限制网页搜索和网页抓取的域名

要控制智能体的 Web 工具可以访问哪些站点，请在智能体工具集的 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。当已启用的 Web 工具的 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 之外，Web 工具条目还接受以下设置：

有关 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"} 名册条目没有自己的 Web 设置，会遵循协调者当前的设置。

如果组合后的 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。

后续步骤