工具

Claude Managed Agents 提供了一组内置工具，Claude 可以在会话中自主使用这些工具。您可以通过在智能体配置中指定工具来控制哪些工具可用。

Claude Managed Agents 还支持自定义的、用户定义的工具。您的应用程序单独执行这些工具并将结果返回给 Claude，Claude 使用这些结果继续执行任务。要为智能体提供来自 MCP 服务器的工具，请改用 MCP 连接器。



可用工具

智能体工具集包含以下工具。当您在智能体配置中包含该工具集时，所有工具默认启用。configs 数组中的每个条目通过其 name 标识，使用"名称"列中的值，并接受一个具有相同值的可选 type 字段。web_search 和 web_fetch 条目接受额外的设置；请参阅限制网页搜索和网页抓取的域名。

当工具输出超过 100,000 个字符（约 25,000 个令牌）时，它会自动写入沙箱中的文件。模型会收到一个包含文件路径的截断预览，并可以从该路径读取完整内容。



配置工具集

创建智能体时，使用 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 可以有不同的限制。列出的域名涵盖该主机及其所有子域名。在运行时，对其列表不允许的 URL 发起的 web_fetch 调用会向智能体返回错误结果（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 更难提取重要信息。



后续步骤