Claude 的工具使用

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

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

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5",
    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 定义模式的工具，例如 bash 和 text_editor）在您的应用程序中运行。Claude 以 stop_reason: "tool_use" 和一个或多个 tool_use 块进行响应。您的代码执行该操作并发送回 tool_result。服务器工具（例如 web_search、web_fetch、code_execution 和 tool_search）在 Anthropic 的基础设施上运行：您无需处理执行即可直接看到结果，除非 Claude 在与您的某个客户端工具相同的并行工具调用组中调用该工具（请参阅停止原因和回退）。

以下是客户端工具的完整往返过程。第一个请求定义了一个 get_weather 工具，Claude 通过调用它来回答问题：响应携带一个 tool_use 块，您的代码运行查询，第二个请求在 tool_result 块中将结果发送回去，以便 Claude 可以回复答案。

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude 会返回一个 tool_use 块，指明工具名称及其参数。
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    # 要求每轮最多调用一个工具。
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# 运行工具，然后将结果放在 tool_result 块中发送回去。
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude 使用该结果来回答最初的问题。
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

处理工具调用详细介绍了每个步骤，包括结果格式化和错误信号传递；并行工具使用介绍了一次调用多个工具的响应。要跳过自己编写这个往返过程，请使用 Tool Runner：SDK 会执行您的工具并自动将结果发送回去。

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

要连接到 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 标头，请参阅工具参考。



您自己的工具

对于您定义的工具，您编写模式，您的应用程序执行每个调用。



Anthropic 模式的客户端工具

Anthropic 发布模式并基于该模式训练 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 搜索工具和代码执行工具。



后续步骤