第 6 章 · Agent SDK 与 Agent 框架

6.1 Claude Agent SDK：Anthropic 官方造的轮子

第 3 章我们手写了 50 行 agent loop。能跑，但要做生产级 agent，还得加：权限管理、子 agent、会话持久化、流式输出、错误重试、上下文压缩、hook 系统……自己造太累。

Anthropic 把 Claude Code 底层的 agent 能力打包成了 Claude Agent SDK，2025 年发布。它的定位：

"Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript."
—— Claude Agent SDK 文档

翻译：用 Python 或 TypeScript，调用 Claude Code 同款的 agent loop + 工具集 + 上下文管理。

包名

bash

# Python
pip install claude_agent_sdk

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

最小示例

python

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"],  # 内置工具
        ),
    ):
        print(message)

asyncio.run(main())

这就是一个能读文件、改代码、跑命令的 agent。没有 agent loop、没有 tool use 处理、没有错误重试——SDK 全包了。

内置工具集

Agent SDK 自带这些工具（和 Claude Code 一样）：

Read / Write / Edit - 文件读写
Bash - 执行 shell 命令
Glob / Grep - 文件搜索
WebSearch / WebFetch - 网页搜索和抓取
Monitor - 监控子进程
AskUserQuestion - 问用户

你可以直接用，不用自己写 schema。

核心抽象

抽象	作用
`query()`	主入口，启动 agent loop
`ClaudeAgentOptions`	配置：允许的工具、模型、权限模式、hooks
Hooks	钩子，在 agent 行为前后插入逻辑（如审查、修改）
Subagents	子 agent，独立 context 跑子任务
MCP	接入 MCP server，复用外部工具
Permissions	权限系统，控制工具能干什么
Sessions	会话持久化，跨调用保持状态

与 Client SDK 的区别

	Client SDK	Agent SDK
你写的	agent loop + tool use 处理	只写 prompt 和配置
控制权	完全在你	SDK 帮你管
灵活性	高	中（SDK 抽象固定）
上手难度	高	低
适合场景	完全自定义 agent	快速做 Claude Code 风格 agent

"With the Client SDK, you implement a tool loop. With the Agent SDK, Claude handles it." ——官方原话。

6.2 Claude Code 本身就是 agent 范本

Claude Code 是 Anthropic 出的 CLI 编程工具，本质上就是个 agent。它是 Agent SDK 的"参考实现"——SDK 里的工具、loop、上下文管理，全是从 Claude Code 提炼出来的。

Claude Code 的几个关键设计值得学：

Subagent（子 agent）：复杂任务拆给 subagent 跑，主 agent 只拿结论，避免 context 爆炸。内置 Explore（探索代码库）、Plan（做计划）、General-purpose（通用）三类。
Skill（技能）：把"怎么干某类事"打包成 skill，agent 自动调用。第 7 章详细讲。
Hook（钩子）：在 agent 行为前后插入逻辑，比如"每次写文件前先备份"。settings.json 里配置。
Permission（权限）：分级控制工具执行——读类放行、写类询问、删除类必须人工确认。

这套设计是 agent 工程化的范本。你做自己的 agent 时，遇到"怎么管复杂度"的问题，可以参考 Claude Code 的拆分方式。

6.3 主流 Agent 框架对比

除了 Claude Agent SDK，市面上还有一堆框架。按 star 排序（2026-07 实测）：

框架类

框架	Stars	定位	上手	适合场景
AutoGen	59k	多 agent 对话式编排	★★★	研究、群聊式推理
CrewAI	55k	角色扮演多 agent 协作	★★	业务流程自动化
LlamaIndex	51k	RAG 起家的文档 agent	★★★	文档问答、知识库
LangGraph	37k	图式状态机编排	★★★★	复杂多步工作流
OpenAI Agents SDK	28k	OpenAI 官方轻量框架	★★	GPT 模型、多 agent 路由
Mastra	26k	TypeScript agent 框架	★★★	全栈 TS 项目
Google ADK	21k	Google 官方工具包	★★★	Gemini 生态、A2A 协议
Pydantic AI	18k	类型安全 agent	★★	Python 后端、结构化输出
Claude Agent SDK	7.5k	Anthropic 官方	★★	Claude 深度集成

产品类（不是框架，可直接用）

产品	Stars	定位
AutoGPT	185k	最早出圈的自主 agent 平台
OpenHands	80k	开源版 Devin，端到端软件开发
Aider	47k	终端 pair programming
Continue	35k	IDE 编程 agent（VSCode/JetBrains）
SWE-agent	20k	Princeton issue 修复 agent

6.4 选型建议

不同场景不同选择：

学概念/做原型

看 agent 怎么演进 → AutoGPT
看多 agent 对话 → AutoGen
最快搭多角色流水线 → CrewAI

Python 后端业务

类型安全 + 结构化输出 → Pydantic AI
复杂状态机 + 人机协作 → LangGraph
RAG / 文档场景 → LlamaIndex

TypeScript 全栈

Mastra（Vercel 生态无缝）

绑定大厂模型

Claude → Claude Agent SDK
GPT → OpenAI Agents SDK
Gemini → Google ADK

日常编码提效（直接用产品，不用框架）

终端党 → Aider
IDE 党 → Continue

做软件工程 agent 产品

工程化最完整 → OpenHands
学术评测基准 → SWE-agent

本教程的主线：先用 Claude Agent SDK（第 3 章那种 50 行代码 → SDK 一行调用），再讲 LangGraph（理解状态机编排），最后看 OpenHands（生产级 agent 怎么设计）。

前人智慧 / Prior Art

本章讲了 Claude Agent SDK 和 9 大框架的对比。理解这些框架的设计选择，比记住它们的 API 更重要--每个框架都是对"AutoGPT 翻车"的不同回应。

Claude Agent SDK 的"参考实现"哲学

Claude Agent SDK 文档里有句关键话：

"The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code."

翻译：SDK 给你和 Claude Code 同款的工具、loop、context 管理。

这个"参考实现"哲学是 Claude Agent SDK 的核心定位：不是发明新抽象，是把 Claude Code 已经验证过的能力封装成 SDK。这和 LangChain 早期"造大量新抽象"的路线形成对比。

工程意义：用 Claude Agent SDK 做的 agent，行为可预测（因为 Claude Code 已经验证过）；用全新抽象的框架，行为要重新踩坑。

OpenAI Swarm 的"轻量原语"反思

OpenAI 在 Agents SDK 文档里有一段值得注意的反思：

"We learned from the Swarm experiment that lightweight primitives beat heavy abstractions."

翻译：从 Swarm 实验里学到，轻量原语胜过重抽象。

Swarm 是 OpenAI 2024 年发布的实验性框架，抽象很重（Handoff / Routine / Agent 三件套）。社区反馈"太重了"。2025 年的 Agents SDK 走相反路线：Agent / Tool / Handover 三个轻量原语，组合即可。

这条反思不只对 OpenAI 有效。LangChain 早期也是"重抽象"（Chain / Agent / Tool / Memory / VectorStore 一堆概念），后期 LangGraph 走"轻量原语"（State / Node / Edge）。整个行业在 2024-2025 都在往轻量化走。

Claude Code 的四件套设计

本章 6.2 节讲了 Claude Code 的 Subagent / Skill / Hook / Permission 四件套。这四件套不是任意组合，是对 Agent 工程四个核心问题的回应：

问题	四件套对应
复杂度怎么拆	Subagent（独立 context）
经验怎么复用	Skill（沉淀做事方法）
自定义怎么注入	Hook（行为前后插逻辑）
风险怎么控制	Permission（分级放行）

这套设计是 Agent 工程化的范本。做自己的 agent 时遇到"怎么管复杂度"，可以参考这个切分。

LangGraph 的状态机哲学

LangGraph 文档把 Agent 设计成显式状态机：

State 是 TypedDict
Node 是 state 转换函数
Edge 是状态转移规则
Checkpoint 是 state 序列化

这种"显式状态机"哲学和 Claude Agent SDK 的"封装 loop"哲学形成对比：

	Claude Agent SDK	LangGraph
抽象层次	高（封装 loop）	低（状态机原语）
控制权	SDK 管	你管
灵活性	中	高
上手难度	低	高
适合	快速做 Claude Code 风格 agent	完全自定义状态机

没有"更好"，只有"更合适"。需要快速做产品用 Claude Agent SDK；需要完全控制 agent 行为做研究用 LangGraph。

CrewAI 的"角色扮演"路线

CrewAI 走的是另一条路：让 agent 扮演角色。定义 Captain / Researcher / Writer 等角色，给每个角色 goal 和 backstory，框架自动编排。

这条路线上手最简单，但灵活性最差。CrewAI 的工程价值在"降低了多 agent 协作的上手门槛"--不用懂状态机，定义角色就能跑。

代价是：复杂场景下 CrewAI 的抽象会束缚手脚。需要细粒度控制时还得换 LangGraph。

AutoGen 的"群聊推理"创新

AutoGen（微软）的创新在"群聊式推理"--多个 agent 在一个群里互相发消息，类似群聊。

这种模式适合"多个角色辩论同一问题"的场景（如代码审查：developer / reviewer / tester 三人辩论）。但对"任务流水线"场景不合适--群聊没有明确顺序，任务推进效率低。

AutoGen 的工程贡献是证明了多 agent 不一定要流水线，可以是平等对话。这扩展了 multi-agent 设计的可能性。

Aider 的"终端 pair programming"哲学

Aider 不是框架，是产品。但它的设计哲学值得框架学习：

终端原生：不嵌入 IDE，不依赖 GUI
git 优先：每次改动自动 commit，可回退
CONVENTIONS.md：项目规则文件（早于 AGENTS.md 约定）
TODO.md：任务清单（spec-driven 的轻量版）

Aider 的贡献是证明了"终端 + git + 规则文件"就够做 Coding Agent。不需要复杂框架，不需要 IDE 集成，简单工具组合就能跑。这条路线后来被 Claude Code 继承。

选型背后的工程判断

本章 6.4 节的选型建议不是任意推荐，每个选择背后有工程判断：

学概念用 AutoGPT -- AutoGPT 是反面教材，看它怎么翻车
快速原型用 Claude Agent SDK -- 参考实现，行为可预测
Python 业务用 Pydantic AI / LangGraph -- 类型安全或状态机
TypeScript 用 Mastra -- TS 生态原生
绑大厂用各家 SDK -- 模型能力对齐

没有"最好"的框架，只有"最合适"的。选型本质是判断：你要的是快速、灵活、还是稳定。

Claude Agent SDK 把 agent loop + 工具 + 权限 + 子 agent 全打包，Python/TS 都能用。
Claude Code 是 agent 工程化的范本，Subagent/Skill/Hook/Permission 四件套值得学。
9 大框架各有定位，按场景选：业务用 Pydantic AI / LangGraph / CrewAI，绑大厂用各家 SDK。
产品类（AutoGPT/OpenHands/Aider）直接用，不用框架。

下一章讲 Skills——怎么把"怎么干某类事"打包成可复用的 agent 能力。

第 6 章 · Agent SDK 与 Agent 框架 ​

6.1 Claude Agent SDK：Anthropic 官方造的轮子 ​

包名 ​

最小示例 ​

内置工具集 ​

核心抽象 ​

与 Client SDK 的区别 ​

6.2 Claude Code 本身就是 agent 范本 ​

6.3 主流 Agent 框架对比 ​

框架类 ​

产品类（不是框架，可直接用） ​

6.4 选型建议 ​

前人智慧 / Prior Art ​

Claude Agent SDK 的"参考实现"哲学 ​

OpenAI Swarm 的"轻量原语"反思 ​

Claude Code 的四件套设计 ​

LangGraph 的状态机哲学 ​

CrewAI 的"角色扮演"路线 ​

AutoGen 的"群聊推理"创新 ​

Aider 的"终端 pair programming"哲学 ​

选型背后的工程判断 ​