Claude Code / Agent SDK / Anthropic API
三者深度解读

0. 前置：先搞清三者的关系

很多人一开始就被名字搞晕。其实它们是同一个模型（claude-opus-4-7 / sonnet-4-6 / haiku-4-5），只是到达模型的路径不一样：

路径 A：Anthropic API 直连
   你的代码 ─→ HTTP ─→ Anthropic API ─→ Claude（Opus/Sonnet/Haiku）
   特点：最底层、最自由、自己写工具循环、独立 API key 计费

路径 B：Claude Code CLI（交互式）
   人类 ─→ 终端 REPL ─→ Claude Code 进程 ─→ Anthropic API ─→ Claude
   特点：给人用的命令行 IDE，REPL 模式，跟 Max/Pro 订阅绑定

路径 C：Claude Agent SDK（程序化）
   你的代码 ─→ Python/TS SDK ─→ subprocess ─→ Claude Code（headless）
                                        ─→ Anthropic API ─→ Claude
   特点：本质是 Claude Code 的 Python/TS 包装，给程序调的

看清楚没？路径 C 其实是路径 B 套了一层壳。Agent SDK 内部就是 spawn 一个 claude --print --json-stream 子进程，通过 stdin/stdout 跟它对话。

1. 路径 A：Anthropic API 直连

装个 pip install anthropic，拿 API key，直接调 messages.create()。最原始最自由。

from anthropic import Anthropic
client = Anthropic(api_key="sk-...")

# 单次调用，自己处理 tool_use 循环
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"name": "search", "description": "...", "input_schema": {...}}],
    messages=[{"role": "user", "content": "查下天气"}],
)

# 如果模型返回 tool_use，你要自己执行工具，把结果回传
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.content[-1])
    response = client.messages.create(
        ...
        messages=[..., {"role": "user", "content": [{"type": "tool_result", ...}]}],
    )

能拿到啥独家能力

• 真 JSON mode：response_format={"type": "json_object"} 强制 100% 合法 JSON 输出
• 精细的 prompt caching：cache_control: {"type": "ephemeral"}，省 90% input token
• Extended Thinking 完全控制：thinking={"budget_tokens": 10000}
• Batch API：50% off，适合定时批量任务
• Temperature/top_p/seed：完全自由调
• Streaming SSE：第一个字 1.5s 内可出
• 新 API 特性第一天可用（Files/Citations/Memory tool 等）

代价

• Tool 循环要自己写 while 循环
• Subagent / Hook / MCP 都没有，要自己造
• 独立计费，不享受 Max 订阅额度
• 没有 .claude/ 文件系统配置（Skills/Slash commands 全没了）

2. 路径 B：Claude Code CLI（终端 REPL）

就是 claude 那个命令行工具，给人坐在终端前用的。打开 REPL 模式跟 Claude 对话，让它读文件改代码跑命令。

$ claude
> 帮我看看 src/auth.py 有什么 bug
[Claude 读文件、思考、给出修复建议、问你要不要应用]

它也有 --print headless 模式（吐一次结果就退出），但这本来不是给程序调的，是给 shell 脚本组合用的：

$ claude --print "git diff 干啥的，一句话总结"

核心定位

• 给人类开发者当 AI 编程伙伴
• 跟 ~/.claude/ 配置深度集成（Skills、Slash commands、Memory）
• 走 Pro/Max 订阅（OAuth 认证）或单独 API key
• 有完整的 tool 循环、subagent、hook 机制（这些后来都被 SDK 暴露给程序）

3. 路径 C：Claude Agent SDK（推荐）

2025 年 Anthropic 把 Claude Code 的能力包装成了 Python/TS 库，叫 Agent SDK。它本质上是「让程序用上 Claude Code 全套能力」。

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="帮我找 src/ 里所有 TODO 并整理",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
        model="claude-opus-4-7",
    ),
):
    print(message)
# Tool 循环 SDK 帮你跑完，你只需要消费结果

它在内部干了啥

  你的 Python 代码
      │
      │ query(prompt, options)
      ▼
  Agent SDK Python 包装
      │
      │ 把 ClaudeAgentOptions 翻译成 CLI flag
      │ subprocess.Popen(["claude", "--print", "--json-stream", ...])
      ▼
  Claude Code CLI 子进程（Node.js）
      │
      │ 内部跑 tool 循环 / hook / subagent 调度
      │ HTTPS to api.anthropic.com
      ▼
  Anthropic API
      │
      ▼
  Claude (Opus/Sonnet/Haiku)

独家能力（API 直连没有的）

• Tool 循环自动跑：你只发 prompt，它自己跑完 N 轮 tool_use，最后返回结果
• Subagent 框架：定义 AgentDefinition，主 agent 自动委派复杂任务
• Hook 机制：PreToolUse/PostToolUse 拦截、审计、修改工具调用
• MCP 集成：Model Context Protocol 服务原生支持（Playwright、自建 SDK Tools）
• Skills / Slash commands：.claude/ 文件系统配置自动加载
• Sessions resume：跨次对话保留 reasoning 上下文
• Permission mode：plan / acceptEdits / bypassPermissions 等
• 走 Max 订阅：用 Agent SDK credit（$100/$200 月）而非独立 API key

4. 三者对比一表

5. 怎么选？

决策树（一分钟搞定）

6. 计费坑（很多人在这翻车）

三个池子互相独立，不互通：

7. 一个实战案例：微信群机器人

我用 Agent SDK + Max 订阅 + Opus 4.7 给自己的微信群造了个机器人，48 小时迭代了 23 个 commit。下面是真实选型逻辑：

8. 常见误区

❌ "API 直连一定更快更便宜"

不一定。HTTP 启动是快，但要自己写 tool 循环 = 一次任务多次 round-trip。 SDK 一次 query() 内部跑完，对终端用户感受未必更慢。 Max 订阅 $200/月覆盖大量调用，API 按 token 算可能更贵。

❌ "Claude Code 是给人用的，不能给程序调"

claude --print 是为程序设计的。但你不需要自己 spawn 它 — Agent SDK 已经替你包装好了。 你"自己 spawn claude" = 重写 Agent SDK。

❌ "用 SDK 就拿不到最新模型"

SDK 支持所有 Anthropic 模型，包括最新的 Opus 4.7： ClaudeAgentOptions(model="claude-opus-4-7")

❌ "SDK 是 Anthropic 限制版，没 API 全"

SDK 在 tool 生态、subagent、hook、MCP 这些层面比 API 强很多。 API 强在 JSON mode、caching 控制、batch 这些底层旋钮。 不是"谁强"，是"侧重不同"。

9. 进阶资源

• Agent SDK 官方文档
• Claude 模型对比（Opus 4.7 / Sonnet 4.6 / Haiku 4.5）
• Python SDK GitHub
• 官方 Agent demo 集
• Max 订阅 vs API 计费说明