Identities

An agent identity is the persistent "person" your agent presents to the outside world. It has a unique handle (like a username), owns its communication channels, an inbox and a phone number, and maintains conversation history across both. Every email your agent sends and every call it makes comes from this single, consistent entity.

Call create_identity() with a handle — a unique slug that identifies the agent in your org. The identity is created immediately, but it has no channels yet. You provision those in the next step.

There are two ways to give an identity a channel: create a new one, or link an existing one.

Create new — use this when spinning up a fresh agent that needs its own address and number. The mailbox and phone number are created and linked to the identity in a single call.

Link existing — use this when you've already provisioned a mailbox or phone number and want to assign it to an identity, or reassign it from one identity to another.

When your agent restarts or you need to rehydrate state, fetch the identity by its handle. get_identity() returns the identity with its current channel state attached.

Identities are long-lived resources. You'll update them as your agents evolve — renaming them, pausing them during off-hours, or retiring them entirely.

Update the handle or status. Setting status to "paused" is useful for temporarily disabling an agent without losing its channels or history.

Unlink a channel when you want to detach it from the identity without deleting it — for example, to reassign the mailbox to a different identity, or to temporarily remove a number.

Delete the identity when the agent is being fully retired. This removes the identity record but does not automatically delete the associated mailbox or phone number.