第 5 章　主流 AI Agent 架构模式

本章目标：横向对比 12 个主流的 AI Agent 框架/产品（Claude Code、Claude Agent SDK、OpenAI Agents、Codex、Gemini CLI、Cursor、Cline、Aider、OpenHands、LangGraph、AutoGen、CrewAI），从十个架构维度系统比较，理解它们的设计取舍，为后续深入 Claude Code 架构提供坐标系。

5.1 为什么要横向对比

理解一个架构的最好方式，不是孤立地看它，而是把它放进坐标系里，看它和”邻居”的异同。孤立地看 Claude Code，你会觉得它”就该这么设计”；横向对比之后，你才会发现：每一个设计决策，都是在多个备选方案之间的权衡。

本章比较 12 个主流框架，它们大致分成三类：

Coding Agent 产品（面向最终用户的完整产品）：Claude Code、Codex、Gemini CLI、Cursor、Cline、Aider、OpenHands。
Agent 框架/SDK（面向开发者的构建工具）：Claude Agent SDK、OpenAI Agents SDK、LangGraph、AutoGen、CrewAI。

这个分类本身就是一个重要观察：“产品”和”框架”的区别。产品有完整的 Harness（终端 UI、权限、会话管理），框架则更聚焦于”帮你搭 Agent Loop”。理解这个区别，是理解 Claude Code 独特价值的关键。

为什么要做这个对比？因为设计取舍只有在对比中才能看清。比如，”要不要用显式图（LangGraph）还是隐式循环（Claude Code）？”这个问题，只有把两者放在一起，才能看清各自的适用场景和代价。孤立地看任何一方，都会得出片面的结论。

5.2 十个架构维度

在对比之前，先明确我们比较的十个维度，每个维度都对应 Harness 的一个核心职责：

Agent Loop：循环怎么实现？是显式 while 循环，还是图（Graph）驱动？
Tool System：工具怎么定义、注册、执行？
Context：上下文怎么管理？有没有压缩机制？
Memory：跨会话记忆怎么做？
Permission：有没有权限控制？人机协作怎么做？
Subagent：支不支持子智能体/多智能体？
MCP：是否支持 Model Context Protocol？
Persistence：会话/状态怎么持久化？
Sandbox：有没有沙箱隔离？
Human-in-loop：人怎么介入？

这十个维度不是随便选的——它们就是第 4 章 Harness 九大职责的展开。通过这十个维度对比，我们能看清每个框架”把重心放在了 Harness 的哪些部分”。

5.3 逐个框架剖析

5.3.1 Claude Code

定位：Anthropic 官方的终端 Coding Agent，是本书的核心研究对象。

架构特点：

Agent Loop：显式的 while (true) 循环（src/query.ts 的 queryLoop），配合完整的状态机（transitions.ts 定义 Terminal/Continue 状态）。
Tool System：40+ 内置工具（Read/Write/Edit/Glob/Grep/Bash/Task/Todo 等），统一的 Tool 接口，支持串行/并发执行。
Context：业界最完善的上下文管理——多种压缩策略（autoCompact/microCompact/sessionMemoryCompact 等，另有 reactiveCompact/snipCompact/contextCollapse 在本版本源码树中仅有调用点、待验证），外加空间预算与收益递减检测。
Permission：细粒度的权限系统，支持 Allow/Deny/Ask 三种策略，规则可持久化。
Subagent：通过 Task 工具委派子智能体，支持并行。
MCP：完整的 MCP 客户端实现。
Persistence：完整的 Session 持久化，支持 resume/fork。
Sandbox：支持工作区隔离、Worktree 隔离。
Human-in-loop：权限审批、Plan Mode、中断恢复。

关键洞察：Claude Code 是”Harness 完整性”的标杆——它几乎覆盖了 Harness 的所有维度，且每个维度都做到了相当高的成熟度。这正是本书把它作为”逆向工程教材”的原因。

5.3.2 Claude Agent SDK

定位：Anthropic 官方的 Agent 开发 SDK，面向开发者。

架构特点：Claude Agent SDK 可以被理解为”把 Claude Code 的 Harness 能力抽出来，做成可编程的 SDK”。它提供了 Agent Loop、工具、子智能体、MCP 等能力，但不包含 Claude Code 的终端 UI 和完整的 CLI 产品形态。

与 Claude Code 的关系：Claude Code 本身可以看作”构建在 Agent SDK 之上的产品”。这个分层很有启示——Harness 的核心能力（SDK）与产品形态（CLI）是可以分离的。这个分离是”Model-Harness Separation”（第 54 章）的又一个体现：Harness 的能力是通用的，产品形态是多样的。

5.3.3 OpenAI Agents SDK

定位：OpenAI 官方的 Agent 开发框架（前身是 Swarm）。

架构特点：

Agent Loop：基于 Python 的 Runner + run() 循环，支持 handoff（交接）模式。
Tool System：Python 函数直接作为工具，通过函数签名和 docstring 自动生成 Schema。
Subagent：通过 handoff 实现多 Agent 协作，也支持 Agent-as-tool。
MCP：后期版本加入了对 MCP 的支持。
Guardrail：提供输入/输出护栏。

关键洞察：OpenAI Agents SDK 强调”简洁”和”Python 原生”——用函数装饰器定义工具，用 handoff 表达多 Agent 协作。它的设计哲学是”让 Agent 开发像写普通 Python 一样简单”。

5.3.4 Codex（OpenAI）

定位：OpenAI 的 Coding Agent（CLI + IDE 集成）。

架构特点：Codex 与 Claude Code 定位高度相似——终端 Coding Agent。它同样有文件工具、Shell 执行、自我修正循环。Codex 的一个特色是强调沙箱化执行——它默认在隔离环境中执行代码，降低安全风险。

关键洞察：Codex 和 Claude Code 的竞争，本质上是”两家头部实验室对 Coding Agent Harness 的理解之争”。对比两者的差异（如沙箱默认策略、上下文策略），能看清 Harness 设计上的关键分歧点。

5.3.5 Gemini CLI

定位：Google 的终端 Coding Agent。

架构特点：Gemini CLI 同样是终端 Coding Agent，提供了文件操作、命令执行、自我修正等能力。它的特色是与 Google 生态（如 Gemini 模型家族、Google 搜索）的深度集成。

5.3.6 Cursor

定位：AI 优先的 IDE（不是 CLI）。

架构特点：Cursor 是”IDE 形态的 Coding Agent”。它与 Claude Code 的最大区别在于交互界面——Cursor 把 Agent 能力嵌入到完整的 IDE 中（编辑器、文件树、调试器），而 Claude Code 是纯终端。

关键洞察：Cursor 和 Claude Code 代表了 Coding Agent 的两种形态之争：IDE 派 vs CLI 派。IDE 派强调可视化、沉浸式；CLI 派强调轻量、可脚本化、可组合。两者没有绝对优劣，取决于用户的工作习惯。

5.3.7 Cline

定位：开源的 VS Code 插件型 Coding Agent。

架构特点：Cline 是开源的，代码完全可见，因此常被用作学习 Coding Agent 实现的教材。它支持多种模型，提供完整的”计划-执行-验证”循环，且强调人工审批（每步操作都可在 IDE 中确认）。

关键洞察：Cline 的价值在于透明性和可学习性——它是”能完整读懂源码的 Coding Agent”之一，对想理解 Coding Agent 内部机制的开发者极其友好。

5.3.8 Aider

定位：开源的终端 Coding Agent，主打”AI 结对编程”。

架构特点：Aider 是极简主义的代表——它只有一个核心循环：把用户的请求和代码 diff 交给模型，模型返回编辑，应用到代码，然后 git commit。Aider 特别强调 “map-reduce”的仓库理解：先把整个仓库压缩成一张”仓库地图”（repository map），再让模型基于地图做编辑。

关键洞察：Aider 的”repository map”思想非常深刻——它证明了 Coding Agent 不需要把整个仓库塞进上下文，只需要给模型一个”结构化的仓库概览”。这个思想对后面的”代码理解”（第 46 章）有重要影响。

5.3.9 OpenHands（原 OpenDevin）

定位：开源的自主软件工程 Agent 平台。

架构特点：OpenHands 是一个更”学术化”的 Coding Agent 平台，它把 Agent 抽象成一个事件驱动的架构——Agent 与工具之间通过事件流（Event Stream）通信，所有事件都可持久化、可回放。OpenHands 还内置了沙箱（Docker），支持在隔离环境中执行。

关键洞察：OpenHands 的”事件溯源（Event Sourcing）”架构很有价值——它让 Agent 的整个执行过程变成一条可回放、可审计的事件流，这是可观测性的极致形态。

5.3.10 LangGraph

定位：LangChain 团队推出的”用图（Graph）表达 Agent 工作流”的框架。

架构特点：LangGraph 的核心理念是用状态机（图）显式地定义 Agent 的控制流。它把 Agent 的每一步建模为”节点”（Node），节点之间的转移建模为”边”（Edge），支持循环、条件分支、并行。

关键洞察：LangGraph 代表了与 Claude Code 截然不同的设计哲学——“显式图” vs “隐式循环”。LangGraph 让你把控制流画出来（显式、可预测、可测试）；Claude Code 让模型在 while 循环里自由决策（隐式、灵活、难预测）。两者各有适用场景：前者适合”流程明确的任务”，后者适合”需要临场发挥的任务”。这与第 1 章”Agent vs Workflow”的讨论一脉相承。

5.3.11 AutoGen（微软）

定位：微软的多智能体对话框架。

架构特点：AutoGen 的核心是**”多 Agent 对话”**——把多个 Agent 放在一个对话里，让它们互相协作。它强调”可对话的智能体”（Conversable Agent），Agent 之间通过消息传递协作。

关键洞察：AutoGen 的价值在于”多智能体协作”的抽象。但它也暴露了多智能体的一个通病：多 Agent 对话的成本和不可控性——多个模型互相”聊天”，token 消耗巨大，且容易跑偏。

5.3.12 CrewAI

定位：面向”角色扮演多智能体”的框架。

架构特点：CrewAI 强调”角色（Role）+ 目标（Goal）+ 任务（Task）+ 团队（Crew）”的抽象。它把多个 Agent 组织成一个”团队”，每个 Agent 有明确的角色分工，像一个小型”公司”一样协作。

关键洞察：CrewAI 的”角色扮演”抽象对业务用户友好，但它更适合”演示性”的多智能体场景，在”真实软件工程任务”上的鲁棒性存疑。

5.4 综合对比表

框架	类型	Agent Loop	上下文管理	权限/人机协作	子智能体	MCP	沙箱	核心特色
Claude Code	产品	while + 状态机	★★★★★（6种压缩）	★★★★★	强（Task）	强	有	Harness 完整性标杆
Claude Agent SDK	SDK	while	★★★★	★★★	强	强	可选	产品与 SDK 分离
OpenAI Agents	SDK	Runner 循环	★★	★★★（Guardrail）	handoff	支持	可选	Python 原生简洁
Codex	产品	while	★★★	★★★	支持	支持	强（默认沙箱）	沙箱优先
Gemini CLI	产品	while	★★★	★★★	支持	支持	有	Google 生态集成
Cursor	IDE	while	★★★	★★★	支持	支持	有	IDE 形态
Cline	插件	while	★★★	★★★★（逐步审批）	支持	支持	有	开源可学习
Aider	CLI	map-reduce	★★（仓库地图）	★	无	无	无	极简 + 仓库地图
OpenHands	平台	事件驱动	★★★	★★★	支持	支持	强（Docker）	事件溯源
LangGraph	框架	显式图	★★	★★	支持	支持	可选	显式控制流
AutoGen	框架	对话	★	★	强（对话）	支持	可选	多 Agent 对话
CrewAI	框架	角色协作	★	★	强（团队）	支持	可选	角色扮演

5.5 从对比中提炼的架构规律

横向对比之后，可以提炼出几条重要的架构规律：

5.5.1 “隐式循环”与”显式图”是两条主线

Claude Code、OpenAI Agents、Aider 走的是**”隐式循环”路线——让模型在 while 循环里自由决策。LangGraph 走的是“显式图”**路线——把控制流画成图。

两者的本质区别是**”谁决定流程”：模型决定（隐式）还是开发者决定（显式）。生产实践中，成熟的团队往往混合使用**：确定性流程用图/Workflow，不确定的探索用 Agent 循环。

这个规律对应第 1 章的”Agent vs Workflow”：Agent 适合”未知的探索”，Workflow 适合”已知的重复”。LangGraph 的图本质上是”Workflow 的强化版”，Claude Code 的循环本质上是”Agent 的纯粹版”。聪明的架构师会在两者之间做选择或组合。

5.5.2 上下文管理是 Coding Agent 的分水岭

在 Coding Agent 这一类别里，上下文管理的成熟度，几乎直接决定了产品的上限。Claude Code 之所以强，很大程度是因为它的上下文管理（压缩、预算、优先级）做到了极致。而 Aider 用”仓库地图”另辟蹊径，用”概览”替代”全量塞入”。这两种策略——”压缩”和”索引”——是 Coding Agent 上下文管理的两大流派。

这个规律揭示了一个反直觉的事实：在 Coding Agent 的竞争中，决定胜负的往往不是”模型多强”，而是”上下文管得多好”。因为大家用的模型（Claude、GPT、Gemini）能力差距有限，但上下文管理的差距可以是数量级的。

5.5.3 安全与权限是”产品”和”玩具”的分界

框架（LangGraph、AutoGen、CrewAI）普遍在权限和安全上投入不足——它们默认”开发者自己负责安全”。而产品（Claude Code、Codex、Cursor）都把权限和沙箱作为核心能力。这是因为产品要面向真实用户操作真实文件系统，安全是生死线；框架只是给开发者搭积木，安全责任在开发者。

这个规律印证了第 4 章的判断：安全是 Harness 从”玩具”走向”生产”的生死线。框架可以”甩锅”给开发者，产品必须”自己扛”。

5.5.4 MCP 正在成为”工具生态”的通用标准

几乎所有主流框架都在拥抱 MCP（Model Context Protocol）。MCP 的意义在于：它把”工具”从一个框架私有的概念，变成了一个跨框架通用的标准。这意味着工具生态可以跨框架复用——为 Claude Code 写的 MCP Server，也能被 Cline、Cursor 使用。这是 Agent 工具生态走向成熟的重要标志。

5.6 如何选择：一个务实的决策框架

对比完之后，一个自然的问题是”我该用哪个？”。给出一个务实的决策框架：

如果你要”用”一个 Coding Agent（而非”搭”一个）：选产品（Claude Code / Codex / Cursor）。它们开箱即用，Harness 完整。
如果你要”学” Coding Agent 的实现：读 Cline（开源、透明）、读 Claude Code 泄露源码（本书）、或读 Aider（极简、清晰）。
如果你要”搭”一个 Agent 应用：选 SDK（Claude Agent SDK / OpenAI Agents SDK），它们抽象层次合适，不会让你从零造轮子。
如果你要”精确控制流程”：选 LangGraph（显式图），把控制流画出来。
如果你要”演示多智能体协作”：AutoGen / CrewAI（角色扮演），但注意它们在真实工程任务上的鲁棒性。

这个决策框架的核心是：先明确你是”用”还是”搭”，再明确你的任务是”确定”还是”不确定”。这两个问题答清楚，选择自然就清晰了。

本章小结

本章横向对比了 12 个主流 Agent 框架/产品，核心收获：

产品 vs 框架：产品（Claude Code、Cursor）有完整 Harness，框架（LangGraph、AutoGen）聚焦 Agent Loop 搭建。
两大设计路线：隐式循环（while + 模型自由决策）vs 显式图（LangGraph 的状态机）。
Claude Code 的独特定位：Harness 完整性标杆，几乎在所有维度都做到了高成熟度。
四大规律：上下文管理是 Coding Agent 的分水岭、安全权限是产品与玩具的分界、MCP 是工具生态的统一标准、隐式循环与显式图是两条主线。
决策框架：先明确”用还是搭”，再明确”确定还是不确定”。

有了这个坐标系，我们接下来进入 Part II 的核心章节——Context Engineering、Tool System、Permission等核心，逐一深入 Harness 最重要的三个子系统。