Claude 的工具使用

工具使用让 Claude 能够调用您定义的函数或 Anthropic 提供的函数。Claude 会根据用户的请求和工具的描述来决定何时调用工具。然后它会返回一个结构化的调用，由您的应用程序执行（客户端工具）或由 Anthropic 执行（服务器工具）。

以下是一个使用服务器工具的最小示例，即 Web 搜索工具，该工具由 Anthropic 为您执行：

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

Claude 在 Anthropic 的基础设施上运行搜索，并在同一响应中返回带引用的结果。如果要让 Claude 调用您定义的函数，请传递一个带有 input_schema 的工具，然后在 Claude 返回 tool_use 块时执行该调用。定义工具和处理工具调用涵盖了这一完整往返流程。



工具使用的工作原理

工具的主要区别在于代码的执行位置。客户端工具（包括用户定义的工具以及具有 Anthropic 定义的 schema 的工具，如 bash 和 text_editor）在您的应用程序中运行。Claude 会以 stop_reason: "tool_use" 和一个或多个 tool_use 块作为响应。您的代码执行该操作并返回一个 tool_result。服务器工具（如 web_search、web_fetch、code_execution 和 tool_search）在 Anthropic 的基础设施上运行：您可以直接看到结果而无需处理执行过程，除非 Claude 在与您的某个客户端工具相同的并行工具调用组中调用该工具（请参阅停止原因和回退）。

有关完整的概念模型（包括智能体循环以及何时选择每种方法），请参阅工具使用的工作原理。

有关连接到 "Model Context Protocol"，即 MCP 服务器的信息，请参阅 MCP 连接器。有关构建您自己的 MCP 客户端的信息，请参阅 Model Context Protocol 指南中的构建 MCP 客户端。



Claude 何时使用工具

在默认的 tool_choice 为 {"type": "auto"} 时，Claude 会在每个回合决定是调用工具还是直接响应。当请求与某个工具所描述的能力相匹配且答案尚不在上下文中时，它会调用工具。对于稳定的知识、创意任务和对话性回合，它会直接响应。

这一边界可以通过您的系统提示进行引导。如果 Claude 没有在您预期的时候调用工具，一条轻量级的指令（如 "Use the tools to investigate before responding."）可以增加工具使用。更强的形式（如 "Always call a tool first before responding."）会进一步推动。相反，"Use your judgment about whether to call a tool or respond directly." 会使触发行为保持保守。

如果要强制要求工具调用而不是依赖提示，请设置 tool_choice。

每个服务器工具的页面都更详细地描述了其自身的触发边界。



选择工具

有关 type 字符串、版本和 beta 标头，请参阅工具参考。



您自己的工具

对于您定义的工具，您需要编写 schema，并由您的应用程序执行每次调用。



Anthropic schema 客户端工具

Anthropic 发布 schema 并基于此训练 Claude。您的应用程序仍然执行每次调用并返回 tool_result。



服务器工具

服务器工具在 Anthropic 的基础设施上运行，您的应用程序中无需处理程序代码。有关它们共享的机制，请参阅服务器工具。



定价

工具使用请求的定价基于以下因素：

1. 发送给模型的输入令牌总数（包括 tools 参数中的令牌）
2. 生成的输出令牌数量
3. 对于服务器端工具，还会产生基于使用量的额外费用（例如，网络搜索按每次执行的搜索收费）

客户端工具的定价与任何其他 Claude API 请求相同，而服务器端工具可能会根据其具体使用情况产生额外费用。

工具使用产生的额外令牌来自：

• API 请求中的 tools 参数（工具名称、描述和模式）
• API 请求和响应中的 tool_use 内容块
• API 请求中的 tool_result 内容块

当您使用 tools 时，API 还会自动为模型包含一个特殊的系统提示以启用工具使用。每个模型所需的工具使用令牌数量如下所列（不包括上述额外令牌）。请注意，该表格假设至少提供了 1 个工具。如果未提供任何 tools，则工具选择为 none 时使用 0 个额外的系统提示令牌。

这些令牌数量会加到您的正常输入和输出令牌中，以计算请求的总费用。

有关当前各模型的价格，请参阅模型概览表格。

当您发送工具使用提示时，与任何其他 API 请求一样，响应会在报告的 usage 指标中包含输入和输出令牌计数。

某些服务器工具会在令牌费用之外增加基于使用量的费用：有关其费率，请参阅 Web 搜索工具和代码执行工具。



后续步骤