从 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 类型 // 用户不需要手动指定用哪个 AgentCrewAI 的做法角色描述驱动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 的做法类 Handofffrom agents import Agent triage Agent(nametriage, 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无你需要自己实现LangGraphinterrupt人工中断仅支持暂停无规则CrewAI无你需要自己实现OpenAI SDKGuardrails输入输出校验有但不是权限控制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], processProcess.hierarchical # 或 sequential )四种编排范式对比编排范式代表优势劣势适合场景自动路由Claude Code零配置智能选择不够灵活通用 Agent状态图LangGraph完全可控、可持久化学习成本高复杂工作流角色流水线CrewAI直观易懂灵活性差内容生产对话轮次AutoGen自然协作难以预测多视角讨论问题四多个 Agent 怎么协作Claude Code层级嵌套主 Agent 通过调用AgentTool启动子 Agent子 Agent 还可以再启动孙 Agent形成树状结构。源码中有两种执行后端PaneBackendExecutor每个 Agent 在独立终端面板运行InProcessBackend轻量级进程内运行OpenAI Agents SDKHandoff 转交triage Agent(nametriage, handoffs[billing, tech_support]) # triage 判断后将对话转给专门 AgentAutoGen对话接力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(checkpointerSqliteSaver(conn)) # 崩溃后可以从上次 checkpoint 恢复其他框架基本上没有原生的状态持久化。CrewAI 和 AutoGen 的 Agent 执行如果中断只能从头来。问题六工具协议怎么统一各家框架的工具定义不互通但MCPModel 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 的自动压缩和会话恢复