从 Claude Code 源码看 Agent 系统设计：主流框架都在解决的问题与各自的解法

与硝酸
49 阅读6分钟

从 Claude Code 源码看 Agent 系统设计：主流框架都在解决的问题与各自的解法

完整教程和所有代码实现：GitHub - agent-system-design-experience （24 章节，6 实战项目，欢迎 Star）

这篇文章讲什么

我花了很多时间分析 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无你需要自己实现
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],
    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 三层规则）
  1. 用 LangGraph 定义工作流 — 状态图是最灵活的编排范式
  2. 用 MCP 连接工具 — 正在成为跨框架标准
  3. 自研权限体系 — 借鉴 Claude Code，所有框架都缺这个
  4. 自研上下文管理 — 参考 Claude Code 的自动压缩和会话恢复

完整教程

本文是精华摘要。完整 24 章教程已在 GitHub 开源：

github.com/Yu-Xiao-She…

如果对你有帮助，给个 Star 就是对我最大的鼓励。

avatar
文章
阅读
粉丝