从 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 的做法：预定义类型 + 自动选择

typescript 复制代码

// Claude Code 内部通过 subagent_type 区分 Agent 角色：
// - general-purpose：通用执行
// - explore：快速搜索和探索
// - plan：制定执行计划
// - verification：验证执行结果
//
// Coordinator 根据请求复杂度自动选择 Agent 类型
// 用户不需要手动指定用哪个 Agent

CrewAI 的做法：角色描述驱动

python 复制代码

from crewai import Agent
agent = Agent(
    role="高级代码审查员",      # 角色
    goal="审查代码质量和安全性",  # 目标
    backstory="你有10年经验...",  # 背景故事
    tools=[code_search, file_read]
)

LangGraph 的做法：状态图节点

python 复制代码

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

python 复制代码

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 最值得学习的设计之一。源码中的权限体系：

typescript 复制代码

// 每个工具执行前，经过三层规则检查：
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 的做法：按复杂度自动选策略

lua 复制代码

用户请求 → Coordinator 分析复杂度
  ├── 简单 → 单 Agent 直接执行
  ├── 中等 → 工具链顺序执行（glob → read → analyze → edit）
  └── 复杂 → 多 Agent 层级协作（explore → plan → execute）

源码中定义了 7 种任务类型，每种对应不同的执行器：

typescript 复制代码

type TaskType =
  | 'local_bash'          // Shell 命令
  | 'local_agent'         // 子 Agent
  | 'remote_agent'        // 远程 Agent
  | 'in_process_teammate' // 进程内协作
  | 'local_workflow'      // 工作流
  | 'monitor_mcp'         // MCP 监控
  | 'dream'               // 后台异步

LangGraph 的做法：开发者画状态图

python 复制代码

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 的做法：角色分工 + 流程编排

python 复制代码

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 转交

python 复制代码

triage = Agent(name="triage", handoffs=[billing, tech_support])
# triage 判断后，将对话转给专门 Agent

AutoGen：对话接力

python 复制代码

team = RoundRobinGroupChat(participants=[coder, reviewer])
# 像开会一样轮流发言

协作模式选择指南：

css 复制代码

你的场景是？
├── 父子任务分解 → Claude Code 的层级嵌套
├── 客服路由     → OpenAI SDK 的 Handoff
├── 多视角讨论   → AutoGen 的 GroupChat
└── 流水线生产   → CrewAI 的 Crew

问题五：状态怎么不丢？

Agent 执行到一半崩了怎么办？对话历史太长怎么办？

Claude Code 的做法：

每个任务有独立的 outputFile，结果实时写入磁盘
sessionRestore.ts 支持会话中断后恢复
自动压缩上下文窗口，避免 Token 溢出

LangGraph 的做法：

python 复制代码

# 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 系统的务实路径

与其纠结选哪个框架，不如：

markdown 复制代码

你的 Agent 系统 = LangGraph（编排）
                + MCP（工具协议）
                + 自研权限层（参考 Claude Code 三层规则）

用 LangGraph 定义工作流 --- 状态图是最灵活的编排范式
用 MCP 连接工具 --- 正在成为跨框架标准
自研权限体系 --- 借鉴 Claude Code，所有框架都缺这个
自研上下文管理 --- 参考 Claude Code 的自动压缩和会话恢复

完整教程

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

github.com/Yu-Xiao-She...

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