原厂 SDK 03:Claude Anthropic SDK——Messages API 结构与显式 Tool Use 状态循环

原厂 SDK 03:Claude Anthropic SDK——Messages API 结构与显式 Tool Use 状态循环
Asaakii与 OpenAI 推出 Agents SDK 封装自动循环的路线不同,Anthropic 在其官方 Python SDK(anthropic)中长期坚持一种更为朴素、透明的工程哲学:不做黑盒化的运行时封装,将协议层与状态驱动的主动权完全交还给开发者。
在许多生产级复杂 Agent 架构(如 Claude Code 或开源的 Harness 体系)中,工程师往往更青睐 Anthropic 的这种设计。因为所有网络交互、消息追加与工具执行都是完全可见且可拦截的,不存在框架暗中发起的隐式请求。
安装与客户端基础
通过官方包安装:
1 | pip install anthropic |
初始化客户端并读取环境变量:
1 | import os |
对于高吞吐异步服务,使用 anthropic.AsyncAnthropic(...) 即可。
Messages API 核心契约
Anthropic 的 Messages API 在数据结构上有几处非常明确的规范设计:
system提示词独立于消息列表:不将 System 提示混在messages数组里作为一种特殊角色,而是作为顶层命名参数传入;- 严格的角色交替规则:
messages列表必须严格维持user与assistant的交替流转; content并非纯文本,而是内容块列表(List[ContentBlock]):模型的响应中,文本、工具调用请求、思维推理过程都是平级的块对象。
flowchart TD
Req["client.messages.create(system=..., messages=..., tools=...)"] --> Resp["Message 响应对象"]
Resp --> Attr1["message.stop_reason (控制流状态指示)"]
Resp --> Attr2["message.usage (输入/输出 Token 账单)"]
Resp --> Attr3["message.content (内容块列表 List[ContentBlock])"]
Attr3 --> B1["Block: TextBlock (纯文本解释)"]
Attr3 --> B2["Block: ToolUseBlock (包含 id, name, input)"]
Attr3 --> B3["Block: ThinkingBlock (深度推演链)"]
基础单轮与系统提示
1 | response = client.messages.create( |
显式 Tool Use 状态机驱动循环
Claude 实现工具调用的核心是 stop_reason 字段。当模型判断需要调用外部工具辅助推演时,它不会直接生成最终答复,而是返回 stop_reason == "tool_use"。
完整的驱动循环拓扑如下:
flowchart TD
Start(["用户提问"]) --> BuildMsg["构建初始 messages 列表"]
BuildMsg --> PostCall["发起 client.messages.create 调用"]
PostCall --> CheckStop{"检查 response.stop_reason"}
CheckStop -- "stop_reason == 'tool_use'" --> ExtractTC["提取所有 type == 'tool_use' 的块"]
ExtractTC --> ExecTool["根据 name 与 input 执行本地函数"]
ExecTool --> AssembleRes["构建 type == 'tool_result' 的回传块"]
AssembleRes --> AppendHist["追加 assistant 消息与 user(tool_results) 消息"]
AppendHist --> PostCall
CheckStop -- "stop_reason == 'end_turn'" --> ExtractText["提取 TextBlock 内容"]
ExtractText --> Finish(["交付最终结果"])
代码实现:生产级白盒工具循环
1 | import json |
Extended Thinking:扩展思考与推理预算
从 Claude 3.7 开始,Anthropic 引入了原生的 Extended Thinking(扩展思考) 机制。模型在生成最终内容或决定调用工具之前,会先在独立的 thinking 内容块中展开深度推演。
开发者可以通过 budget_tokens 显式控制思考预算,权衡推理深度与 Token 成本:
1 | response = client.messages.create( |
这种将推演过程独立建模的做法,使得在生产排错时可以清晰复盘模型“为什么做这个决策”,而无需在 Prompt 里手写“Let’s think step by step”。
为什么企业生产架构青睐显式工具循环?
相比于全自动框架,手动编写 Tool Use 循环为高要求工程系统带来了三项核心保障:
- 确定的权限拦截与准入审计:在
tool_registry[tub.name](**tub.input)执行之前,可以无缝插入本地校验、风控过滤或向前端推送“用户确认授权”弹窗,没有框架层的隐式旁路; - 故障隔离与异常回填:如果本地工具执行崩溃(如数据库连接超时),开发者可以捕获异常并构造
{"type": "tool_result", "is_error": True, "content": "连接超时"}回传给模型,引导模型自主重试或降级,而不是导致整个应用抛出未捕获异常; - 断点续跑与持久化友好:由于消息结构完全由普通的 Python dict 组成,每一轮往返后都可以直接序列化存入 Redis 或 PostgreSQL,天然契合长生命周期工作流。
下一篇我们将把 OpenAI、Google 与 Anthropic 三大 SDK 放在同一维度进行横向横评,梳理从研发验证到企业生产的最佳选型路线。











