限制網頁搜尋與網頁擷取的網域

若要控制代理的網頁工具可以存取哪些網站，請在 agent toolset（代理工具集）的 web_search 與 web_fetch 項目上設定網域清單。這些 configs 項目各自接受以下兩種清單之一：

• allowed_domains： 工具只能存取這些主機。
• blocked_domains： 工具永遠無法存取這些主機。

每個工具都有自己的清單，因此 web_search 與 web_fetch 可以有不同的限制。

在代理上設定網域清單

以下範例建立一個代理，將 web_search 限制為兩個網站，並為 web_fetch 封鎖一個主機。它也設定了 user_location 與 max_content_tokens，相關說明請參閱設定。接著，範例會印出回應中的 configs 陣列。

ant apply agent.md

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

在採用 limited 網路設定的雲端環境中，環境的 allowed_hosts 也會套用至 web_search 與 web_fetch。當已啟用的網頁工具的 allowed_domains 中有不在 allowed_hosts 範圍內的項目時，建立工作階段會失敗並傳回 400 錯誤。新增此類項目的工作階段更新也會失敗。若要修正，請將該主機加入 allowed_hosts，或從 allowed_domains 中移除該項目。在執行階段，對 allowed_hosts 不相符之主機上的 URL 發出的 web_fetch 呼叫會傳回 url_not_allowed 錯誤結果。web_search 會略過來自此類主機的結果。這兩種清單的比對方式不同：工具的項目涵蓋其子網域，但 allowed_hosts 項目只比對單一確切主機，除非它以 *. 開頭。例如，工具項目 docs.example.com 不在 ["example.com"] 的 allowed_hosts 範圍內，但在 ["docs.example.com"] 或 ["*.example.com"] 的範圍內。

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

設定

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

關於 SDK 如何為這些項目定義型別，請參閱 SDK 中的設定項目型別。

當網域不被允許時

web_search 會略過其網域清單不允許的結果。對其網域清單不允許之 URL 發出的 web_fetch 呼叫，會向代理傳回錯誤結果。agent.tool_result 事件會帶有 is_error: true，且其內容會指出錯誤代碼 url_not_allowed。

網域清單規則

這些規則同樣適用於 allowed_domains 與 blocked_domains。違反任一規則的請求都會被拒絕，如驗證錯誤所述。

• 每個項目一份清單： 在一個項目上只能設定 allowed_domains 或 blocked_domains 其中之一，不能兩者都設定。
• 清單大小： 每份清單包含 1 到 64 個網域，每個網域長度為 1 到 255 個字元。
• 不可為空清單： 若不套用任何限制，請省略該欄位或傳送 null。
• 不可重複： 一個網域在清單中只能出現一次。www.example.com 與 example.com 視為不同的網域。

列出的網域會比對哪些主機

列出的網域會比對該主機及其所有子網域。example.com 涵蓋 docs.example.com，但 docs.example.com 不涵蓋 example.com 或 api.example.com。

開頭的 www. 與其他子網域無異，因此 www.example.com 不涵蓋 example.com。請列出裸網域以同時涵蓋兩者。

主機名稱的比對不區分大小寫。

網域格式

每個網域都是可註冊的網域名稱或其子網域，並以純主機名稱的形式撰寫。它可以包含 ASCII 字母、數字、連字號、底線與點。結尾的單一 / 會被忽略。

若網域包含憑證或空白字元，或其中某個標籤以連字號開頭或結尾，也會被拒絕。localhost 以及以 .localhost、.local、.internal、.localdomain 或 .invalid 結尾的主機也會被拒絕。

網頁搜尋網域上的路徑後綴

web_search 網域可以帶有路徑後綴，例如 example.com/blog。路徑不能包含空格、?、#，或 $ , | ^ ! 中的任何字元。

對於 web_search，也建議使用純主機名稱。搜尋提供者會將路徑後綴視為 URL 模式進行比對，而非嚴格的主機規則。

驗證錯誤

當您建立代理或更新代理時，API 會驗證這些設定。當您建立或更新提供 tools 的工作階段時，API 也會驗證這些設定。

違反格式與限制的請求會以 400 invalid_request_error 拒絕：

在相同的請求中，API 也會拒絕三種取決於搜尋與擷取提供者的設定：

• allowed_domains 中 Anthropic 爬蟲不被允許存取的網域。
• 搜尋提供者不支援的 user_location.country。訊息結尾為 user_location.country: not a country the search provider supports。
• 不是有效 IANA 名稱的 user_location.timezone。

在採用 limited 網路設定的雲端環境中，建立與更新工作階段時也會根據環境的 allowed_hosts 檢查 allowed_domains。請參閱在代理上設定網域清單中的規則。

當已接受的設定不再有效時

工作階段在首次初始化工具時會再次檢查設定。若先前已接受的設定在此時不再有效，工作階段會發出 session.error 事件，然後回到 idle 狀態且不會重試。

若要繼續工作階段：

1. 透過更新工作階段的工具修正設定。
2. 同時更新代理，讓新的工作階段以修正後的設定啟動。
3. 傳送新的 user.message。

多代理與成果導向的工作階段

在多代理工作階段中，適用於某個執行緒的所有網域清單會同時強制執行。協調者名單中的代理受三組清單約束：

• 其自身的 allowed_domains 與 blocked_domains
• 任何呼叫它的代理的清單
• 協調者目前的清單

這些設定的組合方式如下：

因此，名單中的代理可以縮小工具的存取範圍，但永遠無法擴大：

• 設定了 blocked_domains 的名單代理會保留協調者的 allowed_domains，並在其中封鎖那些主機。
• 設定了自身 allowed_domains 的名單代理，只能存取其清單與協調者清單都涵蓋的主機。

{"type": "self"} 名單項目沒有自己的網頁設定，會遵循協調者目前的設定。

若組合後的 allowed_domains 清單沒有任何共同網域，該工具對該代理仍然可用，但每次呼叫都會失敗。每次呼叫都會傳回 url_not_allowed 錯誤，說明沒有任何網域被允許。工具描述也會告知模型相同的資訊。為避免這種情況，請讓每個名單代理的 allowed_domains 保持在協調者的範圍內。

成果導向工作階段中的評分器在執行時不具備 web_search 與 web_fetch，不受這些設定影響。

在工作階段中途變更清單

您可以透過更新工具來變更閒置工作階段上的清單。新的清單會套用於工作階段的其餘部分。

在多代理工作階段中，每個執行緒會從其下一個回合開始套用新的清單。此更新不會變更名單代理自身的清單，這些清單會維持建立工作階段時代理定義所設定的內容。

與 Messages API 工具的差異

這些設定使用與 Messages API 伺服器工具的網域篩選相同的 allowed_domains 與 blocked_domains 欄位。Managed Agents 在四個方面有所不同：

• 每份清單上限為 64 個網域。
• 為 web_fetch 列出的網域不能包含路徑。
• 網域必須為 ASCII。Messages API 接受 Unicode 項目，但不建議使用。
• 工具集上無法使用 max_uses、citations 與 cache_control。

後續步驟