工具

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

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

可用工具

智能体工具集包含以下工具。当您在智能体配置中包含该工具集时，所有工具默认启用。

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

配置工具集

创建智能体时，使用 agent_toolset_20260401 启用完整工具集。使用 configs 数组来禁用特定工具或覆盖其设置。每个条目通过其 name 进行标识，其值取自可用工具中的"名称"列。条目还接受一个可选的 type 字段，其值与名称相同。

每个配置条目还可以设置 permission_policy。该策略控制工具调用是无需确认即可运行、需要确认，还是由服务器逐一评估。有关可用的策略类型，请参阅权限策略。

以下示例启用工具集并禁用 web_fetch：

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
---

禁用特定工具

要禁用某个工具，请在其 configs 条目中设置 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 }
  ]
}

限制网页搜索和网页抓取

web_search 和 web_fetch 条目还接受域名列表、抓取内容的上限以及搜索位置。请参阅限制网页搜索和网页抓取的域名。

SDK 中的配置条目类型

Python、TypeScript、Go、Java、C#、Ruby 和 PHP SDK 会按工具为每个 configs 条目定义类型。该类型是一个联合类型，每个内置工具对应一个成员，并通过 type 进行区分。

在 Go、Java、C# 和 PHP 中，您需要使用类型化的值而不是普通的字典或哈希来构造条目。在这些 SDK 中，configs 的元素类型就是该联合类型本身，因此请使用每个工具对应的成员类型来构建各个条目。

构造条目时，您可以省略 type，因为服务器会根据 name 推断它。响应中始终会包含该字段。这种类型定义不会改变条目序列化后的 JSON。如果请求中的条目仅设置了 name、enabled 和 permission_policy，则无论是否包含 type，该请求都是有效的。

自定义工具

自定义工具类似于 Messages API 中的用户定义的客户端工具。您指定可用的操作及其返回内容，由 Claude 决定何时以及如何调用它们。

Claude 不会自行运行自定义工具。它会发出一个结构化请求，由您的代码执行该操作，然后您将结果返回给会话。

以下示例创建了一个包含内置工具集和一个自定义工具 get_weather 的智能体：

ant apply agent.md

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

自定义工具的名称不能以 mcp__ 或 ant__ 开头，也不能与内置智能体工具的名称相同。违反此规则的请求会返回 400 错误。如果某个智能体已有名称以 ant__ 开头的自定义工具，则只有当更新发送的 tools 中不包含该名称时，才会接受该更新，因此请在下一次更新中重命名或移除该工具。如果此类工具存在于新会话的智能体上（在应用任何覆盖之后）、存在于 subagents 的 predefined_agents 列表中的某个智能体上，或存在于 workflows 的 predefined_agents 列表中的某个智能体上，则该新会话会被拒绝并返回 400 错误。已存在的会话不受影响。

智能体会在会话期间调用其自定义工具。要接收这些调用并返回结果，请参阅会话事件流。

对于在自托管沙箱中运行的会话，环境工作进程可以从沙箱提供自定义工具。这些工具可以包括封装您网络内部 MCP 服务器的工具。

自定义工具定义的最佳实践

• 提供极其详细的描述。 这是迄今为止影响工具性能的最重要因素。您为 Claude 提供的工具上下文越多，它就越能判断何时以及如何使用这些工具。每个工具描述应力求包含三到四句话，如果工具较为复杂则应更多。您的描述应涵盖：
  • 工具的功能
  • 何时使用它，以及何时不应使用它
  • 每个参数的含义及其如何影响工具的行为
  • 任何重要的注意事项或限制
• 将相关操作整合到更少的工具中。 将 create_pr、review_pr 和 merge_pr 等操作归入一个带有 action 参数的单一工具中。更少但功能更强的工具可以减少选择上的歧义，并使 Claude 更容易驾驭您的工具集。
• 在工具名称中使用有意义的命名空间。 当您的工具跨越多个服务或资源时，请以资源作为名称前缀（例如 db_query 或 storage_read）。随着您的工具库增长，这可以使工具选择毫无歧义。
• 设计工具响应时仅返回高信号信息。 返回语义化、稳定的标识符（例如 slug 或 UUID），而不是不透明的内部引用。仅包含 Claude 确定下一步所需的字段。臃肿的响应会浪费上下文，并使 Claude 更难提取关键信息。

后续步骤