使用 Claude 进行工具使用

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

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

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-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 定义的 schema 的工具，例如 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-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-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 在每一轮中决定是调用工具还是直接响应。当请求与某个工具所描述的能力相对应，且答案尚不在上下文中时，它会调用该工具。对于稳定的知识、创意任务和对话性轮次，它会直接响应。

这一边界可以通过您的 "system prompt"（系统提示）进行引导。如果 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": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": { "location": "New York, NY", "unit": "fahrenheit" }
}

选择工具

有关 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 个额外的系统提示令牌。

Model	Tool use system prompt tokens
Name	Tool choice	Token count
Claude Opus 5.5For long-running agentic coding and knowledge work	auto, none	286 tokens
Claude Sonnet 5The best combination of speed and intelligence	auto, none	354 tokens
	any, tool	474 tokens
Claude Haiku 4.5The fastest model with near-frontier intelligence	auto, none	496 tokens
	any, tool	588 tokens
Additional models
Claude Opus 5	auto, none	286 tokens
	any, tool	406 tokens
Claude Opus 4.8	auto, none	290 tokens
	any, tool	410 tokens
Claude Opus 4.7	auto, none	675 tokens
	any, tool	804 tokens
Claude Opus 4.6	auto, none	497 tokens
	any, tool	589 tokens
Claude Opus 4.5	auto, none	496 tokens
	any, tool	588 tokens
Claude Opus 4.1	auto, none	313 tokens
	any, tool	315 tokens
Claude Opus 4	auto, none	313 tokens
	any, tool	315 tokens
Claude Sonnet 4.6	auto, none	497 tokens
	any, tool	589 tokens
Claude Sonnet 4.5	auto, none	496 tokens
	any, tool	588 tokens
Claude Sonnet 4	auto, none	313 tokens
	any, tool	315 tokens
Claude Haiku 3.5	auto, none	264 tokens
	any, tool	355 tokens

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

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

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

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

后续步骤