工具

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

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



可用工具

智能体工具集包含以下工具。当您在智能体配置中包含该工具集时，所有工具默认启用。configs 数组中的每个条目通过其 name 进行标识（使用"名称"列中的值），并接受一个可选的 type 字段（值与 name 相同）。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 可以有不同的限制。列出的域名涵盖该主机及其所有子域名。在运行时，如果 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 更难提取重要信息。



后续步骤