工具

Claude Managed Agents 提供一組內建工具，Claude 可以在 session（工作階段）中自主使用這些工具。您可以透過在代理設定中指定工具，來控制哪些工具可供使用。

Claude Managed Agents 也支援自訂的使用者定義工具。您的應用程式會另行執行這些工具，並將結果回傳給 Claude，Claude 再利用這些結果繼續執行任務。若要為代理提供來自 MCP 伺服器的工具，請改用 MCP 連接器。

可用工具

代理工具集包含下列工具。當您在代理設定中納入此工具集時，所有工具預設皆為啟用。

當工具輸出超過 100,000 個字元（約 25,000 個 token）時，會自動寫入 sandbox（沙箱）中的檔案。模型會收到包含檔案路徑的截斷預覽，並可從該處讀取完整內容。

設定工具集

建立代理時，使用 agent_toolset_20260401 啟用完整工具集。使用 configs 陣列來停用特定工具或覆寫其設定。每個項目以其 name 識別，其值取自可用工具中的「名稱」欄。項目也接受一個選用的 type 欄位，其值相同。

每個設定項目也可以設定 permission_policy。此政策控制工具的呼叫是無需確認即執行、需要確認，還是由伺服器逐一評估。請參閱權限政策以了解可用的政策類型。

下列範例啟用工具集並停用 web_fetch：

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
---

停用特定工具

若要停用某個工具，請在其 configs 項目中設定 enabled: false：

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}

僅啟用特定工具

default_config 物件為工具集中的每個工具設定基準，而各工具的 configs 項目會覆寫它。若要從全部關閉開始，僅啟用您需要的工具，請將 default_config.enabled 設為 false：

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}

限制網頁搜尋與網頁擷取

web_search 和 web_fetch 項目也接受網域清單、擷取內容的上限，以及搜尋位置。請參閱限制網頁搜尋與網頁擷取的網域。

SDK 中的設定項目型別

Python、TypeScript、Go、Java、C#、Ruby 和 PHP SDK 會依工具為每個 configs 項目定義型別。該型別是一個聯集（union），每個內建工具對應一個成員，並以 type 區分。

在 Go、Java、C# 和 PHP 中，您需要從具型別的值建構項目，而非使用一般的字典或雜湊。在這些 SDK 中，configs 的元素型別就是該聯集本身，因此請從各工具的成員型別建構每個項目。

建構項目時，您可以省略 type，因為伺服器會從 name 推斷它。回應中一律會包含此欄位。此型別定義不會改變項目序列化後的 JSON。項目僅設定 name、enabled 和 permission_policy 的請求，無論是否包含 type 皆為有效。

自訂工具

自訂工具類似於 Messages API 中的使用者定義用戶端工具。您指定有哪些操作可用以及它們傳回什麼，而 Claude 決定何時以及如何呼叫它們。

Claude 不會自行執行自訂工具。它會發出結構化請求，由您的程式碼執行該操作，然後您將結果傳回工作階段。

下列範例建立一個具有內建工具集和一個自訂工具 get_weather 的代理：

ant apply agent.md

---
name: Weather Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
  - type: custom
    name: get_weather
    description: Get current weather for a location
    input_schema:
      type: object
      properties:
        location:
          type: string
          description: City name
      required:
        - location
---

自訂工具的名稱不能以 mcp__ 或 ant__ 開頭，也不能與內建代理工具的名稱相同。違反此規則的請求會傳回 400 錯誤。若代理已有名稱以 ant__ 開頭的自訂工具，則只有在更新所傳送的 tools 不含該名稱時才會接受更新，因此請在下次更新時重新命名或移除該工具。若此類工具存在於新工作階段的代理上（套用任何覆寫之後）、存在於 subagents 的 predefined_agents 清單中的代理上，或存在於 workflows 的 predefined_agents 清單中的代理上，該新工作階段會以 400 錯誤遭到拒絕。已存在的工作階段不受影響。

代理會在工作階段期間呼叫其自訂工具。若要接收呼叫並傳回結果，請參閱工作階段事件串流。

對於在自行託管沙箱中執行的工作階段，環境 worker 可以從沙箱提供自訂工具。這些工具可以包括包裝您網路內 MCP 伺服器的工具。

自訂工具定義的最佳實務

• 提供極為詳細的說明。 這是影響工具效能最重要的因素。您能提供給 Claude 關於工具的上下文越多，它就越能判斷何時以及如何使用這些工具。每個工具說明以三到四句為目標，若工具較複雜則可更多。您的說明應涵蓋：
  • 工具的功能
  • 何時使用，以及何時不應使用
  • 每個參數的意義，以及它如何影響工具的行為
  • 任何重要的注意事項或限制
• 將相關操作整合為較少的工具。 將 create_pr、review_pr 和 merge_pr 等動作歸納為單一工具，並搭配 action 參數。較少但功能更強的工具可減少選擇上的模糊性，並讓 Claude 更容易瀏覽您的工具介面。
• 在工具名稱中使用有意義的命名空間。 當您的工具橫跨多個服務或資源時，請以資源作為名稱前綴（例如 db_query 或 storage_read）。隨著您的工具庫成長，這能讓工具選擇毫無歧義。
• 設計工具回應時僅傳回高訊號資訊。 傳回具語意且穩定的識別碼（例如 slug 或 UUID），而非不透明的內部參照。僅包含 Claude 判斷下一步所需的欄位。臃腫的回應會浪費上下文，並讓 Claude 更難擷取重要資訊。

後續步驟