Agent 结构

Agent 对象

创建、列表、更新、归档，以及不带 version 参数的 GET /api/v1/cloud/agents/{agent_id} 会返回该结构。

字段	类型	说明
`id`	string	Agent ID，前缀为 `agent_`
`type`	string	固定值 `"agent"`
`name`	string	Agent 名称，长度 1-256 字符
`description`	string	Agent 描述，最长 2048 字符
`model`	string \| object	模型标识。可传 string 表示模型 ID，或传 Agent model 对象以同时配置 `effort` 与 `context_window`
`system`	string	系统提示词，最长 100000 字符
`tools`	Agent tool 数组	工具配置列表，最多 128 个，默认 `[]`
`mcp_servers`	MCP server 数组	MCP server 列表，最多 20 个，默认 `[]`
`skills`	Skill binding 数组	Skill 绑定列表，最多 20 个，默认 `[]`
`metadata`	object	Metadata 对象，默认 `{}`
`multiagent`	Multiagent \| null	Agents 配置；未设置时返回 `null`
`version`	integer	当前 Agent 版本号，从 `1` 开始
`archived_at`	string \| null	UTC 归档时间；未归档时为 `null`
`created_at`	string	UTC 创建时间
`updated_at`	string	UTC 最后更新时间

Agent version snapshot

带 version 参数的 GET /api/v1/cloud/agents/{agent_id} 和 GET /api/v1/cloud/agents/{agent_id}/versions 会返回该结构。

字段	类型	说明
`id`	string	Agent ID，前缀为 `agent_`
`type`	string	固定值 `"agent"`
`name`	string	Agent 名称
`description`	string	Agent 描述
`model`	string \| object	模型标识；形态与 Agent 对象一致，详见 Agent model
`system`	string	系统提示词
`tools`	Agent tool 数组	工具配置列表
`mcp_servers`	MCP server 数组	MCP server 列表
`skills`	Skill binding 数组	Skill 绑定列表
`metadata`	object	Metadata 对象
`multiagent`	Multiagent \| null	Agents 配置
`version`	integer	当前快照对应的版本号
`archived_at`	string \| null	UTC 归档时间；该快照未归档时为 `null`
`created_at`	string	Agent 的 UTC 创建时间
`updated_at`	string	该快照对应的 UTC 最后更新时间

Agent model

Agent 的 model 字段支持两种等价形态：

String 简写：直接传模型 ID，例如 "ultimate"。
Object 形态：包含 id 和可选的调优字段。

字段	类型	必填	说明
`id`	string	是	模型标识；可通过列出模型查询可用值
`effort`	string	否	Reasoning effort 等级。可选值：`none`、`low`、`medium`、`high`、`xhigh`、`max`。各模型实际支持的等级见列出模型返回的 `efforts` 数组
`context_window`	integer	否	期望的上下文窗口（token 数，正整数）。取值请从列出模型返回的 `available_context_windows` 中选择

响应会按请求提交的形态回显：以 string 提交则 model 返回 string；以对象提交则返回对象并保留调优字段。版本快照（GET /api/v1/cloud/agents/{agent_id}?version=N）也是同样的形态。 Session 响应会在嵌入的 Agent 中额外返回只读的 effective_context_window（位于 agent.model 内），详见 Session 数据结构。

Agent tool

tools[] 通过 type 区分不同结构。

字段	类型	适用类型	说明
`type`	string	全部	必填。可选值：`agent_toolset_20260401`、`mcp_toolset`、`custom`
`enabled_tools`	string 数组	`agent_toolset_20260401`	内置工具白名单。非空数组表示严格白名单；省略或传 `[]` 时使用默认内置工具集，并继续叠加 `disallowed_tools` 和 `configs[].enabled`。取值必须使用下方列出的内置工具名
`disallowed_tools`	string 数组	`agent_toolset_20260401`	要隐藏并拒绝的内置工具，取值必须使用下方列出的内置工具名。同一工具不能同时出现在 `enabled_tools` 和 `disallowed_tools`
`configs`	Tool config 数组	`agent_toolset_20260401`、`mcp_toolset`	单工具启用状态和权限规则。逐个工具的权限在这里通过 `permission_policy` 配置
`mcp_server_name`	string	`mcp_toolset`	必填。必须匹配某个 `mcp_servers[].name`
`name`	string	`custom`	必填的自定义工具名。不能与内置工具重名，也不能以 `mcp__` 开头
`description`	string	`custom`	必填的自定义工具描述
`input_schema`	object	`custom`	必填的 JSON Schema 对象，`input_schema.type` 必须为 `"object"`

custom 工具不支持 permission_policy；权限需要通过 agent_toolset_20260401 或 mcp_toolset 的 configs[].permission_policy 配置。

内置工具名

支持以下内置工具名：

工具名
`Bash`
`DeliverArtifacts`
`Edit`
`Glob`
`Grep`
`ImageGen`
`ImageSearch`
`Read`
`WebFetch`
`WebSearch`
`Write`

Tool config

用于 tools[].configs[]。

字段	类型	必填	说明
`name`	string	是	要配置的工具名。`agent_toolset_20260401` 使用内置工具名；`mcp_toolset` 使用该 MCP server 暴露的原始工具名
`enabled`	boolean	否	`false` 表示隐藏并拒绝该工具；`true` 表示显式启用该工具
`permission_policy`	Permission policy	否	该工具的运行时权限行为

Permission policy

字段	类型	必填	说明
`type`	string	是	可选值：`always_allow`、`always_ask`、`always_deny`

always_allow 表示直接执行；always_ask 表示暂停并等待 user.tool_confirmation；always_deny 表示返回被拒绝的工具结果。

MCP server

用于 mcp_servers[]。

字段	类型	必填	说明
`name`	string	是	Agent 内唯一的 MCP server 名称
`type`	string	是	支持值：`"url"`
`url`	string	是	Streamable HTTP MCP endpoint URL

MCP server 鉴权通过 Vault 配置。

Skill binding

用于 skills[]。

字段	类型	必填	说明
`type`	string	是	可选值：`qoder`、`custom`
`skill_id`	string	是	Skill 标识
`version`	string	否	可选的非空版本字符串

Multiagent

用于 Agent 的 multiagent 字段，配置 Agents 能力。设置后，运行时会自动注入 coordinator 控制工具（create_agent、send_to_agent、list_agents、Agent）。

使用 multiagent 时，tools 中必须包含 agent_toolset_20260401 类型的工具配置项。

字段	类型	必填	说明
`type`	string	是	必须为 `"coordinator"`
`agents`	Multiagent agent entry 数组	是	可委派的 Agent 花名册，1-20 个唯一条目

Multiagent agent entry

multiagent.agents[] 支持三种格式： 对象格式：

字段	类型	必填	说明
`type`	string	是	`"agent"` 引用其他 Agent；`"self"` 引用 coordinator 自身
`id`	string	条件必填	Agent ID。`type` 为 `"agent"` 时必填
`version`	integer	否	指定 Agent 版本号；省略时使用最新 active 版本。支持正整数或正整数字符串
`name`	string	否	子 Agent 显示名称

字符串简写：直接传 Agent ID 字符串，等价于 {"type": "agent", "id": "<value>"}。示例：

{
  "type": "coordinator",
  "agents": [
    {"type": "agent", "id": "agent_019f00000001", "name": "Research Agent"},
    {"type": "agent", "id": "agent_019f00000002", "version": 3},
    {"type": "self"},
    "agent_019f00000003"
  ]
}

定义 Agent

创建可复用、可版本化的 Agent 配置。

快速上手

构建 Agent

配置 Agent 环境

委派任务给 Agent

管理 Agent 上下文

最佳实践

API 参考

Agent 结构

Agent 对象

Agent version snapshot

Agent model

Agent tool

内置工具名

Tool config

Permission policy

MCP server

Skill binding

Multiagent

Multiagent agent entry

相关

定义 Agent

​Agent 对象

​Agent version snapshot

​Agent model

​Agent tool

​内置工具名

​Tool config

​Permission policy

​MCP server

​Skill binding

​Multiagent

​Multiagent agent entry

​相关

定义 Agent

Agent 对象

Agent version snapshot

Agent model

Agent tool

内置工具名

Tool config

Permission policy

MCP server

Skill binding

Multiagent

Multiagent agent entry

相关