工具

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

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



可用工具

代理工具集包含以下工具。當您在代理設定中包含此工具集時，所有工具預設皆為啟用狀態。configs 陣列中的每個項目都以其 name 識別，使用「名稱」欄中的值，並接受一個具有相同值的選用 type 欄位。web_search 和 web_fetch 項目接受額外的設定；請參閱限制網頁搜尋和網頁擷取網域。

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



設定工具集

建立代理時，使用 agent_toolset_20260401 啟用完整工具集。使用 configs 陣列來停用特定工具或覆寫其設定。每個設定項目也可以設定 permission_policy，用於控制該工具的呼叫是自動核准還是需要確認。請參閱權限政策以了解可用的政策類型。

web_search 和 web_fetch 的設定項目也接受網域篩選器和其他網頁設定；請參閱限制網頁搜尋和網頁擷取網域。

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
YAML



停用特定工具

若要停用某個工具，請在代理 tools 陣列的工具集物件中，於該工具的設定項目設定 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 }
  ]
}



限制網頁搜尋和網頁擷取網域

若要控制代理的網頁工具可以存取哪些網站，請在工具集 configs 陣列的 web_search 和 web_fetch 項目上設定 allowed_domains（工具只能存取這些主機）或 blocked_domains（工具永遠無法存取這些主機）。每個工具都有自己的清單，因此 web_search 和 web_fetch 可以有不同的限制。列出的網域涵蓋該主機及其所有子網域。在執行階段，若 web_fetch 呼叫的 URL 不在其清單允許範圍內，會向代理回傳錯誤結果（agent.tool_result 事件上的 is_error: true，內容中會指明錯誤代碼 url_not_allowed），而 web_search 會省略其清單不允許的結果。

以下工具集將 web_search 限制為兩個網站並將其結果在地化，同時為 web_fetch 封鎖一個主機，並限制擷取內容進入上下文的數量上限：

{
  "type": "agent_toolset_20260401",
  "configs": [
    {
      "type": "web_search",
      "name": "web_search",
      "allowed_domains": ["docs.example.com", "arxiv.org"],
      "user_location": {
        "type": "approximate",
        "country": "US",
        "timezone": "America/Los_Angeles"
      }
    },
    {
      "type": "web_fetch",
      "name": "web_fetch",
      "blocked_domains": ["ads.example.com"],
      "max_content_tokens": 50000
    }
  ]
}

以下請求使用此工具集建立代理，並印出回應中的 configs 陣列：

ant beta:agents create --transform tools.0.configs <<'YAML'
name: Research Agent
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    configs:
      - type: web_search
        name: web_search
        allowed_domains: [docs.example.com, arxiv.org]
        user_location:
          type: approximate
          country: US
          timezone: America/Los_Angeles
      - type: web_fetch
        name: web_fetch
        blocked_domains: [ads.example.com]
        max_content_tokens: 50000
YAML

在 Claude Console 中，從代理表單的 Built-in tools 卡片中的 web_search 和 web_fetch 列設定允許或封鎖的網域；在代理設定的 Raw 檢視中設定 max_content_tokens 和 user_location。

除了 enabled 和 permission_policy 之外，網頁工具項目還接受以下設定：



網域清單規則

• 在一個項目上設定 allowed_domains 或 blocked_domains 其中之一，不能兩者都設定。同時設定兩者的項目會被拒絕。
• 每個清單包含 1 到 64 個網域，每個網域 1 到 255 個字元。空清單會被拒絕：若不套用任何限制，請省略該欄位或傳送 null。
• 每個網域都是可註冊的網域名稱或其子網域，以純主機名稱形式書寫：ASCII 字母、數字、連字號、底線和點，不含協定、連接埠、認證資訊、萬用字元或空白字元，標籤不得以連字號開頭或結尾，且除了本清單稍後說明的選用 web_search 路徑後綴外，不得包含路徑。請使用 example.com，而非 https://example.com、example.com:443 或 *.example.com。主機名稱比對時不區分大小寫，且會忽略單一結尾的 /。
• 列出的網域會比對該主機及其子網域：example.com 涵蓋 docs.example.com，但 docs.example.com 不涵蓋 example.com 或 api.example.com。開頭的 www. 與其他子網域一樣，因此 www.example.com 不涵蓋 example.com；請列出不含前綴的網域以涵蓋兩者。
• 不接受任何形式的 IP 位址，無論是 IPv4、IPv6、方括號形式，或如 127.1 的數字簡寫。請改為列出網站的網域名稱。
• 單獨的頂層網域或註冊後綴（如 com、co.uk 或 gov.uk）會被拒絕，單一標籤名稱（如 intranet）也會被拒絕。請列出完整網域，如 example.co.uk。
• localhost 以及以 .localhost、.local、.internal、.localdomain 或 .invalid 結尾的主機會被拒絕。
• 國際化網域名稱請使用 xn--（Punycode）形式；包含非 ASCII 字元的網域會被拒絕。
• web_fetch 網域不能包含路徑：請使用 example.com，而非 example.com/*。web_search 網域可以帶有路徑後綴，如 example.com/blog，其中路徑不能包含空格、?、# 或任何 $ , | ^ ! 字元。建議 web_search 也使用純主機名稱，因為搜尋提供者會將路徑後綴視為 URL 模式進行比對，而非嚴格的主機規則。
• 清單中的重複網域會被拒絕。www.example.com 和 example.com 視為不同的網域；請參閱前述的比對規則以了解各自涵蓋的範圍。



設定的驗證時機

當您建立代理或更新代理時，以及當您建立或更新提供 tools 的工作階段時，格式和限制違規會以 400 invalid_request_error 被拒絕。例如，同時設定兩個清單的項目，其訊息會包含 Only one of allowed_domains or blocked_domains may be set.，而空清單的訊息會包含 allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null.。違反格式規則的網域，其訊息會指明其清單和從零開始的位置，例如 allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com"。

相同的請求也會拒絕三種依賴搜尋和擷取提供者的設定：allowed_domains 中 Anthropic 爬蟲不被允許存取的網域、搜尋提供者不支援的 user_location.country（訊息以 user_location.country: not a country the search provider supports 結尾），以及不是有效 IANA 名稱的 user_location.timezone。工作階段在首次初始化工具時會再次檢查設定；如果先前被接受的設定在該時間點已不再有效，工作階段會發出 session.error 事件並回到 idle 狀態，不會重試。請透過更新工作階段的工具來修正設定，同時也更新代理，以便新的工作階段以修正後的設定啟動，然後傳送新的 user.message 以繼續。



多代理工作階段、結果與工作階段中途更新

在多代理工作階段中，適用於某個執行緒的每個網域清單都會同時強制執行：協調器名冊中的代理受其自身的 allowed_domains 和 blocked_domains 約束，也受呼叫它的任何代理的清單約束，以及協調器目前的清單約束。

• 允許清單會合併為所有清單都涵蓋的網域，而封鎖清單會相加，因此名冊代理可以縮小工具可存取的範圍，但永遠無法擴大。例如，設定 blocked_domains 的名冊代理會保留協調器的 allowed_domains，並在其中封鎖那些主機；而設定自己的 allowed_domains 的名冊代理只能存取其清單和協調器清單都涵蓋的主機。
• 如果合併後的允許清單沒有共同的網域，該工具對該代理仍然可用，但每次呼叫都會失敗並回傳 url_not_allowed 錯誤，說明沒有任何網域被允許，且工具描述會告知模型此情況。請將每個名冊代理的允許清單保持在協調器的範圍內以避免此問題。
• max_content_tokens 和 user_location 不會合併：執行緒會使用其自身工具設定中的值（如有設定），否則使用呼叫它的代理的值，再否則使用協調器目前設定的值。
• {"type": "self"} 名冊項目沒有自己的網頁設定，會遵循協調器目前的設定。
• 結果導向工作階段中的評分器在執行時不具備 web_search 和 web_fetch，無論這些設定為何。
• 您可以透過更新其工具來變更閒置工作階段的清單。新清單會套用於工作階段的其餘部分；在多代理工作階段中，每個執行緒會從其下一回合開始套用新清單，而名冊代理自身的清單則維持其代理定義在工作階段建立時所設定的內容。



與 Messages API 工具的差異

這些設定使用與 Messages API 伺服器工具的網域篩選相同的 allowed_domains 和 blocked_domains 詞彙，但在 Managed Agents 上有以下差異：

• 每個清單上限為 64 個網域。
• 為 web_fetch 列出的網域不能包含路徑。
• 工具集上不提供 max_uses、citations 和 cache_control。



自訂工具

除了內建工具之外，您還可以定義自訂工具。自訂工具類似於 Messages API 中的使用者定義的用戶端工具。

每個自訂工具都定義了一個契約：您指定可用的操作及其回傳內容，而 Claude 決定何時以及如何呼叫它們。模型本身從不執行任何操作。它會發出結構化的請求，您的程式碼執行該操作，然後結果流回對話中。請參閱工作階段事件串流以了解如何在工作階段期間接收自訂工具呼叫並回傳結果。

如果您的工作階段在自行託管的沙箱中執行，環境工作程序可以從您的沙箱提供自訂工具，包括封裝您網路內部 MCP 伺服器的工具。

ant beta:agents create < agent.yaml

name: Weather Agent
model: claude-opus-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

在代理上定義自訂工具後，代理會在工作階段期間呼叫它們。



自訂工具定義的最佳實務

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



後續步驟