Anthropic Claude API 开发指南：模型、工具与智能体

Anthropic 官方把 Claude 定位为面向"长周期智能体、复杂编码与企业级工作负载"的模型家族。在 Claude Opus 5 发布之后，全系模型都支持文本与图像输入、多语言和视觉能力，可通过 Claude API、Amazon Bedrock、Google Cloud 与 Microsoft Foundry 等多种渠道调用。

一、Claude 模型矩阵

官方把模型按任务场景分为四档：

Claude Fable 5：当前能力最强的通用模型，面向长时间运行的智能体任务，上下文 1M token、最大输出 128k。
Claude Opus 5：复杂智能体编码与企业级工作的首选，能力与成本平衡点更好。
Claude Sonnet 5：速度与智能的最佳组合，适合绝大多数在线业务；发布初期有促销价。
Claude Haiku 4.5：最快、最便宜的模型，面向高频轻量任务，支持扩展思考。

把四档放到一张表里对比更直观（价格按每百万 token，输入/输出）：

模型	定位	上下文	参考价（入/出）	典型场景
Fable 5	最强通用	1M token	$10 / $50	长周期智能体、深度推理
Opus 5	能力/成本平衡	200k+	$5 / $25	复杂编码、企业级任务
Sonnet 5	速度智能兼备	200k+	$3 / $15	在线业务、客服、摘要
Haiku 4.5	最快最省	200k+	$1 / $5	分类、抽取、高频轻量

选型建议：不确定时从 Opus 5 起步；需要极致能力用 Fable 5；成本敏感、延迟敏感的在线服务用 Sonnet 5 或 Haiku 4.5。所有 Claude 模型 ID 都是固定快照，不会像某些平台那样热切换版本，便于生产锁定。

二、Messages API：一次调用入门

Claude 的核心接口是 Messages API。请求由系统提示（system）+ 消息数组（messages，role 为 user/assistant）组成，其中 max_tokens 是必填参数：

from anthropic import Anthropic
client = Anthropic()
resp = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="你是网站客服助手。",
    messages=[{"role": "user", "content": "介绍一下退款政策"}],
)
print(resp.content[0].text)

消息数组支持多轮对话与多模态内容块（content blocks），图像以 base64 或 URL 形式传入即可。

三、工具调用与流式输出

工具调用（Tool Use）：在请求里声明 tools，模型返回 tool_use 内容块，代码执行后以 tool_result 回传，模型继续生成。Claude 官方强调工具描述要写清楚"何时使用、参数含义、返回格式"，工具数量控制在合理范围以降低混淆。

一个最小例子：让模型查询订单状态。

tools = [{
    "name": "get_order_status",
    "description": "按订单号查询发货状态",
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
    },
}]
resp = client.messages.create(
    model="claude-sonnet-5", max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "订单 20260714001 发货了吗？"}],
)

模型会先返回 tool_use 块，你的代码查库后把结果以 tool_result 回传，Claude 再基于真实数据组织回答。这就是"让模型动手查数据"的标准姿势。

流式输出（Streaming）：通过 SSE 逐块返回内容，可显著改善对话体感，适合聊天机器人场景。SDK 里用 stream=True 即可逐块处理：

with client.messages.stream(
    model="claude-sonnet-5", max_tokens=1024,
    messages=[{"role": "user", "content": "写一段 50 字的产品简介"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

思考机制（Thinking）：新一代模型默认开启自适应思考（adaptive thinking），可用 effort 参数在"更快 vs 更深入"之间权衡；复杂推理、长链路智能体建议显式设置较高思考强度。

四、Claude Code 与 Agent SDK

Claude Code：终端里的智能体编程助手，可以读写文件、执行命令、调用子智能体（subagents），并通过 MCP（Model Context Protocol）连接外部工具与数据源。它把"AI 编码智能体"从概念变成可日常使用的工具。
Agent SDK：官方提供的 TypeScript/Python 智能体构建库，与 Claude API 深度集成，支持工具编排、多智能体协作与生产级生命周期管理。用它之前建议先掌握 AI 智能体开发基础里的概念。

五、定价与成本策略

Claude 按输入/输出 token 计费（每百万 token），当前参考价：Fable 5 为 $10/$50，Opus 5 为 $5/$25，Sonnet 5 为 $3/$15，Haiku 4.5 为 $1/$5。

算一笔账：一个日活 1 万的客服机器人，平均每次会话 800 输入 token + 300 输出 token，用 Sonnet 5 一天大约消耗 800 万输入 token 与 300 万输出 token，按 $3/$15 折算约 $24 + $45 = $69/天；同样的量路由到 Haiku 4.5 则降到 $8 + $15 = $23/天，差价在规模化后非常可观。省钱要点：

批量接口（Batch API）：非实时任务有折扣，离线处理首选。
提示缓存（Prompt Caching）：系统提示与长上下文命中缓存后，输入成本大幅下降。
按需降级：高成本任务用 Opus，常规任务路由到 Sonnet/Haiku，配合统一网关做预算治理（参考 AI 网关预算上限实践）。

六、16IDC 落地建议

Claude 在长上下文与"诚实回答"上的表现，让它很适合知识库问答、客服机器人与内容审核类业务，接入方式可参考网站接入 AI 聊天机器人。它的消息数组与工具调用设计清晰，建议先用官方 SDK 跑通原型，再叠加 RAG（RAG 实现指南）与缓存策略上线。别忘了为服务器选型预留日志、缓存与向量检索的算力——多轮对话的会话状态与知识库索引仍然跑在你自己这边。

七、常见问题

多轮对话的上下文要自己管理吗？ 要。Messages API 是无状态的，需要把历史消息拼进 messages 数组，或用会话层把最近 N 轮维护在缓存里，避免上下文无限膨胀。
遇到速率限制（rate limit）怎么办？ SDK 自带重试，可以配合指数退避；超长任务改用 Batch API，避免占满并发额度。
能换区域或渠道部署吗？ 可以，同一模型在 Bedrock、Vertex AI 与 Foundry 上都能调用，适合数据驻留或多云容灾的场景。

原文来源：https://platform.claude.com/docs/en/docs/about-claude/models/overview
参考：Messages API https://platform.claude.com/docs/en/docs/api/messages
参考：Tool Use https://platform.claude.com/docs/en/docs/agents-and-tools/tool-use/overview
参考：Prompt Caching https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching

Anthropic Claude API 开发指南：模型、工具与智能体