更新智能体

先调用「创建智能体」，用返回的智能体 ID 替换示例 ID。

POST /agent/v1/agents/{agent_id}◐ 部分支持

请求参数

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可选
智能体名称；省略保持不变，不能传空串清除。
modelstring | object可选
智能体使用的模型：直接写模型名字符串（如 claude-opus-5），或传对象做附加配置（见子字段）。
▸ 展开子字段（5）
- idstring必填
  模型名字符串，如 claude-opus-5。
- effortstring | object可选
  每次推理的思考力度：可传级别字符串（如 high）或 {type: high} 对象。创建时省略取该模型的默认值；更新时省略保持不变。
- inference_geostring可选
  模型推理的地理区域；不传沿用工作区默认。model 是整体替换字段，更新时省略子字段即清除该项。
- speedstring可选
  推理速度模式：fast 出字显著更快但按溢价计费；并非所有模型都支持，不支持的组合在创建时被拒。
- settingsobject可选
  Platform model settings. Only reasoning is supported; other model controls return 400.
systemstring可选
系统提示词；省略保持不变，传空串或 null 清除。
versionnumber可选
智能体当前版本号，用于并发保护：必须与最近一次创建/读取返回的版本一致，否则返回冲突。
metadataobject可选
元数据补丁：键设为字符串即写入，设为 null 即删除；省略该字段保持不变。存储上限 16 个键、每个值 512 字符。
descriptionstring可选
用途说明；省略保持不变，传空串或 null 清除。
mcp_serversarray可选
整体替换的 MCP 服务器列表；省略保持不变，传空数组或 null 清除。
multiagentobject可选◐ 部分支持
多智能体协作拓扑：会话主线程作为协调者，从 agents 名单派生会话线程执行工作。
▸ 展开子字段（2）
- agentsarray必填
  协调者可以派生为会话线程的智能体名单，1–20 项；支持 ID 字符串、{type: agent, id, version?} 和最多一个 {type: self}。创建/更新时固定版本。成员须唯一、存在且未归档，不能自身带 multiagent。每个 coordinator 最多一个 advisor，模型须可用且不同于智能体模型；仅主会话可咨询，每次咨询为独立 advisor 线程，建议以 agent.thread_message_received 返回。
- typestring必填
  拓扑类型，目前只有 coordinator。
  取值 coordinator
skillsarray可选
整体替换的 Skill 列表；省略保持不变，传空数组或 null 清除。
▸ 更多参数（4）
- toolsarray可选
  整体替换的工具配置；省略保持不变，传空数组或 null 清除。
- 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可选
  /agent/v1 扩展：智能体级子智能体默认模型 ID，随修订固定。省略保持，null 清除。调用 model 优先，其次本字段，再其次名册成员模型或内置类型的父会话模型。/anthropic 不接受或返回此字段。
- modelsobject可选
  扩展：可切换模型列表，仅 /agent/v1 支持。
  ▸ 展开子字段（1）
  - allowedarray必填
    必须包含默认模型；创建时省略表示只能使用默认模型。更新时省略保持不变。会话使用其钉住版本的列表。

200

通过 agent_toolset_20260401.configs 逐个开关原生工具并设置权限。未列出的工具遵循 default_config；后台任务、Monitor 和子智能体依赖 bash。version 可用于乐观并发控制，版本冲突返回 409；无变化的更新不增加版本。Skills 尚不支持。更新工具集 permissions 可把允许的同类操作保存到智能体的新版本，供以后的对话使用。 multiagent 接受 null 或 coordinator 名册，1–20 项：智能体 ID、{type:"agent",id,version?} 或最多一个 {type:"self"}。创建/更新时固定版本；成员去重且须存在、未归档、不能自身带 multiagent。名册可启用 Agent，仍需启用 bash；SendMessage 遵循工具配置。每个 coordinator 最多一个 advisor，模型须可用且不同于智能体模型；仅主会话可咨询，每次咨询为独立 advisor 线程，建议以 agent.thread_message_received 返回。 /agent/v1 顶层 subagent_model 是可空模型 ID，随智能体版本保存；省略保留、null 清除。模型须存在。优先级为调用 model > subagent_model > 成员模型（内置类型用父会话模型）。/anthropic 不接受或返回此字段。

错误按 Anthropic 错误格式返回（type / message / request_id），参见错误码

响应

HTTP 200

Successful response

application/json

名称	类型	说明
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>	Skills attached to the agent. Setting skills is not supported on this platform and returns 400, so do not send this field on create or update.
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 and custom tool definitions.
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.