# Claude 的工具使用

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

---

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

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

<CodeGroup>
```bash cURL
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?"}]
  }'
```

```bash CLI
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?"}'
```

```python Python
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)
```

```typescript TypeScript
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);
```
</CodeGroup>

---

## 工具使用的工作原理

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

有关完整的概念模型，包括 agentic 循环以及何时选择每种方法，请参阅[工具使用的工作原理](/docs/en/agents-and-tools/tool-use/how-tool-use-works)。

有关连接到 MCP 服务器，请参阅 [MCP 连接器](/docs/en/agents-and-tools/mcp-connector)。有关构建自己的 MCP 客户端，请参阅 [modelcontextprotocol.io](https://modelcontextprotocol.io/docs/develop/build-client)。

<Tip>
**通过严格工具使用保证 schema 一致性**

在工具定义中添加 `strict: true`，以确保 Claude 的工具调用始终与你的 schema 完全匹配。请参阅[严格工具使用](/docs/en/agents-and-tools/tool-use/strict-tool-use)。
</Tip>

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

---

## 工具使用示例

有关完整的实践演练，请参阅[教程](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)。有关各个概念的参考示例，请参阅[定义工具](/docs/en/agents-and-tools/tool-use/define-tools)和[处理工具调用](/docs/en/agents-and-tools/tool-use/handle-tool-calls)。

<section title="当 Claude 需要更多信息时会发生什么">

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

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

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

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

</section>

---

## 定价

工具使用请求的定价基于：
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 数量          |
|--------------------------|------------------------------------------------------|---------------------------------------------|
| Claude Opus 4.7                | `auto`, `none`<hr />`any`, `tool`   | 346 tokens<hr />313 tokens |
| Claude Opus 4.6              | `auto`, `none`<hr />`any`, `tool`   | 346 tokens<hr />313 tokens |
| Claude Opus 4.5            | `auto`, `none`<hr />`any`, `tool`   | 346 tokens<hr />313 tokens |
| Claude Opus 4.1            | `auto`, `none`<hr />`any`, `tool`   | 346 tokens<hr />313 tokens |
| Claude Opus 4（[已弃用](/docs/en/about-claude/model-deprecations)） | `auto`, `none`<hr />`any`, `tool`   | 346 tokens<hr />313 tokens |
| Claude Sonnet 4.6          | `auto`, `none`<hr />`any`, `tool`   | 346 tokens<hr />313 tokens |
| Claude Sonnet 4.5          | `auto`, `none`<hr />`any`, `tool`   | 346 tokens<hr />313 tokens |
| Claude Sonnet 4（[已弃用](/docs/en/about-claude/model-deprecations)） | `auto`, `none`<hr />`any`, `tool`   | 346 tokens<hr />313 tokens |
| Claude Haiku 4.5         | `auto`, `none`<hr />`any`, `tool`   | 346 tokens<hr />313 tokens |
| Claude Haiku 3.5（[已退役，Bedrock 和 Vertex AI 除外](/docs/en/about-claude/model-deprecations)） | `auto`, `none`<hr />`any`, `tool`   | 264 tokens<hr />340 tokens |

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

请参阅[模型概览表](/docs/en/about-claude/models/overview#latest-models-comparison)了解当前各模型的价格。

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

---

## 后续步骤

### 选择你的路径

<CardGroup>
  <Card href="/docs/en/agents-and-tools/tool-use/how-tool-use-works" title="理解概念">
    工具的运行位置、循环的工作原理以及何时使用工具。
  </Card>
  <Card href="/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent" title="逐步构建">
    教程：从单个工具调用到生产环境。
  </Card>
  <Card href="/docs/en/agents-and-tools/tool-use/tool-reference" title="浏览所有工具">
    Anthropic 提供的工具和属性目录。
  </Card>
</CardGroup>