第 1 章 · 02 Claude API 全景与 SDK 总览

第 1 章 · 02 Claude API 全景与 SDK 总览

本节摘要:Claude API 是 Anthropic 提供给开发者的模型接入接口——一次 messages.create() 调用,带上传入消息、模型 ID、可选的 system prompt 与工具,就能拿到模型生成的回复。但它的能力远不止「问答」:工具调用(tool use)让模型动手干活,流式响应(streaming)让回复边生成边返回,提示缓存(prompt caching)能把长上下文的成本与延迟砍到十分之一,Token 计数让成本可预估,批处理(batches)与文件 API(files)则服务于离线大批量任务。本节俯瞰这些能力如何拼成一套完整的 Agent 开发工具箱,并梳理 Python、TypeScript、Go、Java、PHP、Ruby、C#、curl 八大形态的官方 SDK 各自覆盖了什么。读完本节,你建立了全书地图,知道每个能力在哪里展开。

内容来源:Anthropic 官方 Claude API 文档 bundled-skills/claude-api/SKILL.md 与各语言 README(随 Claude Code 分发,从泄露素材库提取),汉化并套用体系化模板。

学习目标

阅读完本节,你应当能够:

1. 写出一次最简的 messages.create() 请求,说明 model、max_tokens、messages、system 各参数的作用。
2. 在一张地图上指认 Claude API 的八大能力(消息、工具调用、流式、缓存、计数、模型、批处理、文件)及其典型用途。
3. 区分同步客户端与异步客户端、顶层 system 与 role:system 消息等概念在 API 中的位置。
4. 说出官方 SDK 覆盖的八种语言形态,以及「何时用 SDK、何时用原始 HTTP」的选择准则。
5. 知道第 2~7 章分别讲什么,能在需要时快速定位。

一、一次最简调用:摸清 API 的骨架

无论用哪种语言,接入 Claude API 的核心都是同一个端点 POST /v1/messages,Python 写法如下:

import anthropic

client = anthropic.Anthropic()  # 从环境变量读 ANTHROPIC_API_KEY

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system="You are a helpful coding assistant.",
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ],
)
for block in response.content:
    if block.type == "text":
        print(block.text)
​

这段代码浓缩了 API 的四个必填要素:model(用哪个模型,如 claude-opus-4-8)、max_tokens(最多生成多少 token)、messages(对话历史,首条必须是 user,user/assistant 交替)、以及可选的 system(系统提示词,见上一节)。返回的 response.content 是一个内容块列表——可能是文本块(TextBlock)、思考块(ThinkingBlock)、工具调用块(ToolUseBlock),要先判断 .type 再访问字段。

💡 两个容易踩的坑:其一,API 是无状态的——每次请求都要把完整对话历史发上去,服务端不替你记。其二,返回的是块列表而非纯字符串,因为有思考、工具调用等多种块类型并存。

二、八大能力:一张全景地图

Claude API 不只是「问答接口」,而是围绕 Agent 开发组织的一组能力。下面这张图是全书的核心地图,后续章节逐一展开:

把这八块按用途归类,就清晰了:

输入侧三件套——system(角色与规则)、tools(模型能调的外部函数)、messages(对话历史)。这三者按 tools → system → messages 的固定顺序渲染成最终提示,顺序很重要,直接影响缓存(第 2 章 03 节)。

核心调用——选模型(Fable 5 最强、Opus 自主、Sonnet 平衡、Haiku 快省)、让模型调工具(第 2 章 01 节)、让模型先思考再回答(adaptive thinking)。

优化与运维——流式响应降低首 token 延迟(第 2 章 02 节)、提示缓存把重复前缀成本砍到十分之一(第 2 章 03 节)、Token 计数让成本可预估(第 2 章 04 节)。

批量与托管——批处理做离线大批量推理、文件 API 上传大文件并在多请求间复用、托管代理(managed agents)则是平台替你跑有状态的 agent 循环(第 4 章 02 节)。

💡 读图提示:前四块(输入+核心调用)是「日常用法」,后四块(优化+批量托管)是「规模化的关键」。新手先把前四块用熟,等遇到成本、延迟、大批量问题时再深入后四块。

三、八种语言形态:官方 SDK 覆盖图

Anthropic 为以下八种语言/形态提供了官方接入方式,覆盖度从「主力 SDK」到「原始 HTTP」:

⚠️ 选择准则:只要你的语言有官方 SDK,优先用 SDK,不要用 requests/fetch 凑原始 HTTP。SDK 替你处理了认证、重试、超时、分页、错误类型化、beta 头注入等大量细节——尤其提示缓存、托管代理这种需要精细 header 的特性,手写 HTTP 极易出错。只有当项目就是 shell/cURL 工程、或语言无官方 SDK 时,才用原始 HTTP。

各 SDK 的客户端初始化模式高度一致,都以「从环境变量读 key、构造一个客户端」为默认:

# Python
import anthropic
client = anthropic.Anthropic()                       # 同步
async_client = anthropic.AsyncAnthropic()            # 异步
​

// TypeScript
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();                       // 从 process.env.ANTHROPIC_API_KEY 读
​

💡 同步 vs 异步:Python 提供 Anthropic(同步)与 AsyncAnthropic(异步)两套客户端,TypeScript 在 Node 环境下天然支持 await。高并发场景(如 Web 服务、扇出 fan-out)用异步客户端;脚本与简单工具用同步即可。第 3 章会讲各语言的细节差异。

四、能力之间的关系:从「问答」到「Agent」

这八块能力不是孤立的,它们组合起来才构成一个真正的 Agent 应用。以「做一个能查数据库并写报告的 Claude agent」为例,你会用到:

1. system prompt:定义角色「你是数据分析助手,先查数据再写报告」。
2. tools:定义 query_database、write_report 两个工具(第 2 章 01 节)。
3. streaming:让用户看到「正在查询…正在写报告…」的实时反馈(第 2 章 02 节)。
4. prompt caching:把那段长 system prompt + 工具定义缓存住,每轮省 90% 成本(第 2 章 03 节)。
5. token counting:发请求前预估成本,避免超预算(第 2 章 04 节)。
6. adaptive thinking:遇到复杂分析时让模型先想清楚再动手(模型参数)。

这正是 Claude Code、Cursor 这类产品背后的工程范式。第 4 章会专门讲 agent 设计原则,第 6 章讲多代理协作,第 5 章讲官方沉淀的工程技能(代码审查、数据可视化)。

问答          ──→  Agent          ──→  多代理系统
(system+messages) (system+tools+缓存)   (主代理+子代理)
  第1~2章           第2~4章              第6章
​

五、本书阅读路线

建立完全景地图后,后续章节的定位就清晰了:

• 第 2 章:逐个讲透八大能力中的核心六块(工具调用已有样章,接着是流式、缓存、计数、模型、错误)。
• 第 3 章:Python 与 TypeScript 两大主力 SDK 详解,其余六种语言合并对照。
• 第 4 章:Agent 设计原则(agent-design)与托管代理(managed-agents)。
• 第 5 章:官方工程技能——代码审查分级、数据可视化、技能生成器、文档与深度研究。
• 第 6 章:多代理架构(11 个子代理)与设计技能精选。
• 第 7 章:附录——各厂商系统提示词的安全哲学横向对比。

本节要点回顾

1. 最简四要素:model、max_tokens、messages(首条 user、user/assistant 交替)、可选 system——构成一次 messages.create() 调用。
2. API 无状态:每次请求都要发完整对话历史;返回是块列表(TextBlock/ThinkingBlock/ToolUseBlock),先判 .type 再取字段。
3. 八大能力地图:输入侧(system/tools/messages)、核心(模型/工具/思考)、优化(流式/缓存/计数)、批量托管(batches/files/managed-agents)。
4. 渲染顺序固定:tools → system → messages,顺序影响缓存,改动会失效其后所有缓存。
5. 八种语言形态:Python/TS 为主力全能力 SDK,Go/Java/PHP/Ruby/C# 各有覆盖,curl 是原始 HTTP;有 SDK 就别用原始 HTTP。
6. 能力组合才构成 Agent:system + tools + streaming + caching + counting 组合使用,是从「问答」升级到「Agent」的路径。

第 1 章到此结束,你已经理解了系统提示词的工程意义与 Claude API 的能力全景。从第 2 章开始,我们逐个讲透核心能力——下一节先进入流式响应(streaming),看 Claude 如何边生成边返回。