Skip to main content
智能体

Agent 结构

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

Agent 对象

创建、列表、更新、归档，以及不带 version 参数的 GET /api/v1/cloud/agents/{agent_id} 会返回该结构。
字段类型说明
idstringAgent ID，前缀为 agent_
typestring固定值 "agent"
namestringAgent 名称，长度 1-256 字符
descriptionstringAgent 描述，最长 2048 字符
modelstring | object模型标识。可传 string 表示模型 ID，或传 Agent model 对象以同时配置 effort 与 context_window
systemstring系统提示词，最长 100000 字符
toolsAgent tool 数组工具配置列表，最多 128 个，默认 []
mcp_serversMCP server 数组MCP server 列表，最多 20 个，默认 []
skillsSkill binding 数组Skill 绑定列表，最多 20 个，默认 []
metadataobjectMetadata 对象，默认 {}
multiagentMultiagent | nullMultiagent 编排配置；未设置时返回 null
versioninteger当前 Agent 版本号，从 1 开始
archived_atstring | nullUTC 归档时间；未归档时为 null
created_atstringUTC 创建时间
updated_atstringUTC 最后更新时间

Agent version snapshot

带 version 参数的 GET /api/v1/cloud/agents/{agent_id} 和 GET /api/v1/cloud/agents/{agent_id}/versions 会返回该结构。
字段类型说明
idstringAgent ID，前缀为 agent_
typestring固定值 "agent"
namestringAgent 名称
descriptionstringAgent 描述
modelstring | object模型标识；形态与 Agent 对象一致，详见 Agent model
systemstring系统提示词
toolsAgent tool 数组工具配置列表
mcp_serversMCP server 数组MCP server 列表
skillsSkill binding 数组Skill 绑定列表
metadataobjectMetadata 对象
multiagentMultiagent | nullMultiagent 编排配置
versioninteger当前快照对应的版本号
archived_atstring | nullUTC 归档时间；该快照未归档时为 null
created_atstringAgent 的 UTC 创建时间
updated_atstring该快照对应的 UTC 最后更新时间

Agent model

Agent 的 model 字段支持两种等价形态：
  • String 简写：直接传模型 ID，例如 "ultimate"。
  • Object 形态：包含 id 和可选的调优字段。
字段类型必填说明
idstring是模型标识；可通过 列出模型 查询可用值
effortstring否Reasoning effort 等级。可选值：none、low、medium、high、xhigh、max。各模型实际支持的等级见 列出模型 返回的 efforts 数组
context_windowinteger否期望的上下文窗口（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 区分不同结构。
字段类型适用类型说明
typestring全部必填。可选值：agent_toolset_20260401、browser_toolset_20260714、mcp_toolset、custom
enabled_toolsstring 数组agent_toolset_20260401内置工具白名单。非空数组表示严格白名单；省略或传 [] 时使用默认内置工具集，并继续叠加 disallowed_tools 和 configs[].enabled。取值必须使用下方列出的内置工具名
disallowed_toolsstring 数组agent_toolset_20260401要隐藏并拒绝的内置工具，取值必须使用下方列出的内置工具名。同一工具不能同时出现在 enabled_tools 和 disallowed_tools
configsTool config 数组agent_toolset_20260401、mcp_toolset单工具启用状态和权限规则。逐个工具的权限在这里通过 permission_policy 配置
mcp_server_namestringmcp_toolset必填。必须匹配某个 mcp_servers[].name
namestringcustom必填的自定义工具名。不能与内置工具重名、使用 advisor（不区分大小写），也不能以 mcp__ 开头
descriptionstringcustom必填的自定义工具描述
input_schemaobjectcustom必填的 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 时：
  1. 请求头添加 x-qoder-beta: browser-use-2026-07-14。
  2. 在请求体的 tools 数组中添加：
{
  "type": "browser_toolset_20260714"
}
该配置会为 Agent 启用全部 browser_* 工具和 Session 实时预览。此对象只接受 type 字段，不支持通过 enabled_tools 选择部分 Browser 工具。 更新 Agent 时，传入 tools 会覆盖原有工具配置；需要保留的工具请一并传入。

内置工具名

支持以下内置工具名：
工具名
Bash
DeliverArtifacts
Edit
Glob
Grep
ImageGen
ImageSearch
Read
VideoGen
WebFetch
WebSearch
Write

Tool config

用于 tools[].configs[]。
字段类型必填说明
namestring是要配置的工具名。agent_toolset_20260401 使用内置工具名；mcp_toolset 使用该 MCP server 暴露的原始工具名
enabledboolean否false 表示隐藏并拒绝该工具；true 表示显式启用该工具
permission_policyPermission policy否该工具的运行时权限行为

Permission policy

字段类型必填说明
typestring是可选值：always_allow、always_ask、always_deny
always_allow 表示直接执行；always_ask 表示暂停并等待 user.tool_confirmation；always_deny 表示返回被拒绝的工具结果。

MCP server

用于 mcp_servers[]。
字段类型必填说明
namestring是Agent 内唯一的 MCP server 名称
typestring是支持值："url"
urlstring是Streamable HTTP MCP endpoint URL
MCP server 鉴权通过 Vault 配置。

Skill binding

用于 skills[]。
字段类型必填说明
typestring是可选值：qoder、custom
skill_idstring是Skill 标识
versionstring否可选的非空版本字符串

Multiagent

用于 Agent 的 multiagent 字段，配置 Coordinator 可以委派的 Agent 名单及可选的 Advisor。完整工作流请参阅 Multiagent 编排。
名单包含普通 Agent 或者 self 时，tools 中必须包含 agent_toolset_20260401。仅配置 Advisor 时不要求该工具集。
字段类型必填说明
typestring是必须为 "coordinator"
agentsMultiagent agent entry 数组是非空名单，最多 20 个不重复的普通 Agent 条目，另可包含 1 个 Advisor

Multiagent agent entry

multiagent.agents[] 支持 Agent 对象、Self 对象、字符串简写和 Advisor 对象： 对象格式：
字段类型必填说明
typestring是"agent" 引用其他 Agent；"self" 引用 coordinator 自身
idstring条件必填Agent ID。type 为 "agent" 时必填
versioninteger | string否仅用于 type: "agent"，规则见下表
type: "agent" 的版本规则：
versionAgent 保存和返回新建 Session
省略保存时最新的数字版本使用已保存版本
"latest"字符串 "latest"解析并保存当时最新的数字版本
3整数 3使用 v3
正整数字符串（如 "3"）也可作为输入，保存后返回整数；null、0 和空字符串无效。 这里的 "latest" 只用于选择子 Agent 的版本，Agent 自身的版本号（顶层 version）仍是整数。
  • 新建 Session 时，"latest" 会被替换为具体版本号，该 Session 后续创建的子线程也使用这个版本。
  • 修改 Coordinator 的子 Agent 引用，不会改变 Coordinator 的历史版本或已有 Session。
  • 已保存的固定版本不会自动变为 "latest"，需要显式修改引用。
agent 条目的显示名称取自被引用 Agent 的 name，self 条目使用 Coordinator 的名称。条目中传入的 name 字段会被接受但忽略；所有显示名称必须忽略大小写后仍保持唯一。 qoder.advisor 是保留的名单名称，不可用于普通 Agent 或 self 条目，大小写变体也不可用。普通名称 advisor 不受此限制，但不会获得 Advisor 行为。 字符串简写：直接传 Agent ID 字符串，等价于 {"type": "agent", "id": "<value>"}。 Advisor 对象：
字段类型必填说明
typestring是必须为 "advisor"
modelstring是非空的可用模型名称，见 模型列表；不支持模型对象格式
Advisor 条目只接受 type 和 model，可以单独配置，也可以与普通条目共存。使用方式见 配置 Advisor。 示例： 
{
  "type": "coordinator",
  "agents": [
    {"type": "agent", "id": "agent_019f00000001", "version": "latest", "name": "Research Agent"},
    {"type": "agent", "id": "agent_019f00000002", "version": 3},
    {"type": "self"},
    "agent_019f00000003",
    {"type": "advisor", "model": "ultimate"}
  ]
}

相关

定义 Agent

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