User Identities

You may be building a multi-user application with Letta, in which each user is associated with a specific agent. In this scenario, you can use Identities to associate each agent with a user in your application.

Using Identities

Let’s assume that you have an application with multiple users that you’re building on a self-hosted Letta Server or Letta Cloud. Each user has a unique username, starting at user_1, and incrementing up as you add more users to the platform.

To associate agents you create in Letta with your users, you can first create an Identity object with the user’s unique ID as the identifier_key for your user, and then specify the Identity object ID when creating an agent.

For example, with user_1, we would create a new Identity object with identifier_key="user_1" and then pass identity.id into our create agent request:

1
curl -X POST https://app.letta.com/v1/identities/ \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "identifier_key": "user_1",
6
  "name": "Caren",
7
  "identity_type": "user"
8
}'
9
{"id":"identity-634d3994-5d6c-46e9-b56b-56e34fe34ca0","identifier_key":"user_1","name":"Caren","identity_type":"user","project_id":null,"agent_ids":[],"organization_id":"org-00000000-0000-4000-8000-000000000000","properties":[]}
10
curl -X POST https://app.letta.com/v1/agents/ \
11
     -H "Authorization: Bearer <token>" \
12
     -H "Content-Type: application/json" \
13
     -d '{
14
  "memory_blocks": [],
15
  "llm": "anthropic/claude-3-5-sonnet-20241022",
16
  "context_window_limit": 200000,
17
  "embedding": "openai/text-embedding-ada-002",
18
  "identity_ids": ["identity-634d3994-5d6c-46e9-b56b-56e34fe34ca0"]
19
}'

Then, if I wanted to search for agents associated with a specific user (e.g. called user_id), I could use the identifier_keys parameter in the list agents request:

1
curl -X GET "https://app.letta.com/v1/agents/?identifier_keys=user_1" \
2
  -H "Accept: application/json"

You can also create an identity object and attach it to an existing agent. This can be useful if you want to enable multiple users to interact with a single agent:

1
curl -X POST https://app.letta.com/v1/identities/ \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "identifier_key": "user_1",
6
  "name": "Sarah",
7
  "identity_type": "user"
8
  "agent_ids": ["agent-00000000-0000-4000-8000-000000000000"]
9
}'

Using Agent Tags to Identify Users

It’s also possible to utilize our agent tags feature to associate agents with specific users. To associate agents you create in Letta with your users, you can specify a tag when creating an agent, and set the tag to the user’s unique ID. This example assumes that you have a self-hosted Letta Server running on localhost (for example, by running docker run ...).

1
from letta_client import Letta
2
3
# in this example we'll connect to a self-hosted Letta Server
4
client = Letta(base_url="http://localhost:8283")
5
user_id = "my_uuid"
6
7
# create an agent with the user_id tag
8
agent = client.agents.create(
9
    memory_blocks=[],
10
    model="anthropic/claude-3-5-sonnet-20241022",
11
    context_window_limit=200000,
12
    embedding="openai/text-embedding-ada-002",
13
    tags=[user_id]
14
)
15
print(f"Created agent with id {agent.id}, tags {agent.tags}")
16
17
# list agents
18
user_agents = client.agents.list(tags=[user_id])
19
agent_ids = [agent.id for agent in user_agents]
20
print(f"Found matching agents {agent_ids}")

Creating and Viewing Tags in the ADE

You can also modify tags in the ADE. Simply click the Advanced Settings tab in the top-left of the ADE to view an agent’s tags. You can create new tags by typing the tag name in the input field and hitting enter.