工具 - Claude API Docs

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

自定义用户定义工具也受支持。您的应用程序单独执行这些工具，并将工具结果发送回 Claude；Claude 可以使用这些结果继续当前任务。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 头部。SDK 会自动设置 beta 头部。

可用工具

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

工具	名称	描述
Bash	`bash`	在 shell 会话中执行 bash 命令
Read	`read`	从本地文件系统读取文件
Write	`write`	将文件写入本地文件系统
Edit	`edit`	在文件中执行字符串替换
Glob	`glob`	使用 glob 模式进行快速文件模式匹配
Grep	`grep`	使用正则表达式模式进行文本搜索
Web fetch	`web_fetch`	从 URL 获取内容
Web search	`web_search`	在网络上搜索信息

配置工具集

创建智能体时，使用 agent_toolset_20260401 启用完整工具集。使用 configs 数组禁用特定工具或覆盖其设置。

禁用特定工具

要禁用某个工具，请在其配置条目中设置 enabled: false：

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}

仅启用特定工具

要从全部关闭开始，仅启用所需工具，请将 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 的能力，以执行更多种类的任务。每个工具定义一个契约：您指定哪些操作可用以及它们返回什么；Claude 决定何时以及如何调用它们。模型本身不会执行任何操作。它发出一个结构化请求，您的代码运行该操作，结果流回到对话中。

在智能体级别定义工具后，智能体将在会话过程中调用这些工具。请参阅会话事件流了解完整流程。

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

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

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "name": "Coding Assistant",
  "model": "claude-sonnet-4-6",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "configs": [
        {"name": "web_fetch", "enabled": false}
      ]
    }
  ]
}
EOF
)

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "name": "Weather Agent",
  "model": "claude-sonnet-4-6",
  "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"]
      }
    }
  ]
}
EOF
)