从 Claude Code 源码看 Agent 系统设计：主流框架都在解决的问题与各自的解法
这篇文章讲什么
我花了很多时间分析 Claude Code 的源码。Claude Code 不是开源框架，但它的源码实现了一个完整的生产级 Agent 系统。对比 LangChain、AutoGen、CrewAI、LangGraph、OpenAI Agents SDK 之后，我发现无论你用哪个框架，有6 个架构问题你绕不开。
这篇文章逐个分析这 6 个问题，每家的解法和取舍。
不想看分析的，直接去仓库拿完整教程：
- 6 大部分 24 章节完整教程
- 每个核心模块的完整 TypeScript 代码
- Mermaid 架构图 / 序列图 / 状态图
- 4 个从零构建的实战项目
- LangChain / AutoGen / CrewAI / LangGraph / OpenAI SDK 全维度对比
问题一：Agent 怎么定义？
每个框架都需要回答"什么是 Agent"。答案决定了整个系统的天花板。
Claude Code 的做法：预定义类型 + 自动选择
// Claude Code 内部通过 subagent_type 区分 Agent 角色： // - general-purpose：通用执行 // - explore：快速搜索和探索 // - plan：制定执行计划 // - verification：验证执行结果 // // Coordinator 根据请求复杂度自动选择 Agent 类型 // 用户不需要手动指定用哪个 Agent
CrewAI 的做法：角色描述驱动
from crewai import Agent agent = Agent( role="高级代码审查员", # 角色 goal="审查代码质量和安全性", # 目标 backstory="你有10年经验...", # 背景故事 tools=[code_search, file_read] )
LangGraph 的做法：状态图节点
graph = StateGraph(AgentState) graph.add_node("think", think_node) # 一个节点就是一个"Agent" graph.add_node("act", act_node) graph.add_conditional_edges("think", should_continue)
OpenAI Agents SDK 的做法：类 + Handoff
from agents import Agent triage = Agent(name="triage", handoffs=[billing_agent, tech_agent]) # triage 判断不了的问题，通过 handoff 转交给专门 Agent
| 框架 | Agent 定义方式 | 灵活性 | 上手难度 |
|---|---|---|---|
| Claude Code | 预定义类型枚举 | 低（但够用） | 零（自动选择） |
| CrewAI | 角色描述 | 高 | 低 |
| LangGraph | 图节点函数 | 最高 | 高 |
| OpenAI SDK | 类实例化 | 中 | 低 |
| AutoGen 0.4 | 类实例化 | 中 | 中 |
我的观察：大多数场景下，你不需要无限灵活的 Agent 定义。Claude Code 的"预定义类型 + 自动路由"反而最高效。如果你在构建特定领域的 Agent，建议走这条路。
问题二：工具怎么安全地调用？
Agent 需要调用外部工具（执行命令、读写文件、网络请求）。核心矛盾是：工具越强大，风险越高。
Claude Code 的做法：三层权限规则
这是 Claude Code 最值得学习的设计之一。源码中的权限体系：
// 每个工具执行前，经过三层规则检查： type ToolPermissionContext = { mode: PermissionMode, // 'default' | 'auto' | 'bypass' alwaysAllowRules: RulesBySource, // 自动放行（如：只读文件） alwaysDenyRules: RulesBySource, // 自动拒绝（如：rm -rf /） alwaysAskRules: RulesBySource, // 弹窗确认（如：执行bash） }
用户可以配置规则，比如"允许读取 .ts 文件但每次编辑都要确认"。
其他框架呢？
| 框架 | 工具权限 | 现状 |
|---|---|---|
| Claude Code | 三层规则 + 文件弹窗 + 命令过滤 | 生产级 |
| LangChain | 无 | 你需要自己实现 |
| LangGraph | interrupt（人工中断） | 仅支持暂停，无规则 |
| CrewAI | 无 | 你需要自己实现 |
| OpenAI SDK | Guardrails（输入输出校验） | 有，但不是权限控制 |
| AutoGen | 无 | 你需要自己实现 |
这是目前 Agent 框架最大的短板。如果你做的是生产系统，必须自己实现权限层。建议参考 Claude Code 的三层规则：
alwaysAllow → 匹配规则的操作直接放行（低风险操作） alwaysAsk → 匹配规则的操作弹窗确认（中风险操作） alwaysDeny → 匹配规则的操作直接拒绝（高风险操作）
问题三：请求怎么变成一步步的操作？
用户一句"帮我重构这个模块"，Agent 需要分解成多个步骤执行。
Claude Code 的做法：按复杂度自动选策略
用户请求 → Coordinator 分析复杂度 ├── 简单 → 单 Agent 直接执行 ├── 中等 → 工具链顺序执行（glob → read → analyze → edit） └── 复杂 → 多 Agent 层级协作（explore → plan → execute）
源码中定义了 7 种任务类型，每种对应不同的执行器：
type TaskType = | 'local_bash' // Shell 命令 | 'local_agent' // 子 Agent | 'remote_agent' // 远程 Agent | 'in_process_teammate' // 进程内协作 | 'local_workflow' // 工作流 | 'monitor_mcp' // MCP 监控 | 'dream' // 后台异步
LangGraph 的做法：开发者画状态图
graph = StateGraph(State) graph.add_node("analyze", analyze) graph.add_node("search", search) graph.add_node("refactor", refactor) graph.add_node("verify", verify) graph.add_conditional_edges("analyze", route_by_complexity) graph.add_edge("search", "refactor") graph.add_edge("refactor", "verify")
CrewAI 的做法：角色分工 + 流程编排
crew = Crew( agents=[explorer, coder, reviewer], tasks=[explore_task, refactor_task, review_task], process=Process.hierarchical # 或 sequential )
四种编排范式对比：
| 编排范式 | 代表 | 优势 | 劣势 | 适合场景 |
|---|---|---|---|---|
| 自动路由 | Claude Code | 零配置，智能选择 | 不够灵活 | 通用 Agent |
| 状态图 | LangGraph | 完全可控、可持久化 | 学习成本高 | 复杂工作流 |
| 角色流水线 | CrewAI | 直观易懂 | 灵活性差 | 内容生产 |
| 对话轮次 | AutoGen | 自然协作 | 难以预测 | 多视角讨论 |
问题四：多个 Agent 怎么协作？
Claude Code：层级嵌套
主 Agent 通过调用AgentTool启动子 Agent，子 Agent 还可以再启动孙 Agent，形成树状结构。源码中有两种执行后端：
PaneBackendExecutor：每个 Agent 在独立终端面板运行InProcessBackend：轻量级进程内运行
OpenAI Agents SDK：Handoff 转交
triage = Agent(name="triage", handoffs=[billing, tech_support]) # triage 判断后，将对话转给专门 Agent
AutoGen：对话接力
team = RoundRobinGroupChat(participants=[coder, reviewer]) # 像开会一样轮流发言
协作模式选择指南：
你的场景是？ ├── 父子任务分解 → Claude Code 的层级嵌套 ├── 客服路由 → OpenAI SDK 的 Handoff ├── 多视角讨论 → AutoGen 的 GroupChat └── 流水线生产 → CrewAI 的 Crew
问题五：状态怎么不丢？
Agent 执行到一半崩了怎么办？对话历史太长怎么办？
Claude Code 的做法：
- 每个任务有独立的
outputFile，结果实时写入磁盘 sessionRestore.ts支持会话中断后恢复- 自动压缩上下文窗口，避免 Token 溢出
LangGraph 的做法：
# Checkpointer 持久化状态图执行进度 app = graph.compile(checkpointer=SqliteSaver(conn)) # 崩溃后可以从上次 checkpoint 恢复
其他框架基本上没有原生的状态持久化。CrewAI 和 AutoGen 的 Agent 执行如果中断，只能从头来。
问题六：工具协议怎么统一？
各家框架的工具定义不互通，但MCP（Model Context Protocol）正在改变这个局面。
MCP 是 Anthropic 推动的开放标准，定义了 Agent 和工具服务器之间的通信协议。Claude Code 原生支持，OpenAI Agents SDK 在 2025 年也加入了支持。
这意味着你可以：
- 用 MCP 协议写一次工具服务器
- 在 Claude Code、OpenAI SDK、任何支持 MCP 的框架中使用
- 运行时动态连接/断开工具服务器
如果你在选工具协议，MCP 是当前最值得投的方向。
我的建议：构建自己 Agent 系统的务实路径
与其纠结选哪个框架，不如：
你的 Agent 系统 = LangGraph（编排） + MCP（工具协议） + 自研权限层（参考 Claude Code 三层规则）
- 用LangGraph定义工作流 — 状态图是最灵活的编排范式
- 用MCP连接工具 — 正在成为跨框架标准
- 自研权限体系— 借鉴 Claude Code，所有框架都缺这个
- 自研上下文管理 — 参考 Claude Code 的自动压缩和会话恢复