Claude Advanced Tool Use 完全指南

为什么需要 Claude Advanced Tool Use：文本模型触达不了外部系统 → 工具调用补齐 Agent 闭环

传统做法下，让模型「调用外部系统」通常靠两种方式：一是用正则或模板强行解析模型输出中的 JSON，输出稍有偏差就断裂，且解析结果无法被模型感知纠错；二是微调模型模仿固定输出格式，成本高、泛化差，换一个业务场景就要重训。这两种方式都无法支撑「查完订单再改地址」「读完代码再跑测试」这类多步、多工具的复杂任务。

Tool Use 把交互变成协议：模型在回答中输出类型化的 tool_use 块（含工具名、参数），开发者执行真实函数后把 tool_result 块放回消息序列，模型基于真实结果继续推理。判断、执行、反馈各司其职，无需任何文本解析，且模型能看到执行结果并自我纠错。官方评测（TAU-bench、SWE-bench Verified）显示，这条链路在零售客服、机票预订、代码修复等复杂任务上已能达到 80%+ 的端到端准确率。

与 LangChain 等框架的抽象不同，Claude Tool Use 是模型原生的协议能力：无框架绑定、无中间层开销，SDK 只负责传输，工具调用逻辑完全由开发者掌控。这意味着你可以把它嵌入任何语言、任何编排引擎（包括自研 Agent 循环），而不会被框架的 Agent 抽象限制。

安装与环境配置：3 步就绪

步骤一·安装官方 Python SDK。Tool Use 不是一个独立安装包，而是 Messages API 的能力，通过官方 SDK 调用：

步骤二·配置 API 密钥。在 Anthropic Console 中创建密钥，写入环境变量。密钥属于敏感凭据，不要提交到代码仓库：

步骤三·验证连通性。用一个最小工具定义发起一次请求，确认返回 stop_reason 为 tool_use，说明协议链路已通：

pip install -U anthropic

export ANTHROPIC_API_KEY=sk-ant-xxxxxxxx

python -c "import anthropicc = anthropic.Anthropic()r = c.messages.create(model='claude-sonnet-4-5', max_tokens=128,    tools=[{'name':'ping','description':'测试工具','input_schema':{'type':'object','properties':{'text':{'type':'string'}},'required':['text']}}],    messages=[{'role':'user','content':'用 ping 工具，text 传 hello'}])print(r.stop_reason)  # 期望输出 tool_use"

快速上手：20 分钟跑通「模型调天气工具」

核心思路是一个最多 N 轮的 while 循环：调用模型 → 检查 stop_reason → 若为 tool_use 则执行工具并回传结果 → 再次调用模型，直到模型给出最终文本回答。完整可运行代码如下（约 30 行）：

运行后你会看到模型先输出 tool_use 意图，程序执行 get_weather 后回传结果，模型最终给出「北京：晴，22°C」的回答。进阶技巧：把 max_tokens 提到 4096+ 并开启流式（client.messages.stream），首字延迟更低；多个独立工具调用（如同时查天气和订机票）可在一个 tool_result 列表里并行回传。

import anthropic client = anthropic.Anthropic() def get_weather(city: str) -> str:    return f"{city}：晴，22°C"  # 演示用，生产环境替换为真实天气 API tools = [{    "name": "get_weather",    "description": "查询指定城市的实时天气；当用户询问天气时调用",    "input_schema": {        "type": "object",        "properties": {            "city": {"type": "string", "description": "城市名，如北京"}        },        "required": ["city"],    },}] messages = [{"role": "user", "content": "北京今天天气如何？"}] for _ in range(5):  # Agent 循环，最多 5 轮防止死循环    resp = client.messages.create(        model="claude-sonnet-4-5",        max_tokens=1024,        tools=tools,        messages=messages,    )    if resp.stop_reason == "tool_use":        tool_results = []        for block in resp.content:            if block.type == "tool_use":                tool_results.append({                    "type": "tool_result",                    "tool_use_id": block.id,   # 必须使用 API 返回的真实 id                    "content": get_weather(**block.input),                })        messages += [            {"role": "assistant", "content": resp.content},  # 原样带回 tool_use 块            {"role": "user", "content": tool_results},       # 紧跟 tool_result 块        ]    else:        print(resp.content[0].text)        break

核心能力详解：5 大支柱

支柱一·结构化工具协议。每个工具是一个 JSON Schema 定义：name（全局唯一，匹配正则 ^[a-zA-Z0-9_-]{1,64}$）、description（写明何时用、何时不用）、input_schema（属性类型、必填项、示例值）。响应中 tool_use 块携带 id、name、input，开发者必须用真实 tool_use_id 回传 tool_result，协议全程可校验，任何语言 SDK 行为一致。

支柱二·并行工具调用。Claude 3.5 起支持一次响应返回多个相互独立的 tool_use 块，官方文档称可将任务往返轮次减少最多约 90%。但并行只适用于无依赖的调用：如果工具 B 的输入依赖工具 A 的输出，必须把 A 的结果回传模型，让模型在下一轮决定如何调用 B。

支柱三·多步工具链与 Agent 循环。标准循环模式：调用模型 → 检查 stop_reason → 执行 → 回传 → 重复。Claude 3.7 起支持扩展思考（thinking 块），模型在调用工具前先推理、给出调用理由，显著降低无效调用次数；开启后必须把 thinking 块和 tool_use 块一起原样回传，否则报错。

支柱四·调用控制（tool_choice）。四种取值：auto（默认，模型自主决定）、any（强制至少调用一个工具，适合工具优先的 Agent）、{"type":"tool","name":"..."}（强制指定某个工具，适合结构化抽取）、none（禁止调用）。注意扩展思考模式下不支持强制指定工具。

支柱五·大型结果与成本治理。tool_result 超过约 30k tokens 会被截断或忽略，需先摘要再回传；工具结果支持多模态内容块（图片、PDF），可配合截图识别使用。工具定义可以通过 prompt caching（cache_control: {"type": "ephemeral"}）缓存，缓存命中的输入 token 成本降低约 90%，适合工具众多（如 MCP 场景）的部署。

生产部署与监控：从上线到运维

循环工程化。Agent 循环要处理三类问题：一是限流与过载错误（HTTP 429/529），用指数退避加重试；二是模型幻觉，tool_use.input 可能缺字段或类型错误，回传前按 input_schema 做校验（可用 jsonschema 库）；三是死循环，必须设置最大轮次与单轮超时。工具执行要幂等——同一 tool_use_id 重复执行不能产生副作用。

成本与延迟治理。流式输出（SSE）让首 token 更快，适合长链路任务；用 /v1/messages/count_tokens 在请求前估算 token 用量，防止超预算；离线批量场景用 Message Batches API（24 小时内完成，价格 50% 折扣）跑评测集；稳定的工具定义用 prompt caching 复用，输入成本降约 90%。

可观测性。为每次请求记录 message id、stop_reason、工具名称、tool_use 输入与 tool_result 输出、prompt/output token 数；用 OpenTelemetry 把多轮调用串成一条 trace，定位「哪一轮工具调用引入了错误」；维护业务 golden 数据集，在模型版本升级前自动跑回归评测——升级到更强模型并不总是意味着业务工具调用准确率提升，必须用数据说话。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>工具名必须匹配 ^[a-zA-Z0-9_-]{1,64}$ 且全局唯一，否则 API 返回 400；不要与内置工具（web_search、web_fetch、computer 等）重名。</li><li>tool_result 必须在同一轮往返中回传：assistant 消息后紧跟一条包含全部 tool_result 的 user 消息；跨轮返回、漏返回或伪造 tool_use_id 都会报错。</li><li>tool_result 超过约 30k tokens 会被截断，先把大结果摘要/截断再回传；开启扩展思考时，后续请求必须原样带回 assistant 的 thinking 块。</li></ul>

版本迭代

Tool Use 从 Claude 3 的公开测试版演变为 Claude 4.5 系列的生产级核心能力：beta → GA（3.5）→ 与扩展思考结合的 Agentic 工具调用（3.7）→ 多步推理与工具失败自愈能力显著增强（4 / 4.5）。迭代主线是「调用可靠性 + 思考深度」双重提升。

AI 应用场景

常见误区

面试题