简介:Anthropic 没有另起一套接口替代 Messages,而是守住 `/v1/messages` 这个稳定核心,在其上逐层叠加 Agent SDK、托管 Agent、Compaction、Memory 等运行时能力。本文拆解这条演进路径的三层结构、每层的适用边界与接入方式,并给出跨平台统一接入与成本控制的实操建议;如果你正在做模型选型与成本评估,可以先看看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供模型能力对比、价格对比与统一 API 接入,能省掉大量横向调研工作。
如果说 OpenAI 的 API 演进主线是「从 Chat Completions 走向 Responses 运行时」,那么 Anthropic 的路径不同,但目标一致: Claude API 正在从「Messages 消息原语 + 开发者自编排」,演进为「Messages 原语 + 多层 Agent 运行时 + 托管平台能力」 。
Anthropic 没有废弃 Messages API,也没有推出一个替代性的新接口。它的策略是守住 /v1/messages 这个稳定核心,在上面叠加一层层运行时能力,让开发者按 控制粒度 自主选择接入深度。理解这条路径,对正在选型 Claude 的开发者同样关键。
很多团队在评估 Agent 平台时会担心「刚上手的接口会不会被废弃」。Anthropic 的做法恰好相反:
/v1/messages 保持向后兼容,请求/响应结构长期稳定;这意味着你可以从 20 行代码的裸调用起步,随着业务复杂度上升,逐步把上下文管理、子 Agent 编排、会话状态持久化「外包」给平台,而 不必重写业务代码 。这种渐进式路径对企业的实际价值在于:技术栈的沉没成本可控,试点和规模化可以走同一条演进曲线。
/v1/messages 是 Claude API 的根基,设计哲学与 OpenAI 早期的 Chat Completions 类似:你发一组消息,模型返回结构化的 content blocks(text、tool_use、thinking 等)。
但 Anthropic 在 Messages 上持续深耕,使它本身就能承载相当复杂的 Agent 工作流:
| 能力 | 作用 | 对 Agent 的意义 |
|---|---|---|
| Tool use | 模型返回 tool_use block,开发者执行后回传 tool_result |
自主决定工具调用时机 |
| Extended thinking | 推理过程以 thinking block 返回,可跨轮次传递 |
复杂推理任务保持思路连续 |
| Prompt caching | 块级或自动缓存,最高 90% 成本折扣 | 长 system prompt / 大文档场景显著降本 |
| Structured outputs | JSON Schema 约束输出格式 | 结果可直接进入下游系统 |
| Server-side tools | web search、web fetch、code execution 由 Anthropic 托管执行 | 无需自建工具链 |
最小可运行示例:
import anthropicclient = anthropic.Anthropic(api_key="your-api-key")resp = client.messages.create(model="claude-sonnet-4-5",max_tokens=1024,system="你是一名资深后端工程师",tools=[{"name": "get_weather", "description": "查询城市天气","input_schema": {"type": "object","properties": {"city": {"type": "string"}},"required": ["city"]}}],messages=[{"role": "user", "content": "北京今天适合跑步吗?"}],)for block in resp.content:if block.type == "tool_use":print("需调用工具:", block.name, block.input)elif block.type == "text":print(block.text)
优势 是控制粒度最细——你完整拥有 agent loop、上下文管理、工具执行逻辑,审计、灰度、降级都能自己掌控。 劣势 同样明显:多步工具调用、子 Agent、会话状态、Compaction 全部要自己实现,这部分工程量往往比接入模型本身大得多。
2025 年 9 月,Anthropic 将 Claude Code SDK 重命名为 Claude Agent SDK 。这不只是改名,而是明确了产品定位:把驱动 Claude Code 的同一套 Agent 运行时,开放给开发者嵌入自己的产品。
它提供两种接入方式:
| 方式 | 适用场景 | 特点 |
|---|---|---|
query() |
无状态、单次任务 | 约 20 行代码即可启动 Agent |
ClaudeSDKClient |
有状态、多轮对话 | 支持 Hooks 与细粒度权限控制 |
开箱即用的内置工具包括 Read、Write、Edit、Bash、Glob、Grep、WebSearch、WebFetch、Skill;配合 18 个生命周期 Hook(PreToolUse、PostToolUse、SubagentStart、PreCompact 等),开发者可以在 不重写 Agent loop 的前提下完成审计、拦截与行为改造。
import asynciofrom claude_agent_sdk import query, ClaudeAgentOptionsasync def main():options = ClaudeAgentOptions(system_prompt="你是一名资深 Python 开发者",model="claude-sonnet-4-5",permission_mode="acceptEdits",)async for message in query(prompt="实现一个快速排序函数并写测试", options=options):print(message)asyncio.run(main())
工程上最值得投入的是 Hook 机制。例如用 PreToolUse 拦截危险 Bash 命令、用 PostToolUse 记录全量工具调用日志、用 PreCompact 在上下文压缩前把关键结论写入外部存储——这些过去都需要 fork Agent 框架才能实现。
当 Agent 从 Demo 走向生产,最先崩的通常不是模型能力,而是 上下文 。长任务下 token 线性膨胀,成本与延迟同步失控,早期关键信息被挤出窗口。
托管层能力正是针对这些痛点:
判断是否需要托管层,有个简单标准: 如果你的 Agent 需要跑超过 10 轮工具调用,或者需要跨会话记住用户信息,自建成本通常高于接入成本。
| 接入层级 | 控制粒度 | 自建成本 | 推荐场景 |
|---|---|---|---|
| Messages API | 最高 | 高 | 定制化 Agent、强合规审计、已有编排框架 |
| Agent SDK | 中高 | 中 | 编码助手、运维 Agent、需要内置工具与 Hook |
| 托管 Agent | 较低 | 低 | 长任务、多轮客服、快速上线验证 |
一个务实的建议: 先用 Messages API 验证模型能力边界,再用 Agent SDK 补齐运行时,最后在长任务与状态管理上引入托管能力 。反过来做,很容易在需求尚未清晰时就锁死架构。
实际项目中很少只用一家模型。如果你的业务需要同时使用 Claude 与其他模型,可以借助 Anthropic 兼容端点 统一接入方式,把 Claude Code / Agent SDK 直接指向兼容网关。以百度智能云千帆为例,其 Anthropic 兼容接口的调用方式如下:
curl --location 'https://qianfan.baidubce.com/anthropic/v1/messages' \--header 'x-api-key: your-api-key' \--header 'anthropic-version: 2023-06-01' \--header 'Content-Type: application/json' \--data '{"model":"deepseek-v3.2","max_tokens":1000,"messages":[{"role":"user","content":"你好"}]}'
SDK 侧只需替换 base_url,即可复用原有代码:
client = anthropic.Anthropic(base_url="https://qianfan.baidubce.com/anthropic",api_key="your-api-key",)
Claude Code 则通过环境变量切换,把 ANTHROPIC_BASE_URL 指向兼容地址,并用 ANTHROPIC_MODEL、ANTHROPIC_SMALL_FAST_MODEL 指定模型,CLAUDE_CODE_MAX_OUTPUT_TOKENS 与 API_TIMEOUT_MS 按目标模型的最大输出和超时特性调整。若使用自定义 appid,还需通过 ANTHROPIC_CUSTOM_HEADERS 补全对应请求头。
这类兼容层的价值在于: Agent 代码与模型解耦 ,切换底座模型时无需改动业务逻辑。而在决定「换成哪个模型」之前,更稳妥的做法是先做横向对比——词元所的模型价格与性能对比能力,可以帮你把候选模型的调用成本、能力边界放在同一张表里评估,避免凭印象选型。
Claude API 的演进不只是能力叠加,也在改变成本结构:
评估总成本时,建议不要只算单价,而是按「单任务平均 token 消耗 × 任务量」建模,并把缓存命中率、压缩触发频率作为变量纳入测算。如果你需要频繁在多个模型之间做这类测算与统一接入,百度智能云词元所提供的多模型统一 API 接入与调用管理能力,可以降低这部分集成与运维开销。
Anthropic 的路线可以概括为一句话: 用一个稳定的 Messages 核心,托住多种控制粒度的 Agent 运行时 。对开发者的实际意义是,你不必在「完全自建」和「完全托管」之间二选一,而可以按业务阶段渐进迁移。真正需要提前想清楚的,是你的 Agent 究竟需要多细的控制粒度——这个问题回答对了,选 Messages、Agent SDK 还是托管平台,答案自然浮现。