Update Agent

Call Create agent first and replace the example agent ID with its returned ID.

POST /agent/v1/agents/{agent_id}◐ Partial

Request parameters

agent_idstring必填
path: Agent id, as returned by agents.create or agents.list (for a session filter, the agent the session was created with). Not the agent name.
namestring可选
Agent name; omit to preserve. Cannot be cleared.
modelstring | object可选
The model powering the agent: a model name string (e.g. claude-opus-5) or an object for extra configuration (see subfields).
▸ 展开子字段（5）
- idstring必填
  The model name string, e.g. claude-opus-5.
- effortstring | object可选
  How hard the model works per inference: a bare level string (e.g. high) or a {type: high} object. On create, omitted resolves the per-model default; on update, omitting preserves it.
- inference_geostring可选
  Geographic region for inference; unset falls through to the workspace default. model is replaced wholesale — omitting the subfield on update clears it.
- speedstring可选
  Inference speed mode: fast generates output notably quicker at premium pricing. Not all models support it; invalid combinations are rejected at create time.
- settingsobject可选
  Platform model settings. Only reasoning is supported; other model controls return 400.
systemstring可选
System prompt; omit to preserve, send an empty string or null to clear.
versionnumber可选
The agent's current version for concurrency control: must match the version returned by the latest create or retrieve, or the call answers a conflict.
metadataobject可选
Metadata patch: set a key to a string to upsert it, or to null to delete it; omit the field to preserve. Up to 16 keys of at most 512 characters.
descriptionstring可选
Description; omit to preserve, send an empty string or null to clear.
mcp_serversarray可选
Full-replacement MCP server list; omit to preserve, send an empty array or null to clear.
multiagentobject可选◐ 部分支持
Multiagent topology: the session's primary thread orchestrates work by spawning session threads drawn from the agents roster.
▸ 展开子字段（2）
- agentsarray必填
  A 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. 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.
- typestring必填
  Topology type; only coordinator today.
  取值 coordinator
skillsarray可选
Full-replacement skill list; omit to preserve, send an empty array or null to clear.
▸ 更多参数（4）
- toolsarray可选
  Full-replacement tool configuration; omit to preserve, send an empty array or null to clear.
- computer_idstring可选
  Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined.
- subagent_modelstring可选
  Own-face extension: revision-pinned default subagent model ID. Omit to preserve; null clears it. Priority: call model, this field, then the roster member model or the parent model for built-ins. Not accepted or returned on the compatibility face.
- modelsobject可选
  Extension: selectable models, available only on /agent/v1.
  ▸ 展开子字段（1）
  - allowedarray必填
    Must include the default model. Omit on creation to allow only the default; omit on update to preserve the list. Sessions use their pinned version’s list.

Returns

200

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.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Response

HTTP 200

Successful response

application/json

Name	Type	Description
id	string	Agent id (agent_...). Pass it as agent when creating a session and as agent_id in agent calls.
archived_at	null \| string	A timestamp in RFC 3339 format
created_at	string	A timestamp in RFC 3339 format
description	null \| string	Free-text description of what the agent is for; null when none was set.
mcp_servers	array<object>	URL MCP servers the agent can call, paired one-to-one with mcp_toolset entries in tools and saved with the agent version. No credentials are stored here.
mcp_servers[].type	string	Always `url`. An MCP server reached over a URL.
mcp_servers[].name	string	Name of the MCP server; the mcp_toolset entry that refers to it uses the same name in mcp_server_name.
mcp_servers[].url	string	http(s) endpoint of the MCP server, at most 2048 characters.
metadata	object	Free-form string key/value pairs stored with the agent for your own bookkeeping.
model	object	Model identifier and configuration.
model.id	string	The model that will power your agent. See models for additional details and options.
model.effort	object	How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
model.inference_geo	string	Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
model.speed	string	Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
model.settings	object	Platform model settings. Only reasoning is supported; other model controls return 400.
multiagent	null \| object	Resolved coordinator topology with a concrete agent roster.
multiagent.agents	array<object>	Agents the coordinator may spawn as session threads, each resolved to a specific version.
multiagent.type	string	Always `coordinator`. The agent coordinates the roster in agents and can delegate to its members.
name	string	Display name of the agent, as set on create or update. It is a label, not a unique key.
skills	array<object>	Skill attachments are not supported: a nonempty skills array returns 400. Omit this field or send an empty array. The native Skill tool loads available runtime skills independently of this field.
skills[].skill_id	string	Id of the skill to attach.
skills[].type	string	Always `anthropic`. A skill provided by Anthropic, identified by skill_id. / Always `custom`. A skill created by you, identified by skill_id.
skills[].version	string	Version of the skill; a string.
system	null \| string	System prompt given to the model at the start of every session of this agent; null when none was set.
tools	array<object>	Tools of the agent: one agent_toolset_20260401 entry for the native tools (all resolved settings are returned, ready to send back on update), plus mcp_toolset entries; custom tool definitions are rejected with 400. Keep bash enabled to use codemode, Skill and subagents.
tools[].configs	array<object> \| array \| null	Per-tool settings that override default_config. Tools that are not listed follow default_config.
tools[].default_config	object \| object \| null	Resolved default configuration for agent tools. / Settings applied to every tool of this toolset that configs does not name. When omitted, tools are enabled with the always_allow policy.
tools[].type	string	Always `agent_toolset_20260401`. The native toolset entry (bash, edit, glob, grep, read, write, web_search, web_fetch, TaskOutput, TaskStop, Monitor, Agent, SendMessage). / Always `mcp_toolset`. An entry that exposes the tools of one MCP server from mcp_servers. / Always `custom`. A custom tool defined by name, description and input_schema; its calls are answered by the client with user.custom_tool_result.
tools[].mcp_server_name	string	Name of the MCP server in mcp_servers whose tools this entry exposes.
tools[].description	string	What the custom tool does and when the model should call it.
tools[].input_schema	object	JSON Schema for custom tool input parameters.
tools[].name	string	Name of the custom tool, as the model sees and calls it.
type	string	Always `agent`. An agent definition.
updated_at	string	A timestamp in RFC 3339 format
version	number	The agent's current version. Starts at 1 and increments when the agent is modified.
computer_id	string	Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined. Omitted when no computer is selected.
subagent_model	string \| null	Praxis extension: default subagent model ID, pinned in the agent revision. Call model overrides this; otherwise it overrides the roster member model or the parent model for built-ins. Null clears the default. /agent/v1 only.
models	object	Praxis extension: switchable model ids on /agent/v1 only. The default model must be included. When omitted, only the default model is selectable.
models.allowed	array<string>	Model ids a session may select with its model field; it must be non-empty and must contain the agent's default model.