工具

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

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



可用工具

智能体工具集包含以下工具。当您在智能体配置中包含该工具集时，所有工具默认启用。请使用"名称"列中的值在 configs 数组中引用工具。

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



配置工具集

创建智能体时，使用 agent_toolset_20260401 启用完整工具集。使用 configs 数组禁用特定工具或覆盖其设置。每个配置条目还可以设置 permission_policy，用于控制该工具的调用是自动批准还是需要确认。有关可用的策略类型，请参阅权限策略。

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
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 }
  ]
}



自定义工具

除了内置工具外，您还可以定义自定义工具。自定义工具类似于 Messages API 中的用户定义的客户端工具。

每个自定义工具都定义了一个契约：您指定可用的操作及其返回内容，Claude 则决定何时以及如何调用它们。模型本身从不执行任何操作。它会发出结构化请求，由您的代码运行该操作，然后将结果返回到对话中。有关如何在会话期间接收自定义工具调用并返回结果，请参阅会话事件流。

ant beta:agents create <<'YAML'
name: Weather Agent
model: claude-opus-4-8
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
YAML

在智能体上定义自定义工具后，智能体会在会话期间调用它们。



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

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



后续步骤