Claude API 工具调用实战：让模型连接外部世界
上一章我们学了 Prompt Caching 来降低成本。但光是对话还不够——真正强大的 AI 应用需要 Claude 能调用外部工具：查数据库、调 API、执行代码、搜索网页。这就是 Tool Use。
本章从零构建一个带工具调用的 Agent，覆盖完整的请求-响应循环，以及如何将工具定义与 Prompt Caching 结合实现最优成本。
Tool Use 的工作模型
Tool Use 的核心是一个循环：
Claude 不直接执行工具代码。它返回一个结构化的调用请求（函数名 + 参数），你的应用负责实际执行，然后把结果回传。
两类工具：Client Tools（你定义 + 你执行）和 Server Tools（Anthropic 提供并执行，如 web_search）。本章聚焦 Client Tools——你自己定义的工具。
定义工具
工具通过 tools 参数传入，每个工具需要名称、描述和 JSON Schema 格式的参数定义：
工具描述的质量直接影响 Claude 的调用准确率。写清楚：这个工具做什么、什么时候该用它、参数的含义和格式要求。好的描述 > 短的描述。
处理工具调用循环
当 Claude 决定调用工具时，响应的 stop_reason 为 "tool_use"，content 包含 tool_use 块：
接下来你执行实际的工具逻辑，把结果发回 Claude：
完整 Agent 循环
实际应用中，Claude 可能连续调用多个工具，或根据第一个工具的结果再调第二个。你需要一个循环来处理：
Agent 循环需要设置最大迭代次数（如 10 次），防止无限循环。在生产环境中，还应该对每次工具调用做超时和错误处理。
控制工具选择：tool_choice 参数
tool_choice 控制 Claude 何时以及如何使用工具：
| tool_choice | 行为 | 适用场景 |
|---|---|---|
auto（默认） | Claude 决定是否调用 | 通用对话 + 工具 |
tool + name | 必须调用指定工具 | 结构化信息提取 |
any | 必须调用某个工具 | 强制 Agent 行动 |
none | 禁用工具 | 需要纯文本回复时 |
严格模式：保证 Schema 符合
添加 strict: true 确保 Claude 的工具调用严格遵守你的 JSON Schema：
严格模式在生产环境中强烈推荐。没有它时，Claude 偶尔会返回不符合 schema 的参数（如 required 字段缺失），导致下游代码报错。
与 Prompt Caching 结合
工具定义在缓存层级中排第一——tools → system → messages。这意味着：
- 如果工具定义不变（大多数应用是这样），它们会被缓存，后续请求免费读取
- 如果你频繁增删工具，整个缓存链条都会失效
最佳实践：
成本效果：
| 组件 | 首次请求 | 后续请求 |
|---|---|---|
| tools 定义（~500 tokens） | 1.25x（写入） | 0.1x（读取） |
| system prompt（~200 tokens） | 1.25x（写入） | 0.1x（读取） |
| 对话历史（增长中） | 1.25x（写入） | 0.1x（读取） |
| 新用户消息 | 1x（正常） | 1x（正常） |
在一个 10 轮对话中，工具定义 + system prompt 被缓存读取 9 次，每次节省 90%。
流式响应中的工具调用
流式传输时，工具调用也是增量返回的：
并行工具调用
Claude 可以在单个回复中返回多个 tool_use 块，表示需要并行调用多个工具：
错误处理
工具执行失败时，发送带 is_error: true 的结果让 Claude 知道：
Claude 收到错误后通常会：告知用户出了问题、尝试用不同参数重试、或改用其他方式回答。
实战示例：带缓存的客服 Agent
把前一章的 Prompt Caching 和本章的 Tool Use 结合起来：
总结
| 概念 | 要点 |
|---|---|
| 工具定义 | name + description + input_schema（JSON Schema） |
| 调用循环 | 检查 stop_reason == "tool_use" → 执行 → 发回 tool_result → 重复 |
| tool_choice | auto（默认）/ tool（强制指定）/ any（强制任一）/ none（禁用） |
| strict 模式 | 生产环境推荐，保证参数严格符合 schema |
| 并行调用 | 单个回复可能含多个 tool_use 块，应并行执行 |
| 错误处理 | is_error: true 告知 Claude 执行失败 |
| 缓存结合 | tools 在缓存层级最前，保持稳定可获得最大缓存收益 |
下一步：你可以将 Tool Use 与 Extended Thinking 结合，让 Claude 在复杂决策场景中先深度推理再调用工具，进一步提升 Agent 的准确率。