Agent 数据结构

Agent 对象、工具配置、MCP 服务器及 Skill 绑定的完整结构定义。

Agent 对象

由创建、列表、更新、归档以及 GET /api/v1/cloud/agents/{agent_id}（省略 version）返回。

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

Agent 版本快照

由 GET /api/v1/cloud/agents/{agent_id}?version=N 以及 GET /api/v1/cloud/agents/{agent_id}/versions 返回。

字段	类型	说明
`id`	string	Agent ID，前缀 `agent_`
`type`	string	固定为 `"agent"`
`name`	string	Agent 名称
`description`	string	Agent 描述
`model`	string	模型标识符
`system`	string	系统提示词
`tools`	array of Agent tool	工具配置列表
`mcp_servers`	array of MCP server	MCP 服务器列表
`skills`	array of Skill binding	Skill 绑定列表
`metadata`	object	Metadata 对象
`multiagent`	Multiagent \| null	多 Agent 配置
`version`	integer	此快照的版本号
`archived_at`	string \| null	UTC 归档时间
`created_at`	string	Agent 创建时间
`updated_at`	string	此快照的最后更新时间

Agent tool

tools[] 是按 type 区分的联合类型。

字段	类型	适用类型	说明
`type`	string	全部	必填。可选值：`agent_toolset_20260401`、`mcp_toolset`、`custom`
`enabled_tools`	array of string	`agent_toolset_20260401`	内置工具白名单。传入非空数组表示严格白名单。省略或传 `[]` 使用默认内置工具集
`disallowed_tools`	array of string	`agent_toolset_20260401`	需要禁用的内置工具。不能与 `enabled_tools` 中的值重复
`configs`	array of Tool config	`agent_toolset_20260401`、`mcp_toolset`	逐工具的启用及权限规则
`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，需通过 configs[].permission_policy 在 agent_toolset_20260401 或 mcp_toolset 条目上配置权限。

内置工具名称

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

Tool config

用于 tools[].configs[]。

字段	类型	必填	说明
`name`	string	是	要配置的工具名。`agent_toolset_20260401` 使用内置工具名；`mcp_toolset` 使用 MCP 服务器暴露的工具原始名称
`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 服务器名称
`type`	string	是	支持的值：`"url"`
`url`	string	是	Streamable HTTP MCP 端点 URL

MCP 服务器的认证通过 Vaults 配置。

Skill binding

用于 skills[]。

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

Multiagent

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

使用 multiagent 时，tools 数组必须包含一个 agent_toolset_20260401 类型的条目。

字段	类型	必填	说明
`type`	string	是	必须为 `"coordinator"`
`agents`	array of Multiagent agent entry	是	可委派的 Agent 列表，1-20 项（唯一）

Multiagent agent entry

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

字段	类型	必填	说明
`type`	string	是	`"agent"` 引用另一个 Agent；`"self"` 引用协调器自身
`id`	string	条件	Agent ID。`type` 为 `"agent"` 时必填
`version`	integer	否	指定 Agent 版本。省略时使用最新活跃版本
`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 tool

​内置工具名称

​Tool config

​Permission policy

​MCP server

​Skill binding

​Multiagent

​Multiagent agent entry