Agent 结构 - Qoder CN

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	Multiagent 编排配置；未设置时返回 `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	Multiagent 编排配置
`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`、`browser_toolset_20260714`、`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`	必填的自定义工具名。不能与内置工具重名、使用 `advisor`（不区分大小写），也不能以 `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 配置。

Browser Use Beta 工具集

Browser Use 当前为 Beta 功能，功能和接口会持续改进。完整的状态说明和启用示例见 Browser Use（Beta）。要让 Agent 使用 Browser Use，在创建或更新 Agent 时：

请求头添加 x-qoder-beta: browser-use-2026-07-14。
在请求体的 tools 数组中添加：

{
  "type": "browser_toolset_20260714"
}

该配置会为 Agent 启用全部 browser_* 工具和 Session 实时预览。此对象只接受 type 字段，不支持通过 enabled_tools 选择部分 Browser 工具。更新 Agent 时，传入 tools 会覆盖原有工具配置；需要保留的工具请一并传入。

内置工具名

支持以下内置工具名：

工具名
`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 字段，配置 Coordinator 可以委派的 Agent 名单及可选的 Advisor。完整工作流请参阅 Multiagent 编排。

名单包含普通 Agent 或者 self 时，tools 中必须包含 agent_toolset_20260401。仅配置 Advisor 时不要求该工具集。

字段	类型	必填	说明
`type`	string	是	必须为 `"coordinator"`
`agents`	Multiagent agent entry 数组	是	非空名单，最多 20 个不重复的普通 Agent 条目，另可包含 1 个 Advisor

Multiagent agent entry

multiagent.agents[] 支持 Agent 对象、Self 对象、字符串简写和 Advisor 对象： 对象格式：

字段	类型	必填	说明
`type`	string	是	`"agent"` 引用其他 Agent；`"self"` 引用 coordinator 自身
`id`	string	条件必填	Agent ID。`type` 为 `"agent"` 时必填
`version`	integer	否	指定 Agent 版本号；省略时在创建或更新 Coordinator 时解析并保存最新 Active 版本。支持正整数或正整数字符串

agent 条目的显示名称取自被引用 Agent 的 name，self 条目使用 Coordinator 的名称。条目中传入的 name 字段会被接受但忽略；所有显示名称必须忽略大小写后仍保持唯一。 qoder.advisor 是保留的名单名称，不可用于普通 Agent 或 self 条目，大小写变体也不可用。普通名称 advisor 不受此限制，但不会获得 Advisor 行为。 字符串简写：直接传 Agent ID 字符串，等价于 {"type": "agent", "id": "<value>"}。 Advisor 对象：

字段	类型	必填	说明
`type`	string	是	必须为 `"advisor"`
`model`	string	是	非空的可用模型名称，见模型列表；不支持模型对象格式

Advisor 条目只接受 type 和 model，可以单独配置，也可以与普通条目共存。使用方式见配置 Advisor。示例：

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

定义 Agent

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

​Agent 对象

​Agent version snapshot

​Agent model

​Agent tool

​Browser Use Beta 工具集

​内置工具名

​Tool config

​Permission policy

​MCP server

​Skill binding

​Multiagent

​Multiagent agent entry

​相关

定义 Agent

Agent 对象

Agent version snapshot

Agent model

Agent tool

Browser Use Beta 工具集

内置工具名

Tool config

Permission policy

MCP server

Skill binding

Multiagent

Multiagent agent entry

相关