跳转到主要内容

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 时配置 tools 字段，你可以精确控制 Agent 的能力边界。

​
工具的作用

Agent 在执行任务时，会根据 tools 配置判断可以调用哪些能力：
  • computer —— 控制虚拟桌面，执行 GUI 操作
  • bash —— 在安全沙箱中执行 shell 命令
  • text_editor —— 读写和编辑文件
未配置的工具，Agent 不会尝试调用。

​
工具类型版本后缀

API 中工具类型必须带版本日期后缀（如 _20250124），用于固定 API 行为版本。请使用最新的版本后缀。
工具类型API 实际类型说明典型用途
computercomputer_20250124虚拟桌面控制浏览器操作、GUI 自动化
bashbash_20250124Shell 命令执行安装依赖、运行脚本、系统管理
text_editortext_editor_20250124文件编辑代码开发、配置修改

​
当前格式：JSON 数组

工具配置为扁平 JSON 数组，每个元素是一个工具对象： 
{
  "tools": [
    {"type": "computer_20250124"},
    {"type": "bash_20250124"},
    {"type": "text_editor_20250124"}
  ]
}
在创建 Agent 时设置： 
curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-agent",
    "model": "qoder-best",
    "instructions": "你是一个开发助手",
    "tools": [
      {"type": "computer_20250124"},
      {"type": "bash_20250124"},
      {"type": "text_editor_20250124"}
    ]
  }'

​
工具配置示例

​
最小配置（仅命令行）

{
  "tools": [
    {"type": "bash_20250124"}
  ]
}

​
完整开发环境

{
  "tools": [
    {"type": "computer_20250124"},
    {"type": "bash_20250124"},
    {"type": "text_editor_20250124"}
  ]
}

​
带权限策略的配置

工具对象可包含 permission 字段控制执行策略（详见权限策略）： 
{
  "tools": [
    {"type": "bash_20250124", "permission": "allow"},
    {"type": "text_editor_20250124", "permission": "allow"},
    {"type": "computer_20250124", "permission": "ask"}
  ]
}

​
更新工具配置

通过 PATCH 更新 Agent 的工具列表： 
curl -X PATCH https://openapi.qoder.sh/api/v1/cloud/agents/agt_abc123 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [
      {"type": "bash_20250124", "permission": "allow"},
      {"type": "text_editor_20250124", "permission": "allow"}
    ]
  }'
更新 tools 是全量替换，需传入完整数组。已有 Session 不受影响，新 Session 使用更新后的配置。

​
curl 查看当前工具配置

curl https://openapi.qoder.sh/api/v1/cloud/agents/agt_abc123 \
  -H "Authorization: Bearer $QODER_PAT" | jq '.tools'
输出示例： 
[
  {"type": "computer_20250124"},
  {"type": "bash_20250124"},
  {"type": "text_editor_20250124"}
]

​
常见问题

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