工具

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

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

可用工具

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

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

設定工具集

建立代理時，使用 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 列設定允許或封鎖的網域；max_content_tokens 與 user_location 則在代理設定的 Raw 檢視中設定。

除了 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 列出的網域不可包含路徑。
• 網域必須為 ASCII：國際化網域名稱請使用 xn--（Punycode）形式。Messages API 接受 Unicode 項目，但不建議使用。
• 工具集上不提供 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 更難擷取重要內容。

後續步驟