Agents and sessions
Understand configuration versions, sessions, environments, events, and identity boundaries.
An agent is a reusable configuration. A session is a separate conversation running with that configuration. Keeping these objects distinct helps you determine who a configuration change affects, where to send a message, and how to recognize completion.
Configuration and execution objects
| Object | Contains | Creation and use |
|---|---|---|
| Agent | Model, instructions, tools, MCP configuration, and a version | Creation returns an agent_… ID that multiple sessions can reuse |
| Session | A pinned version, message and tool events, execution state | Create it from an agent ID or versioned reference, then send input to it |
| Environment | Machine configuration for a session | Select an environment for sandbox execution; basic API sessions can omit it |
| Event | User input, replies, tool execution, and status changes | Submit input events; read history or subscribe to the event stream |
| vault | Credentials for accessing tool services | Manage separately from instructions; prompts cannot enforce credential access |
Service agents use a separate execution environment for each session. Personal agents bind to a persistent computer for tasks that retain a working directory. Choose the kind at creation. The API quickstart uses a service agent and needs no personal computer.
Versions and the session lifecycle
Saving agent configuration creates a new version. When creating a session, agent can be an ID string to select the latest version at that moment. Alternatively, pass { type: "agent", id, version } to choose explicitly. The session pins that configuration; later agent edits do not upgrade existing sessions.
A session can be idle, running, rescheduling, or terminated. An idle session has no task currently running and can accept another message. A terminated session cannot continue. Archiving is separate: you can still read the record, but cannot send more messages. Decide whether you need to retain history or stop accepting input before cleaning up records.
A successful user.message response only acknowledges input. Read agent.message for the reply and a subsequent session.status_idle to confirm that the turn became idle. If a tool needs approval, handle the pending confirmation event. Waiting for a decision does not mean the API has stopped responding.
Environment and identity boundaries
An API session uses a light machine when environment_id is omitted and no computer is selected. Choosing an environment selects its sandbox configuration. That configuration is fixed when the session is created. File and tool capabilities depend on configuration; the word “environment” does not imply support for arbitrary runtimes.
Keep organization API Keys on your server. Customer-facing pages use embed tokens. Your backend derives external_user_id from verified sign-in state and issues a token for the selected agent. The token scopes access to an agent, version, and end user. A user ID supplied by the browser is not verified identity.
Public documentation Q&A can use a publishable key to obtain anonymous visitor tokens. The same browser storage preserves the visitor identity. This is not a signed-in account and grants no access to private orders. When users change, destroy the old component and obtain fresh credentials; clearing the message list is insufficient.
Tool confirmation records whether the user agrees to an operation. Your business service must still validate the caller's credential and the user's access to each resource. Page context, model-generated arguments, and an approval button cannot replace that check. Instructions and context are also unsuitable for secrets.
Choose your next step
Use Run your first agent to verify the API. Read Configure an agent to change configuration or select an embed version. The API reference defines creation and update fields.
For customer products, choose a delivery format, then connect identity through Embed tokens and users. Investigate execution through Sessions and usage, then apply Limits and errors.