> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](#agent-model) 对象以同时配置 `effort` 与 `context_window` |
| `system` | string | 系统提示词，最长 100000 字符 |
| `tools` | [Agent tool](#agent-tool) 数组 | 工具配置列表，最多 128 个，默认 `[]` |
| `mcp_servers` | [MCP server](#mcp-server) 数组 | MCP server 列表，最多 20 个，默认 `[]` |
| `skills` | [Skill binding](#skill-binding) 数组 | Skill 绑定列表，最多 20 个，默认 `[]` |
| `metadata` | object | [Metadata 对象](/zh/cloud-agents/api/conventions/schemas#metadata-对象)，默认 `{}` |
| `multiagent` | [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-对象)一致，详见 [Agent model](#agent-model) |
| `system` | string | 系统提示词 |
| `tools` | [Agent tool](#agent-tool) 数组 | 工具配置列表 |
| `mcp_servers` | [MCP server](#mcp-server) 数组 | MCP server 列表 |
| `skills` | [Skill binding](#skill-binding) 数组 | Skill 绑定列表 |
| `metadata` | object | [Metadata 对象](/zh/cloud-agents/api/conventions/schemas#metadata-对象) |
| `multiagent` | [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 | 是 | 模型标识；可通过 [列出模型](/zh/cloud-agents/api/models/list) 查询可用值 |
| `effort` | string | 否 | Reasoning effort 等级。可选值：`none`、`low`、`medium`、`high`、`xhigh`、`max`。各模型实际支持的等级见 [列出模型](/zh/cloud-agents/api/models/list) 返回的 `efforts` 数组 |
| `context_window` | integer | 否 | 期望的上下文窗口（token 数，正整数）。取值请从 [列出模型](/zh/cloud-agents/api/models/list) 返回的 `available_context_windows` 中选择 |
响应会按请求提交的形态回显：以 string 提交则 `model` 返回 string；以对象提交则返回对象并保留调优字段。版本快照（`GET /api/v1/cloud/agents/{agent_id}?version=N`）也是同样的形态。
Session 响应会在嵌入的 Agent 中额外返回只读的 `effective_context_window`（位于 `agent.model` 内），详见 [Session 数据结构](/zh/cloud-agents/api/sessions/schemas)。
## 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](#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` |
| `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) | 否 | 该工具的运行时权限行为 |
## 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](/zh/cloud-agents/vaults) 配置。
## 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](#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": ""}`。
示例：
```json theme={null}
{
"type": "coordinator",
"agents": [
{"type": "agent", "id": "agent_019f00000001", "name": "Research Agent"},
{"type": "agent", "id": "agent_019f00000002", "version": 3},
{"type": "self"},
"agent_019f00000003"
]
}
```
## 相关
创建可复用、可版本化的 Agent 配置。