Agent 工具配置

工具决定了 Agent 能做什么。通过在创建或更新 Agent 时配置 tools 字段，你可以精确控制 Agent 的能力边界。

工具的作用

Agent 在执行任务时，会根据 tools 配置判断可以调用哪些能力。所有工具通过单一对象 { "type": "agent_toolset_20260401", "enabled_tools": [...] } 配置，按需开启 enabled_tools 数组中的原子工具。未配置的工具，Agent 不会尝试调用。

可用工具

工具名（enabled_tools 数组取值）	用途	典型场景
`Bash`	Shell 命令执行	安装依赖、运行脚本、curl 调 API
`Read`	文件读	查看 mount 的文件、代码阅读
`Write`	文件写（创建/覆盖）	生成报告、产出物
`Edit`	文件局部编辑	改配置、改代码
`Glob`	通配符列文件	找代码文件
`Grep`	文件内容搜索	定位字符串
`WebFetch`	HTTP GET 单页面	拉文档/页面
`WebSearch`	联网搜索	检索资料

注意事项：

工具名首字母大写（Bash 不是 bash），事件流里也是大写形式
enabled_tools 不能为空数组（空数组等于 0 工具，session 进入 processing 后永不响应）
enabled_tools 里写未知工具名（如 "Foo"）服务端会静默接受、agent 实际拿不到该工具
不再支持每工具一对象的旧 schema（如 {"type": "bash_20250124"}）

当前格式：单一对象

工具配置为单一对象，通过 enabled_tools 数组开关具体工具：

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

在创建 Agent 时设置：

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",
    "instructions": "你是一个开发助手",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }'

工具配置示例

最小配置（仅命令行）

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash"]
    }
  ]
}

完整开发环境

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

创建新版本（PUT 全量替换）

通过 PUT 创建 Agent 的新版本，更新工具配置：

curl -X PUT 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"]
      }
    ]
  }'

PUT 是全量替换（不是补丁），未携带的字段会被清空。必须带上 version 字段做乐观并发控制：

携带的 version 等于当前版本 → 200，version + 1
携带过期 version → 409 { error: { type: "conflict_error", message: "Version conflict. Expected version N, got M." }}

已有 Session 不受影响，新 Session 使用更新后的配置。

curl 查看当前工具配置

curl https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" | jq '.tools'

输出示例：

[
  {
    "type": "agent_toolset_20260401",
    "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
  }
]

常见问题

Q：不配置 tools 会怎样？ A：Agent 将没有任何工具可用，只能进行纯文本对话。 Q：能否在 Session 级别覆盖工具配置？ A：当前不支持。工具配置绑定在 Agent 上，同一 Agent 的所有 Session 共享相同工具集。 Q：tools 数组顺序重要吗？ A：不重要。Agent 根据任务上下文自主决定调用哪个工具。 Q：版本后缀会随时间变化吗？ A：会。当 API 推出新版本工具时，会给出新的日期后缀。建议关注 Changelog 选择最新版本。

Documentation Index

​工具的作用

​可用工具

​当前格式：单一对象

​工具配置示例

​最小配置（仅命令行）

​完整开发环境

​创建新版本（PUT 全量替换）

​curl 查看当前工具配置

​常见问题