Skip to main content
构建 Agent

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 数组取值）用途典型场景
BashShell 命令执行安装依赖、运行脚本、curl 调 API
Read文件读查看 mount 的文件、代码阅读
Write文件写（创建/覆盖）生成报告、产出物
Edit文件局部编辑改配置、改代码
Glob通配符列文件找代码文件
Grep文件内容搜索定位字符串
WebFetchHTTP GET 单页面拉文档/页面
WebSearch联网搜索检索资料
ImageSearch图片搜索查找任务需要的图片素材
ImageGen图片生成根据文本描述生成图片
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 配置，见 权限策略
  • 不再支持每工具一对象的旧 schema（如 {"type": "bash_20250124"}）

Browser Use Beta

Browser Use 当前为 Beta 功能。我们会根据使用反馈持续改进功能、稳定性和使用体验。Beta 期间的工具能力、使用限制及接口细节可能调整，请关注版本说明，并根据变更及时调整集成。
Browser Use 提供平台托管的 browser_* 工具和 Session 实时预览。它使用独立的工具集配置，不属于 agent_toolset_20260401.enabled_tools： 
{
  "type": "browser_toolset_20260714"
}
创建 Agent，或更新 Agent 时提交包含该工具集的完整 tools 数组，请求需同时包含 x-qoder-beta: browser-use-2026-07-14 请求头： 
curl -X POST https://api.qoder.com/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-qoder-beta: browser-use-2026-07-14" \
  -d '{
    "name": "browser-agent",
    "model": "ultimate",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      },
      {
        "type": "browser_toolset_20260714"
      }
    ]
  }'
Browser Use 当前已开放使用。接入时请注意：
  • 只有配置了 browser_toolset_20260714 的 Agent 才会启用浏览器工具和 Session 实时预览
  • 更新 Agent 只影响之后创建的 Session；已有 Session 继续使用创建时固定的 Agent 快照
  • Browser Use 配置不会影响其他 Agent 或其他工具

当前格式：单一对象

内置工具配置为单一对象，通过 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_ACCESS_TOKEN" \
  -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 事件把结果回传。 
{
  "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 的回传流程见 发送事件。

工具配置示例

最小配置（仅命令行）

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

完整开发环境

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

更新工具配置

通过 POST 更新 Agent 的工具配置。请求必须携带当前 version；显式传入 tools 时会替换已保存的工具数组。 
curl -X POST https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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 查看当前工具配置

curl https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" | jq '.tools'
输出示例： 
[
  {
    "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 附加领域专业知识。

定义 Agent

回顾 Agent 配置。

启动 Session

管理会话生命周期。
快速入门
构建 Agent
配置 Agent 环境
委派任务给 Agent
集成 Agent
管理 Agent 上下文
账户
最佳实践
公告
API 参考