Agent 结构

Agent 对象、工具、MCP server 和 Skill binding 的字段结构。

​

Agent 对象

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

字段	类型	说明
id	string	Agent ID，前缀为 agent_
type	string	固定值 "agent"
name	string	Agent 名称，长度 1-256 字符
description	string	Agent 描述，最长 2048 字符
model	string	模型标识；请求和响应都使用 string
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	Managed Agents 配置。仅在设置后返回，默认 null
version	integer	当前 Agent 版本号，从 1 开始
archived	boolean	是否已归档
archived_at	string | null	UTC 归档时间；未归档时为 null
created_at	string	UTC 创建时间
updated_at	string	UTC 最后更新时间

​

Agent version snapshot

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

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

​

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
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	是	支持值："http"
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 字段，配置 managed 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 配置。