创建智能体

POST /agent/v1/agents◐ 部分支持

请求体

namestring必填
智能体名称，1–255 个字符，工作区内可读。
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可选
智能体的系统提示词。
metadataobject可选
自定义元数据键值对，最多 16 个键、每个值最长 512 字符。
descriptionstring可选
智能体的用途说明。
mcp_serversarray可选
智能体连接的 MCP 服务器列表，最多 20 个，名称必须唯一；每个服务器都要被 tools 里的 mcp_toolset 引用，否则整笔请求被拒。
▸ 展开子字段（3）
- typestring必填
  服务器类型，目前只支持 url。
  取值 url
- namestring必填
  MCP 服务器在本列表内的唯一名称，1–255 个字符，供 mcp_toolset 配置引用。
- urlstring必填
  MCP 服务器的端点地址。
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 列表。
toolsarray可选
智能体可用的工具配置，所有工具合计最多 128 个。
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.
▸ 更多参数（2）
- subagent_modelstring可选
  /agent/v1 扩展：智能体级子智能体默认模型 ID，随修订固定。省略保持，null 清除。调用 model 优先，其次本字段，再其次名册成员模型或内置类型的父会话模型。/anthropic 不接受或返回此字段。
- modelsobject可选
  扩展：可切换模型列表，仅 /agent/v1 支持。
  ▸ 展开子字段（1）
  - allowedarray必填
    必须包含默认模型；创建时省略表示只能使用默认模型。更新时省略保持不变。会话使用其钉住版本的列表。

200

agent_toolset_20260401 是原生工具集，包含 bash、edit、glob、grep、read、write、web_search、web_fetch，以及 TaskOutput、TaskStop、Monitor、Agent、SendMessage。新建智能体默认全部启用；configs 可逐个设置 name、enabled、permission_policy，未列出的工具遵循 default_config（默认启用）。后台任务、Monitor 和子智能体依赖 bash；启用任一后台工具时，bash 提供 run_in_background。兼容 API /anthropic 只接受和返回官方 8 个工具，经该入口创建的会话也只注册这 8 个工具。支持文本提示词、模型、元数据与内置工具。model.settings.reasoning 可选 low、medium、high、xhigh、none，为会话提供默认思考档位；会话显式 thinking 优先，不支持的默认值回退到模型 default_effort。示例 model: {id: "deepseek-v4-flash", settings: {reasoning: "high"}}。Skills 及其它额外模型控制尚不支持，传入会返回 400。可在工具集 permissions 中设置 allow、ask、deny 规则，最多共 100 条，用于以后的对话。 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.