Agent API

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

Get started

Loading…

See Agent for the domain overview; see Authentication for how keys work.

Endpoints

Computers (10 endpoints, 10 available)

Session resources (4 endpoints, 4 available)

Agents (6 endpoints, 6 available)

Sessions & events (16 endpoints, 16 available)

Session threads (5 endpoints, 5 available)

Environments (5 endpoints, 5 available)

Toolsets (1 endpoints, 1 available)

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.
• Create Environment：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.
• Update Environment：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.
• Archive Environment：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.
• ComputersCreate：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.
• ComputersList：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.
• ComputersRetrieve：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.
• ComputersUpdate：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.
• ComputersArchive：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.
• Delete Archived Computer：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.
• ComputersFilesList：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.
• ComputersFilesContent：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.
• Connect computer：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.
• Upload Computer Attachment：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.
• Add Session Resource：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.
• List Session Resources：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.
• Get Session Resource：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.
• Delete Session Resource：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.
• Create Agent：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.
• Get Agent：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.
• Update Agent：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.
• List Agent Versions：Replace example resource IDs with IDs from resources you created.
• Archive Agent：Archived agents remain readable, including versions, but cannot be updated. Only archive your own test agent.
• List Sessions：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.
• Create Session：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.
• Get Session：Replace example resource IDs with IDs from resources you created.
• Fork Session (Extension)：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.
• Get Session Context (Extension)：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.
• List Session Background Tasks (Extension)：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.
• Get Background Task Output (Extension)：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.
• Stop Background Task (Extension)：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.
• Compact Session (Extension)：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.
• Get Session Compaction (Extension)：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.
• List Session Compactions (Extension)：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.
• List Events：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.
• Send Events：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.
• Stream Events：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.
• Update Session：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.
• Archive Session：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.
• List Threads：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.
• Get Thread：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.
• List Thread Events：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.
• Stream Thread Events：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.
• Archive Thread：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.
• List Environments：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.
• Get Environment：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.
• List Toolsets：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 describes the official fields supported by the compatibility API.

Errors follow the Anthropic error format (type / message / request_id), see errors; quotas and response headers are covered in rate limits.