> ## 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 和自定义工具。
工具决定了 Agent **能做什么**。通过在创建或更新 Agent 时配置 `tools` 字段，你可以精确控制 Agent 的能力边界。
## 工具的作用
Agent 在执行任务时，会根据 `tools` 配置判断可以调用哪些能力。内置工具通过 `{ "type": "agent_toolset_20260401", "enabled_tools": [...] }` 配置，按需开启 `enabled_tools` 数组中的原子工具。Client-side 自定义工具使用独立的 `{ "type": "custom", ... }` 条目配置。
`enabled_tools` 为非空白名单时，列表外的工具模型层完全不可见，不会发生调用尝试；`enabled_tools` 省略或为空数组时，所有内置工具都会暴露给模型。整个 `tools` 字段省略或写成 `[]` 时，模型层完全拿不到工具 schema（详见下文 FAQ）。
## 可用工具
| 工具名（enabled\_tools 数组取值） | 用途 | 典型场景 |
| ------------------------ | --------------------------------------- | -------------------- |
| `Bash` | Shell 命令执行 | 安装依赖、运行脚本、curl 调 API |
| `Read` | 文件读 | 查看 mount 的文件、代码阅读 |
| `Write` | 文件写（创建/覆盖） | 生成报告、产出物 |
| `Edit` | 文件局部编辑 | 改配置、改代码 |
| `Glob` | 通配符列文件 | 找代码文件 |
| `Grep` | 文件内容搜索 | 定位字符串 |
| `WebFetch` | HTTP GET 单页面 | 拉文档/页面 |
| `WebSearch` | 联网搜索 | 检索资料 |
| `DeliverArtifacts` | 将 Agent 在 `/data/` 下产出的文件投递给用户，作为可下载的产物 | 用户需要文件/报告/导出等可交付产物时 |
注意事项：
* 工具名必须使用上表中的精确写法；事件流里也使用相同写法
* `enabled_tools` 省略或填空数组 `[]` 等同启用**全部内置工具**（包含上表中的 `DeliverArtifacts`）；如果希望 Agent 完全没有工具，请把整个 `tools` 字段省略或写成 `[]`
* `enabled_tools` 为**非空白名单**时，列表外的工具对模型完全不可见。若要在自定义白名单中使用 `DeliverArtifacts`，必须显式列出（如 `["Bash", "Write", "DeliverArtifacts"]`）
* `enabled_tools` 中的每个工具名均会校验——写入未知名称（如 `"Foo"`）将返回 **400** 错误：`"unknown tool name 'Foo'"`
* 内置工具和 MCP 工具权限通过 `configs[].permission_policy` 配置，见 [权限策略](/zh/cloud-agents/permission-policies)
* 不再支持每工具一对象的旧 schema（如 `{"type": "bash_20250124"}`）
## 当前格式：单一对象
内置工具配置为单一对象，通过 `enabled_tools` 数组开关具体工具：
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
}
```
在创建 Agent 时设置：
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/agents \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "dev-agent",
"model": "ultimate",
"system": "你是一个开发助手",
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
}'
```
## 自定义 Client-Side 工具
自定义工具用于把你的应用侧能力暴露给 Agent。Agent 可以请求调用这些工具，但平台不会直接执行；当 Agent 调用自定义工具时，Session 会以 `requires_action` stop reason 暂停，客户端执行工具后通过 `user.custom_tool_result` 事件把结果回传。
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Read", "Write"]
},
{
"type": "custom",
"name": "lookup_order",
"description": "根据订单 ID 查询订单。",
"input_schema": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"]
}
}
]
}
```
自定义工具规则：
* `name`、`description`、`input_schema` 必填
* `input_schema` 必须是 JSON Schema 对象，且 `"type": "object"`
* 同一个 Agent 内的自定义工具名按大小写不敏感方式去重
* 自定义工具名不能与 `Bash`、`Read` 等内置工具名冲突
* 以 `mcp__` 开头的名称保留给 MCP 工具使用
* 自定义工具不支持 `permission_policy`，因为工具由客户端执行
`user.custom_tool_result` 的回传流程见 [发送事件](/zh/cloud-agents/api/sessions/send-event)。
## 工具配置示例
### 最小配置（仅命令行）
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash"]
}
]
}
```
### 完整开发环境
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
}
```
## 更新工具配置
通过 `POST` 更新 Agent 的工具配置。请求必须携带当前 `version`；显式传入 `tools` 时会替换已保存的工具数组。
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"version": 1,
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit"]
}
]
}'
```
Agent 更新对未传字段使用 merge 语义。`tools`、`mcp_servers`、`skills` 等数组字段在显式传入时会整体替换。必须带上 `version` 字段做乐观并发控制：
* 携带的 version 等于当前版本 → 200，version + 1
* 携带过期 version → 409 `{ error: { type: "conflict_error", message: "Version conflict. Expected version N, got M." }}`
已有 Session 不受影响，新 Session 使用更新后的配置。
## curl 查看当前工具配置
```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
-H "Authorization: Bearer $QODER_PAT" | jq '.tools'
```
输出示例：
```json theme={null}
[
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
```
## 常见问题
**Q：不配置 tools 会怎样？** A：Agent 将没有任何工具可用，只能进行纯文本对话。要让 Agent 具备工具能力，至少传 `[{"type":"agent_toolset_20260401"}]`（等同启用全部内置工具）。
**Q：能否在 Session 级别覆盖工具配置？** A：当前不支持。工具配置绑定在 Agent 上，同一 Agent 的所有 Session 共享相同工具集。
**Q：tools 数组顺序重要吗？** A：不重要。Agent 根据任务上下文自主决定调用哪个工具。
**Q：版本后缀会随时间变化吗？** A：会。当 API 推出新版本工具时，会给出新的日期后缀。建议关注 Changelog 选择最新版本。
## 下一步
控制工具调用是允许、询问还是拒绝。
为 Agent 附加领域专业知识。
回顾 Agent 配置。
管理会话生命周期。