# Agent API (/en/docs/api/native/agent)



Agent runs versioned agents and conversations through /agent/v1. Concepts and behavior follow Anthropic Managed Agents (agents, environments, sessions and events), so Anthropic Managed Agents experience applies. Differences: omitting environment\_id selects a light machine unless a Computer is selected, and self-hosted environments are unavailable; the native toolset includes codemode, Skill and subagents, while /anthropic/v1 sessions expose only the eight official tools; nonempty skills attachments and custom tools are rejected; native events include steering, withdrawal, notifications, forks and goals, with remembered permissions and question answers on approvals. Start with `praxis.agent.agents.create`, then open a session and read its events for the result.

## Base URL [#base-url]

<ApiBaseDomain prefix="/agent" />

## Get started [#get-started]

<QuickstartTabs snippets="{&#x22;curl&#x22;:&#x22;curl https://api-origin.invalid/agent/v1/agents \\\n  -H \&#x22;Authorization: Bearer $PRAXIS_API_KEY\&#x22; \\\n  -H \&#x22;Content-Type: application/json\&#x22; \\\n  -d '{\&#x22;name\&#x22;:\&#x22;文档助手\&#x22;,\&#x22;model\&#x22;:\&#x22;deepseek-flash\&#x22;,\&#x22;system\&#x22;:\&#x22;用一句话简短回答。\&#x22;}'&#x22;,&#x22;python&#x22;:&#x22;import os\n\nimport requests\n\nopts = dict(\n    base_url=\&#x22;https://api-origin.invalid/agent\&#x22;,\n    api_key=os.environ[\&#x22;PRAXIS_API_KEY\&#x22;],\n)\n\n# /agent 是我们自己的 Managed Agents 形状，直接发 HTTP 请求（Bearer 认证）\nresp = requests.post(\n    f\&#x22;{opts['base_url']}/v1/agents\&#x22;,\n    headers={\&#x22;Authorization\&#x22;: f\&#x22;Bearer {opts['api_key']}\&#x22;},\n    json={\&#x22;name\&#x22;:\&#x22;文档助手\&#x22;,\&#x22;model\&#x22;:\&#x22;deepseek-flash\&#x22;,\&#x22;system\&#x22;:\&#x22;用一句话简短回答。\&#x22;},\n)\nprint(resp.status_code, resp.json())&#x22;,&#x22;typescript&#x22;:&#x22;\n\nconst opts = {\n  baseURL: \&#x22;https://api-origin.invalid/agent\&#x22;,\n  apiKey: process.env.PRAXIS_API_KEY,\n};\n\n// /agent 是我们自己的 Managed Agents 形状，直接发 HTTP 请求（Bearer 认证）\nconst resp = await fetch(`${opts.baseURL}/v1/agents`, {\n  method: \&#x22;POST\&#x22;,\n  headers: { Authorization: `Bearer ${opts.apiKey}`, \&#x22;Content-Type\&#x22;: \&#x22;application/json\&#x22; },\n  body: JSON.stringify({\&#x22;name\&#x22;:\&#x22;文档助手\&#x22;,\&#x22;model\&#x22;:\&#x22;deepseek-flash\&#x22;,\&#x22;system\&#x22;:\&#x22;用一句话简短回答。\&#x22;}),\n});\nconsole.log(resp.status, await resp.json());&#x22;}" />

See [Agent](/en/docs/cloud/services/agent) for the domain overview; see [Authentication](/en/docs/api/authentication) for how keys work.

## Endpoints [#endpoints]

### Computers (10 endpoints, 10 available) [#computers-10-endpoints-10-available]

| Method | Path                                                                                              | Description                | Support     |
| ------ | ------------------------------------------------------------------------------------------------- | -------------------------- | ----------- |
| POST   | [`/v1/computers`](/docs/api/native/agent/createComputer)                                          | ComputersCreate            | ● Supported |
| GET    | [`/v1/computers`](/docs/api/native/agent/listComputers)                                           | ComputersList              | ● Supported |
| GET    | [`/v1/computers/{computer_id}`](/docs/api/native/agent/retrieveComputer)                          | ComputersRetrieve          | ● Supported |
| POST   | [`/v1/computers/{computer_id}`](/docs/api/native/agent/updateComputer)                            | ComputersUpdate            | ● Supported |
| POST   | [`/v1/computers/{computer_id}/archive`](/docs/api/native/agent/archiveComputer)                   | ComputersArchive           | ● Supported |
| DELETE | [`/v1/computers/{computer_id}`](/docs/api/native/agent/deleteComputer)                            | Delete Archived Computer   | ● Supported |
| GET    | [`/v1/computers/{computer_id}/files`](/docs/api/native/agent/listComputerFiles)                   | ComputersFilesList         | ● Supported |
| GET    | [`/v1/computers/{computer_id}/files/content`](/docs/api/native/agent/retrieveComputerFileContent) | ComputersFilesContent      | ● Supported |
| POST   | [`/v1/computers/{computer_id}/connect`](/docs/api/native/agent/connectComputer)                   | Connect computer           | ● Supported |
| POST   | [`/v1/computers/{computer_id}/attachments`](/docs/api/native/agent/createComputerAttachment)      | Upload Computer Attachment | ● Supported |

### Session resources (4 endpoints, 4 available) [#session-resources-4-endpoints-4-available]

| Method | Path                                                                                                  | Description             | Support   |
| ------ | ----------------------------------------------------------------------------------------------------- | ----------------------- | --------- |
| POST   | [`/v1/sessions/{session_id}/resources`](/docs/api/native/agent/addSessionResource)                    | Add Session Resource    | ◐ Partial |
| GET    | [`/v1/sessions/{session_id}/resources`](/docs/api/native/agent/listSessionResources)                  | List Session Resources  | ◐ Partial |
| GET    | [`/v1/sessions/{session_id}/resources/{resource_id}`](/docs/api/native/agent/retrieveSessionResource) | Get Session Resource    | ◐ Partial |
| DELETE | [`/v1/sessions/{session_id}/resources/{resource_id}`](/docs/api/native/agent/deleteSessionResource)   | Delete Session Resource | ◐ Partial |

### Agents (6 endpoints, 6 available) [#agents-6-endpoints-6-available]

| Method | Path                                                                         | Description         | Support     |
| ------ | ---------------------------------------------------------------------------- | ------------------- | ----------- |
| GET    | [`/v1/agents`](/docs/api/native/agent/listAgents)                            | List Agents         | ● Supported |
| POST   | [`/v1/agents`](/docs/api/native/agent/createAgent)                           | Create Agent        | ◐ Partial   |
| GET    | [`/v1/agents/{agent_id}`](/docs/api/native/agent/retrieveAgent)              | Get Agent           | ● Supported |
| POST   | [`/v1/agents/{agent_id}`](/docs/api/native/agent/updateAgent)                | Update Agent        | ◐ Partial   |
| GET    | [`/v1/agents/{agent_id}/versions`](/docs/api/native/agent/listAgentVersions) | List Agent Versions | ● Supported |
| POST   | [`/v1/agents/{agent_id}/archive`](/docs/api/native/agent/archiveAgent)       | Archive Agent       | ● Supported |

### Sessions & events (16 endpoints, 16 available) [#sessions--events-16-endpoints-16-available]

| Method | Path                                                                                                                   | Description                               | Support     |
| ------ | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------- |
| GET    | [`/v1/sessions`](/docs/api/native/agent/listSessions)                                                                  | List Sessions                             | ◐ Partial   |
| POST   | [`/v1/sessions`](/docs/api/native/agent/createSession)                                                                 | Create Session                            | ◐ Partial   |
| GET    | [`/v1/sessions/{session_id}`](/docs/api/native/agent/retrieveSession)                                                  | Get Session                               | ● Supported |
| POST   | [`/v1/sessions/{session_id}/fork`](/docs/api/native/agent/forkSession)                                                 | Fork Session (Extension)                  | ● Supported |
| GET    | [`/v1/sessions/{session_id}/context`](/docs/api/native/agent/getSessionContext)                                        | Get Session Context (Extension)           | ● Supported |
| GET    | [`/v1/sessions/{session_id}/background_tasks`](/docs/api/native/agent/listSessionBackgroundTasks)                      | List Session Background Tasks (Extension) | ● Supported |
| GET    | [`/v1/sessions/{session_id}/background_tasks/{task_id}/output`](/docs/api/native/agent/getSessionBackgroundTaskOutput) | Get Background Task Output (Extension)    | ● Supported |
| POST   | [`/v1/sessions/{session_id}/background_tasks/{task_id}/stop`](/docs/api/native/agent/stopSessionBackgroundTask)        | Stop Background Task (Extension)          | ● Supported |
| POST   | [`/v1/sessions/{session_id}/compact`](/docs/api/native/agent/compactSession)                                           | Compact Session (Extension)               | ● Supported |
| GET    | [`/v1/sessions/{session_id}/compact/{operation_id}`](/docs/api/native/agent/getSessionCompaction)                      | Get Session Compaction (Extension)        | ● Supported |
| GET    | [`/v1/sessions/{session_id}/compactions`](/docs/api/native/agent/listSessionCompactions)                               | List Session Compactions (Extension)      | ● Supported |
| GET    | [`/v1/sessions/{session_id}/events`](/docs/api/native/agent/listEvents)                                                | List Events                               | ● Supported |
| POST   | [`/v1/sessions/{session_id}/events`](/docs/api/native/agent/sendEvents)                                                | Send Events                               | ◐ Partial   |
| GET    | [`/v1/sessions/{session_id}/events/stream`](/docs/api/native/agent/streamEvents)                                       | Stream Events                             | ◐ Partial   |
| POST   | [`/v1/sessions/{session_id}`](/docs/api/native/agent/updateSession)                                                    | Update Session                            | ◐ Partial   |
| POST   | [`/v1/sessions/{session_id}/archive`](/docs/api/native/agent/archiveSession)                                           | Archive Session                           | ● Supported |

### Session threads (5 endpoints, 5 available) [#session-threads-5-endpoints-5-available]

| Method | Path                                                                                                       | Description          | Support   |
| ------ | ---------------------------------------------------------------------------------------------------------- | -------------------- | --------- |
| GET    | [`/v1/sessions/{session_id}/threads`](/docs/api/native/agent/listSessionThreads)                           | List Threads         | ◐ Partial |
| GET    | [`/v1/sessions/{session_id}/threads/{thread_id}`](/docs/api/native/agent/retrieveSessionThread)            | Get Thread           | ◐ Partial |
| GET    | [`/v1/sessions/{session_id}/threads/{thread_id}/events`](/docs/api/native/agent/listSessionThreadEvents)   | List Thread Events   | ◐ Partial |
| GET    | [`/v1/sessions/{session_id}/threads/{thread_id}/stream`](/docs/api/native/agent/streamSessionThreadEvents) | Stream Thread Events | ◐ Partial |
| POST   | [`/v1/sessions/{session_id}/threads/{thread_id}/archive`](/docs/api/native/agent/archiveSessionThread)     | Archive Thread       | ◐ Partial |

### Environments (5 endpoints, 5 available) [#environments-5-endpoints-5-available]

| Method | Path                                                                                     | Description         | Support   |
| ------ | ---------------------------------------------------------------------------------------- | ------------------- | --------- |
| POST   | [`/v1/environments`](/docs/api/native/agent/createEnvironment)                           | Create Environment  | ◐ Partial |
| POST   | [`/v1/environments/{environment_id}`](/docs/api/native/agent/updateEnvironment)          | Update Environment  | ◐ Partial |
| POST   | [`/v1/environments/{environment_id}/archive`](/docs/api/native/agent/archiveEnvironment) | Archive Environment | ◐ Partial |
| GET    | [`/v1/environments`](/docs/api/native/agent/listEnvironments)                            | List Environments   | ◐ Partial |
| GET    | [`/v1/environments/{environment_id}`](/docs/api/native/agent/retrieveEnvironment)        | Get Environment     | ◐ Partial |

### Toolsets (1 endpoints, 1 available) [#toolsets-1-endpoints-1-available]

| Method | Path                                                  | Description   | Support     |
| ------ | ----------------------------------------------------- | ------------- | ----------- |
| GET    | [`/v1/toolsets`](/docs/api/native/agent/listToolsets) | List Toolsets | ● Supported |

## Differences from Claude Managed Agents [#differences-from-claude-managed-agents]

* This face declares only the 30 listed endpoints, including the toolset catalog, context snapshot, compaction operations and background tasks: the other official Managed Agents operations are not on this face and answer 404. For Anthropic-protocol compatible access use the /anthropic compat face, where operations the platform has not implemented answer 501 (not\_implemented\_error) with no side effects.
* <a href="/docs/api/native/agent/createEnvironment">Create Environment</a>：Supports tenant-owned cloud environments, configuration updates and soft archival; built-ins are read-only. Lists accept limit, page and include\_archived. Limited networking applies at sandbox creation; package installation failure terminates the session with ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED. self\_hosted, scope and cross-session package caching are not supported.
* <a href="/docs/api/native/agent/updateEnvironment">Update Environment</a>：Supports tenant-owned cloud environments, configuration updates and soft archival; built-ins are read-only. Lists accept limit, page and include\_archived. Limited networking applies at sandbox creation; package installation failure terminates the session with ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED. self\_hosted, scope and cross-session package caching are not supported.
* <a href="/docs/api/native/agent/archiveEnvironment">Archive Environment</a>：Supports tenant-owned cloud environments, configuration updates and soft archival; built-ins are read-only. Lists accept limit, page and include\_archived. Limited networking applies at sandbox creation; package installation failure terminates the session with ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED. self\_hosted, scope and cross-session package caching are not supported.
* <a href="/docs/api/native/agent/createComputer">ComputersCreate</a>：Praxis extension: MA only has session-scoped temporary containers and memory\_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment\_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox\_id. Lists include archived computers.
* <a href="/docs/api/native/agent/listComputers">ComputersList</a>：Praxis extension: MA only has session-scoped temporary containers and memory\_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment\_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox\_id. Lists include archived computers.
* <a href="/docs/api/native/agent/retrieveComputer">ComputersRetrieve</a>：Praxis extension: MA only has session-scoped temporary containers and memory\_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment\_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox\_id. Lists include archived computers.
* <a href="/docs/api/native/agent/updateComputer">ComputersUpdate</a>：Praxis extension: MA only has session-scoped temporary containers and memory\_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment\_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox\_id. Lists include archived computers.
* <a href="/docs/api/native/agent/archiveComputer">ComputersArchive</a>：Praxis extension: MA only has session-scoped temporary containers and memory\_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment\_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox\_id. Lists include archived computers.
* <a href="/docs/api/native/agent/deleteComputer">Delete Archived Computer</a>：Own-face superset: Managed Agents has no persistent Computer deletion lifecycle. Only archived computers can be deleted. Active computers return 400 COMPUTER\_ACTIVE (archive first). Destroy storage before removing registration. Success returns id and type=computer\_deleted; missing or foreign computers return 404.
* <a href="/docs/api/native/agent/listComputerFiles">ComputersFilesList</a>：Praxis extension: MA only has session-scoped temporary containers and memory\_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment\_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox\_id. Lists include archived computers.
* <a href="/docs/api/native/agent/retrieveComputerFileContent">ComputersFilesContent</a>：Praxis extension: MA only has session-scoped temporary containers and memory\_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment\_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox\_id. Lists include archived computers.
* <a href="/docs/api/native/agent/connectComputer">Connect computer</a>：Own-face extension: Managed Agents has no persistent Computer connection. Returns the public SDK sandbox\_id, envd\_access\_token and template\_id. Archived computers remain accessible; foreign or absent computers return 404. Never cache credentials.
* <a href="/docs/api/native/agent/createComputerAttachment">Upload Computer Attachment</a>：Own-face superset: Managed Agents has no persistent Computer attachment directory. User uploads overwrite the same name; agents retain read-only access. Run-token uploads return 403 READ\_ONLY. name is one filename of at most 255 UTF-8 bytes; MIME is inferred from the extension; custom Content-Type is not persisted and digest may be absent. Limit 16 MiB (413); invalid names return 400. Archived computers accept uploads; foreign computers return 404.
* <a href="/docs/api/native/agent/addSessionResource">Add Session Resource</a>：Supports persistence, retrieval and removal of file resource references, up to 500 per session. Files must be live and owned by the current tenant. Paths default to /mnt/session/uploads/\<file\_id>; custom paths are rooted there and parent traversal is rejected. File content is immutable through this API. Sandbox synchronization is not implemented in this batch.
* <a href="/docs/api/native/agent/listSessionResources">List Session Resources</a>：Supports persistence, retrieval and removal of file resource references, up to 500 per session. Files must be live and owned by the current tenant. Paths default to /mnt/session/uploads/\<file\_id>; custom paths are rooted there and parent traversal is rejected. File content is immutable through this API. Sandbox synchronization is not implemented in this batch.
* <a href="/docs/api/native/agent/retrieveSessionResource">Get Session Resource</a>：Supports persistence, retrieval and removal of file resource references, up to 500 per session. Files must be live and owned by the current tenant. Paths default to /mnt/session/uploads/\<file\_id>; custom paths are rooted there and parent traversal is rejected. File content is immutable through this API. Sandbox synchronization is not implemented in this batch.
* <a href="/docs/api/native/agent/deleteSessionResource">Delete Session Resource</a>：Supports persistence, retrieval and removal of file resource references, up to 500 per session. Files must be live and owned by the current tenant. Paths default to /mnt/session/uploads/\<file\_id>; custom paths are rooted there and parent traversal is rejected. File content is immutable through this API. Sandbox synchronization is not implemented in this batch.
* <a href="/docs/api/native/agent/createAgent">Create Agent</a>：agent\_toolset\_20260401 is the native toolset: bash, edit, glob, grep, read, write, web\_search, web\_fetch, TaskOutput, TaskStop, Monitor, Agent and SendMessage. New agents enable all tools by default. Configure each tool through name, enabled and permission\_policy in configs; omitted tools follow default\_config (enabled by default). Background tasks, Monitor and subagents require bash. Enabling any background tool exposes bash run\_in\_background. The /anthropic compatibility API accepts and returns only the eight official tools, and sessions created there receive only those tools. Supports text prompts, models, metadata and built-in tools. Optional model.settings.reasoning accepts low, medium, high, xhigh or none as the session default. Explicit session thinking takes precedence; unsupported agent defaults fall back to the model default\_effort. Example model: \{id: "deepseek-v4-flash", settings: \{reasoning: "high"}}. Skills and other additional model controls are not supported and return 400. Set up to 100 allow, ask and deny rules in toolset permissions for future conversations. multiagent accepts null or a coordinator roster of 1–20 agent IDs, \{type:"agent",id,version?} references or at most one \{type:"self"}. Versions are pinned on create/update. Members must be distinct, exist, be unarchived and have no multiagent topology. A roster can enable Agent while bash is enabled; SendMessage follows its tool configuration. Each coordinator permits at most one advisor whose model must be available and differ from the agent model; only the primary session can consult it, each consultation uses a separate advisor thread, and advice returns via agent.thread\_message\_received. The /agent/v1 top-level subagent\_model is a nullable model ID stored in each revision: omit to preserve, null to clear. The model must exist. Priority: call model > subagent\_model > roster member model (parent session model for built-ins). /anthropic neither accepts nor returns this field.
* <a href="/docs/api/native/agent/retrieveAgent">Get Agent</a>：tools returns all resolved native tool configurations in one agent\_toolset\_20260401 entry, ready for an update round trip. Replace example resource IDs with IDs from resources you created.
* <a href="/docs/api/native/agent/updateAgent">Update Agent</a>：Use agent\_toolset\_20260401.configs to enable each native tool and set its permission policy. Omitted tools follow default\_config; background tasks, Monitor and subagents require bash. Use version for optimistic concurrency; conflicts return 409 and unchanged updates preserve the version. Skills are not supported. Update toolset permissions to save allowed operations in a new agent version for future conversations. multiagent accepts null or a coordinator roster of 1–20 agent IDs, \{type:"agent",id,version?} references or at most one \{type:"self"}. Versions are pinned on create/update. Members must be distinct, exist, be unarchived and have no multiagent topology. A roster can enable Agent while bash is enabled; SendMessage follows its tool configuration. Each coordinator permits at most one advisor whose model must be available and differ from the agent model; only the primary session can consult it, each consultation uses a separate advisor thread, and advice returns via agent.thread\_message\_received. The /agent/v1 top-level subagent\_model is a nullable model ID stored in each revision: omit to preserve, null to clear. The model must exist. Priority: call model > subagent\_model > roster member model (parent session model for built-ins). /anthropic neither accepts nor returns this field.
* <a href="/docs/api/native/agent/listAgentVersions">List Agent Versions</a>：Replace example resource IDs with IDs from resources you created.
* <a href="/docs/api/native/agent/archiveAgent">Archive Agent</a>：Archived agents remain readable, including versions, but cannot be updated. Only archive your own test agent.
* <a href="/docs/api/native/agent/listSessions">List Sessions</a>：Supports limit, page and agent\_id. agent\_version, time ranges, deployment\_id, memory\_store\_id, include\_archived, order and statuses are not supported and return 400.
* <a href="/docs/api/native/agent/createSession">Create Session</a>：Create with optional model (an ID string in models.allowed; only the default if no list) and thinking (\{effort: "low|medium|high|xhigh|none"} or null), saved before initial\_events execute. Omitted or null thinking inherits the agent default, then the model default. Efforts must be in model.thinking.efforts; none requires can\_disable. Invalid selections return 400 invalid\_request\_error. The response includes thinking and model.thinking: \{efforts, can\_disable, default\_effort}; unknown capability and an unspecified default\_effort are null. Example: \{"agent":"agent\_123", "model":"deepseek-v4-flash","thinking":\{"effort":"xhigh"}}. These selection fields belong only to /agent/v1. Create an agent first and replace agent\_123 with its returned id. Omit environment\_id to get a light machine, unless an explicit or agent-default computer\_id selects a Computer. Select node22 or a tenant-owned cloud environment for a sandbox recipe. Responses omit environment\_id when no recipe is selected. Inline agent overrides, budgets and vaults are not supported. File resources are persisted, up to 500 per session; sandbox synchronization is not implemented in this batch.
* <a href="/docs/api/native/agent/retrieveSession">Get Session</a>：Replace example resource IDs with IDs from resources you created.
* <a href="/docs/api/native/agent/forkSession">Fork Session (Extension)</a>：Available only on /agent/v1. Use the message\_id field from own-face events, not the event id. Copies every message and part through the target, including tool calls and results. The parent is unchanged; another running turn does not prevent forking an earlier completed turn. The new root session appears in the session list with the same agent version, current model and thinking settings, and cwd working directory. Its title is the parent title plus “ 的分支”. If the parent has a sandbox, the new session owns an independent fork including a memory snapshot. Inherited running tasks are terminated, ring targets are replaced with the new session only, and its background-task table starts empty. Without a parent sandbox, creation remains lazy. Returns 201 with the same Session shape as retrieval. forked\_from is \{session\_id, message\_id}, or null for ordinary sessions. Imported history ends with session.forked containing forked\_from\_session\_id and forked\_from\_message\_id. These fields and this event are own-face only. Invalid requests return 400; ineligible targets return 409 FORK\_TARGET\_INVALID; missing sessions or sessions belonging to another caller return 404. Initialization failures leave the child unpublished and reclaim the forked sandbox.
* <a href="/docs/api/native/agent/getSessionContext">Get Session Context (Extension)</a>：Praxis extension available only on /agent/v1, following Claude Agent SDK getContextUsage() with snake\_case fields. detail is summary: the latest actual model usage takes precedence, and local estimates apportion source totals; used categories sum to total\_tokens. Only nonzero sources appear. Classify rows by kind (used/free/buffer/deferred). key is a stable source identifier extension; clients must tolerate unknown keys and new sources, falling back to name. MCP tools group by server, plugin blocks by id, and compaction summaries are counted separately. excluded\_items is currently zero. Before measurement, total\_tokens, total\_tokens\_source and measured\_at are null, categories is empty, and details are zero or empty arrays. Model selection recalculates max\_tokens, auto\_compact\_threshold and free/buffer while preserving the latest measurement. is\_auto\_compact\_enabled is false for unknown capacity or a tripped compaction breaker. For example model.thinking is \{efforts: \[high, xhigh], can\_disable: true, default\_effort: high}. model.thinking contains efforts, can\_disable and nullable default\_effort; the entire thinking value is null when capability is unknown. Missing or inaccessible sessions return 404.
* <a href="/docs/api/native/agent/listSessionBackgroundTasks">List Session Background Tasks (Extension)</a>：Own-face extension. Returns \{ data: BackgroundTask\[] }. Each task has id, kind, title, thread\_id, status, started\_at, ended\_at, cancellable, notified\_at and trigger\_count. Subagent rows link to their child thread via thread\_id; other kinds have null. kind is an open string; tolerate unknown kinds. Status is running, result\_pending, completed, failed, cancelled or lost. Only completed tasks with pending delivery are result\_pending. Timestamps are RFC3339; ended\_at is null while running. notified\_at is the admission time of the latest system notification batch, or null. trigger\_count counts admitted monitor event batches, or is null without records and for other kinds. Only supported running tasks without stop intent are cancellable. Missing or inaccessible sessions return 404.
* <a href="/docs/api/native/agent/getSessionBackgroundTaskOutput">Get Background Task Output (Extension)</a>：Own-face extension. offset defaults to 0; max\_bytes defaults to 65536 and must be between 1 and 262144. Returns text, next\_offset and eof. Offsets count UTF-8 bytes, not characters; partial trailing characters are retained for the next read. eof describes the current log, which may grow while running. A paused or missing sandbox returns empty text, the original offset, eof=true and unavailable=true, without waking it. Reading does not acknowledge model result delivery. Missing or inaccessible sessions or tasks return 404; invalid ranges return 400.
* <a href="/docs/api/native/agent/stopSessionBackgroundTask">Stop Background Task (Extension)</a>：Own-face extension. No request body is required. Uses the same stop implementation as TaskStop: records stop\_requested\_at and signals the process group. Returns BackgroundTask with the same fields as the list operation. Until termination is observed, status may remain running with cancellable=false. An ended or unsupported task returns 409. Missing or inaccessible sessions or tasks return 404.
* <a href="/docs/api/native/agent/compactSession">Compact Session (Extension)</a>：Available only on /agent/v1. The body may be omitted or \{}. Optional instructions must be a string and is forwarded unchanged. Idempotency-Key is forwarded unchanged; a UUID is generated when absent. Returns \{ type: session\_compaction, id, status, reason? }, where id is the operation ID. queued/running return 202; skipped/succeeded/failed return 200. Non-string instructions return 400 invalid\_request\_error. Missing or inaccessible managed sessions return 404 not\_found\_error.
* <a href="/docs/api/native/agent/getSessionCompaction">Get Session Compaction (Extension)</a>：Available only on /agent/v1. Returns \{ type: session\_compaction, id, status, reason? } with HTTP 200 for every status. A missing operation or inaccessible session returns 404 not\_found\_error.
* <a href="/docs/api/native/agent/listSessionCompactions">List Session Compactions (Extension)</a>：Available only on /agent/v1. Returns \{ data: \[...] }. Each entry contains type, id, event\_id, trigger, status, model, compacted\_message\_count, input\_tokens\_before, input\_tokens\_after, summary, error and created\_at, as recorded by the service. Missing or inaccessible managed sessions return 404 not\_found\_error.
* <a href="/docs/api/native/agent/listEvents">List Events</a>：Send a message before reading history. Until processing finishes, only admitted input may be visible. Pagination, event type and time filters are supported. A session waiting for tool approval pauses on session.status\_idle with stop\_reason requires\_action, whose event\_ids list the agent.tool\_use events to confirm. A failed run emits session.error before session.status\_terminated. agent.thinking carries the thinking text in content. When searching or reading web pages, tool results use official search\_result blocks on both API surfaces. Answer text blocks carry citations as an /agent/v1 extension; /anthropic renders answer references as \[n] in the text.
* <a href="/docs/api/native/agent/sendEvents">Send Events</a>：Each user.message accepts exactly one nonempty text block. Replace sesn\_123 with your session id. Text user.message, user.interrupt and tool confirmation are supported. To guide a running turn, send a user.steer event with event\_id referencing a queued user.message. Current tools continue; the message enters the next model request. The user.steer receipt has its own processed\_at; repeated marking returns the same receipt. Processing or withdrawn inputs return 409; missing events return 404. Pending approvals defer injection. If the turn ends first, the input runs normally from the queue. Ordinary messages remain queued by default. This extension is unavailable on /anthropic. The response acknowledges inputs; read replies from event history or the stream. A user.message sent while the session waits for tool approval is queued: the returned event has processed\_at null and runs in order once the approval is resolved. When allowing a tool call, copy its permission\_suggestions into updated\_permissions to remember similar operations for this conversation; dangerous operations offer no suggestions to remember. When searching or reading web pages, tool results use official search\_result blocks on both API surfaces. Answer text blocks carry citations as an /agent/v1 extension; /anthropic renders answer references as \[n] in the text.
* <a href="/docs/api/native/agent/streamEvents">Stream Events</a>：Keep the SSE connection open and send a message in another request after replacing sesn\_123. Stopping the stream disconnects the subscription, not the agent. SDK 0.124.0 filters session.usage; read history for full usage. Pass event\_deltas\[]=agent.message or event\_deltas\[]=agent.thinking to receive incremental previews (event\_start and event\_delta) before the final event. Pass event\_deltas\[]=agent.tool\_use to receive input\_json\_delta fragments while tool arguments are being generated. When searching or reading web pages, tool results use official search\_result blocks on both API surfaces. Answer text blocks carry citations as an /agent/v1 extension; /anthropic renders answer references as \[n] in the text.
* <a href="/docs/api/native/agent/updateSession">Update Session</a>：Optional model is an ID in the pinned version allowed list; thinking is \{effort: "low|medium|high|xhigh|none"} or null. Omission preserves the selection; null restores inheritance. A model-only change clears unsupported session thinking. Combined updates validate against the new model; invalid choices return 400 and preserve the previous selection. Changes affect the next turn, not an in-flight turn. Example: \{"model":"deepseek-v4-flash","thinking":\{"effort":"xhigh"}}. Responses include thinking and model.thinking: \{efforts, can\_disable, default\_effort}; unknown capability is null. These fields are available only on /agent/v1. Supports title and metadata with the official patch semantics: a string value upserts the key, null deletes it, a whole-null object clears the bag, and untouched keys are preserved. The official agent override (tools/mcp\_servers), budget and vault\_ids are not supported and return 400 naming the field. Updating an archived session returns 409.
* <a href="/docs/api/native/agent/archiveSession">Archive Session</a>：Archived sessions refuse new messages with 400 invalid\_request\_error naming the archived session; retrieval and event history stay readable. Re-archiving is idempotent and archived\_at keeps the first archive time.
* <a href="/docs/api/native/agent/listSessionThreads">List Threads</a>：Returns the primary thread and every child thread in created\_at order. Thread ids use sthr\_ plus the owning session suffix; children reference the primary parent\_thread\_id and retain the parent session\_id. agent describes the actual running definition; built-in types use their type name and null for unregistered id/version. Archived children have status terminated and archived\_at. stats/usage remain null without thread-level tracking.
* <a href="/docs/api/native/agent/retrieveSessionThread">Get Thread</a>：Returns a primary or child thread belonging to this session, field-for-field identical to its list item. Foreign, unknown and malformed thread ids uniformly return 404 without revealing existence.
* <a href="/docs/api/native/agent/listSessionThreadEvents">List Thread Events</a>：Reads the selected thread ledger: the primary session for the primary thread, or the child session for a child thread. Uses the session event query parameters, public event types and data + next\_page envelope. Web tools return search\_result blocks on both APIs; answer citations are an /agent/v1 extension, rendered as \[n] on /anthropic.
* <a href="/docs/api/native/agent/streamSessionThreadEvents">Stream Thread Events</a>：Subscribes to the selected thread live ledger using the session SSE implementation; the /agent API also supports a read-only WebSocket. The parent stream includes child creation, status and message events. Child approvals carry session\_thread\_id; confirmations and interrupts targeting that id are routed to the owned child.
* <a href="/docs/api/native/agent/archiveSessionThread">Archive Thread</a>：Archiving the primary thread uses session archival. Archiving a child archives only that child session, leaving the parent and siblings intact. Archived children have status terminated and archived\_at; their history remains readable.
* <a href="/docs/api/native/agent/listEnvironments">List Environments</a>：Supports tenant-owned cloud environments, configuration updates and soft archival; built-ins are read-only. Lists accept limit, page and include\_archived. Limited networking applies at sandbox creation; package installation failure terminates the session with ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED. self\_hosted, scope and cross-session package caching are not supported.
* <a href="/docs/api/native/agent/retrieveEnvironment">Get Environment</a>：Supports tenant-owned cloud environments, configuration updates and soft archival; built-ins are read-only. Lists accept limit, page and include\_archived. Limited networking applies at sandbox creation; package installation failure terminates the session with ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED. self\_hosted, scope and cross-session package caching are not supported.
* <a href="/docs/api/native/agent/listToolsets">List Toolsets</a>：Returns toolset descriptions, plugin names and versions, and each tool’s name, description, input schema, read-only status and default permission policy. Available at /agent/v1/toolsets. Reading the catalog does not change agent configuration. agent\_toolset\_20260401 contains all 13 native tools. TaskOutput, TaskStop, Monitor, Agent and SendMessage support individual enablement and permission policies and require bash. The compatibility API provides only the eight official tools.

For native tools and parameters, use these endpoint pages and `/meta/v1/openapi.yaml`; the [Claude Managed Agents documentation](https://platform.claude.com/docs/en/managed-agents/overview) describes the official fields supported by the compatibility API.

Errors follow the Anthropic error format (type / message / request\_id), see [errors](/docs/api/errors); quotas and response headers are covered in [rate limits](/docs/api/rate-limits).