Skip to main content
When someone or something talks to your agent, you choose the karta id. The id tells Karta which durable workspace and memory to resume. In the widget, this is usually userId; in session metadata, it is end_user_id (or its user_id alias). For a virtual employee that works with a team, a backend task singleton, or a fleet member, your backend can set agent_instance_id. That id is the single most consequential thing you set, because: One id is one durable karta - one running agent instance with its own workspace and memory. Create one per user for personal AI assistant use cases, one per team for virtual employee use cases, one singleton for a backend task that may run on a timer, event, or on-demand call, or one per fleet member. Everything the agent accumulates for that id - files, artifacts, conversation history, and any memory it builds up - is keyed on it. Reach it again with the same id and the karta picks up where it left off. Reach it with a different id and you get a fresh karta, remembering nothing. So the id is the switch that selects the agent instance, workspace, and memory. Choosing what it maps to is a product decision. With workspace access enabled, an admin can clone everything a karta has accumulated read-only over git, to inspect or back it up.

​
The mental model: one agent project, many kartas

You deploy one agent project. Karta runs that project as many durable kartas, each keyed by the id you choose:
  • Map the id to your user’s id -> each user-agent relationship gets its own karta with private, accumulating memory.
  • Map the id to a virtual employee id -> many humans can work with the same persistent virtual employee, Jira agent, or shared operations agent. This creates one karta for that virtual employee, not one karta for the whole team.
  • Map several ids to several virtual employees -> one team can operate a roster, such as two Auditor kartas covering different business areas and three Reviewer kartas checking reports from different angles. That roster can include kartas from one agent project or several.
  • Map the id to a fleet member id -> each student, account, project, or system gets its own karta while a supervisor agent coordinates across them.
The project stays the same. The agent instance, files, and memory change with the id.

​
Choosing the grain

Pick the smallest grain that matches your privacy model. If two actors should not see each other’s files, use different ids. If they are meant to share a workspace, share the id deliberately.

​
Identity trust levels

Continuity and trust are separate decisions: Use verified identity when the agent acts on user-specific data or credentials. Use soft or anonymous ids only for continuity.

​
Three rules

1

Grain equals privacy - there is no sub-key

Everyone and everything that shares an id shares one computer. If two people, teams, systems, or fleet members must not see each other’s files or memory, give each their own id. You cannot get finer-grained privacy out of a coarse id - the karta has nothing finer to separate on. For a virtual employee, household, project, or backend task that should share context, share the id deliberately.
2

Use a stable, durable key

The id must stay the same for as long as you want the memory to live. Derive it from something permanent (your internal user id), never from something that changes between visits - a session token, a rotating value, an email that can change. If the id drifts, the old karta is orphaned and the user silently starts over.
3

Treat it as a tenant boundary

The id is a security boundary, not a display label. Make it stable, opaque, and non-guessable, and keep your id spaces from colliding (a team id that happens to equal another user’s id would share their karta). For ids your own server can vouch for, use verified identity so the agent can safely act on per-user data.

​
Throwaway kartas

Sometimes you want no memory at all - a public FAQ bot, or a shared kiosk where the next person must not see the last conversation. Pass the reserved id ephemeral:
Each ephemeral session becomes its own isolated, single-use karta - nothing carries across sessions, and no two ephemeral users ever share state. It behaves like any other karta for the duration of the session, then disappears after the session ends.
ephemeral is different from passing nothing. An anonymous visitor still gets a per-browser id so a reload resumes the same conversation; ephemeral guarantees a fresh, isolated karta every time.

​
Checking your ids are stable

If you intend kartas to be reused but your key is unstable, returning users quietly lose their memory. Your agent’s Overview surfaces a per-karta utility reading, which measures how often a karta is reached more than once. If you expect reuse but the reading shows kartas are almost always one-shot, your id is probably drifting between visits.

​
Inspecting a karta’s files

A karta’s durable files are normally private to the running agent. When you need to see what one has accumulated, an org admin can enable workspace access and clone the karta’s workspace read-only over git - see Clone a karta’s workspace.

​
Next

Widget identity

Anonymous, soft, and verified ids - and how to sign a verified id.

Sessions API

Passing end_user_id in session metadata directly.