Claude 的工具使用

将 Claude 连接到外部工具和 API。了解工具的执行位置以及 agentic 循环的工作原理。

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

以下是使用服务器端工具的最简单示例，其中 Anthropic 负责执行：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "tools": [{"type": "web_search_20260209", "name": "web_search"}],
    "messages": [{"role": "user", "content": "What'\''s the latest on the Mars rover?"}]
  }'

ant messages create --transform content --format yaml \
  --model claude-opus-4-7 \
  --max-tokens 1024 \
  --tool '{type: web_search_20260209, name: web_search}' \
  --message '{role: user, content: "What is the latest on the Mars rover?"}'

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-7",
    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)

import Anthropic from "@anthropic-ai/sdk";

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

工具使用的工作原理

工具的主要区别在于代码的执行位置。客户端工具（包括用户定义的工具和 Anthropic-schema 工具，如 bash 和 text_editor）在你的应用程序中运行：Claude 返回 stop_reason: "tool_use" 和一个或多个 tool_use 块，你的代码执行操作，然后你发送回 tool_result。服务器端工具（web_search、code_execution、web_fetch、tool_search）在 Anthropic 的基础设施上运行：你可以直接看到结果，无需处理执行过程。

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

有关连接到 MCP 服务器，请参阅 MCP 连接器。有关构建自己的 MCP 客户端，请参阅 modelcontextprotocol.io。

工具访问是你可以赋予 agent 的最高杠杆原语之一。在 LAB-Bench FigQA（科学图表解读）和 SWE-bench（真实世界软件工程）等基准测试中，即使添加基本工具也能产生巨大的能力提升，通常超越人类专家基线。

工具使用示例

有关完整的实践演练，请参阅教程。有关各个概念的参考示例，请参阅定义工具和处理工具调用。

当 Claude 需要更多信息时会发生什么

如果用户的提示没有包含足够的信息来填充工具的所有必需参数，Claude Opus 更有可能识别出缺少参数并要求提供。Claude Sonnet 可能会询问，特别是在被要求在输出工具请求之前思考时。但它也可能尽力推断合理的值。

例如，给定一个需要 location 参数的 get_weather 工具，如果你问 Claude "天气怎么样？" 而没有指定位置，Claude（特别是 Claude Sonnet）可能会对工具输入进行猜测：

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": { "location": "New York, NY", "unit": "fahrenheit" }
}

这种行为并不保证，特别是对于更模糊的提示和不太智能的模型。如果 Claude Opus 没有足够的上下文来填充必需参数，它更有可能用澄清问题来回应，而不是进行工具调用。

定价

工具使用请求的定价基于：

1. 发送到模型的输入 token 总数（包括 tools 参数中的内容）
2. 生成的输出 token 数量
3. 对于服务器端工具，基于使用的额外定价（例如，网络搜索按每次搜索收费）

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

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

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

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

这些 token 计数会添加到你的正常输入和输出 token 中，以计算请求的总成本。

请参阅模型概览表了解当前各模型的价格。

当你发送工具使用提示时，与任何其他 API 请求一样，响应将输出输入和输出 token 计数，作为报告的 usage 指标的一部分。

后续步骤

选择你的路径