Agent 结构

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

​

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、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	必填的自定义工具名。不能与内置工具重名，也不能以 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 时：

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
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 配置。