Agent 工具配置 - AI Coding Assistant Lingma

工具決定了 Agent 能做什麼。通過在建立或更新 Agent 時配置 tools 欄位，你可以精確控制 Agent 的能力邊界。

工具的作用

Agent 在執行任務時，會根據 tools 配置判斷可以調用哪些能力。所有工具通過單一對象 { "type": "agent_toolset_20260401", "enabled_tools": [...] } 配置，按需開啟 enabled_tools 數組中的原子工具。

enabled_tools 為非空白名單時，列表外的工具模型層完全不可見，不會發生調用嘗試；enabled_tools 省略或為空白數組時，所有內建工具都會暴露給模型。整個 tools 欄位省略或寫成 [] 時，模型層完全拿不到工具 schema（詳見下文 FAQ）。

可用工具

工具名（enabled_tools 數組取值）	用途	典型情境
`Bash`	Shell 命令執行	安裝依賴、運行指令碼、curl 調 API
`Read`	檔案讀	查看 mount 的檔案、代碼閱讀
`Write`	檔案寫（建立/覆蓋）	產生報告、產出物
`Edit`	檔案局部編輯	改配置、改代碼
`Glob`	萬用字元列檔案	找代碼檔案
`Grep`	檔案內容搜尋	定位字串
`WebFetch`	HTTP GET 單頁面	拉文檔/頁面
`WebSearch`	連網搜尋	檢索資料
`DeliverArtifacts`	系統保留工具，處於”全開”集合中（`enabled_tools` 省略或為空白時）	不建議在 `enabled_tools` 中顯式聲明

注意事項：

工具名首字母大寫（Bash 不是 bash），事件流裡也是大寫形式
enabled_tools 省略或填空數組 [] 等同啟用全部內建工具（包含上表中的 DeliverArtifacts）；如果希望 Agent 完全沒有工具，請把整個 tools 欄位省略或寫成 []
enabled_tools 中的每個工具名均會校正——寫入未知名稱（如 "Foo"）將返回 400 錯誤："unknown tool name 'Foo'"
不再支援每工具一對象的舊 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.cn/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.cn/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.cn/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 將沒有任何工具可用，只能進行純文字對話。要讓 Agent 具備工具能力，至少傳 [{"type":"agent_toolset_20260401"}]（等同啟用全部內建工具）。

Q：能否在 Session 層級覆蓋工具配置？ A：當前不支援。工具配置綁定在 Agent 上，同一 Agent 的所有 Session 共用相同工具集。

Q：tools 數組順序重要嗎？ A：不重要。Agent 根據任務上下文自主決定調用哪個工具。

Q：版本尾碼會隨時間變化嗎？ A：會。當 API 推出新版本工具時，會給出新的日期尾碼。建議關注 Changelog 選擇最新版本。