[AI/Agent/Runetime] LangGraph:图驱动的有状态智能体编排运行时
0 序
- LangGraph 作为 AI Agent Runetime 底座的热门开源框架之一,在持续学习、持续实践的同时,在此总结一二。
产品定位:LangGraph 是 LangChain Inc. 推出的低层级智能体编排框架与运行时,以有向图(StateGraph)为核心抽象,支持循环、分支、持久化检查点与人机协同,专为构建长运行、有状态、可审计的生产级 AI Agent 而设计。
1 概述
产品介绍
- LangGraph 是一个用于构建、管理和部署长运行、有状态智能体(long-running, stateful agents)的低层级编排框架与运行时,其专为构建有状态(Stateful)、长时运行的 AI 工作流而设计。与传统的线性 LLM 调用链不同,LangGraph 将工作流建模为有向图(Directed Graph):
- 节点(Node):执行具体操作的函数(如调用 LLM、执行工具、处理数据)
- 边(Edge):定义节点之间的流转路径,支持条件分支
- 状态(State):在整个工作流中共享并传递的数据
它由 LangChain Inc. 开发,于 2024 年 1 月首次发布,2025 年 10 月 22 日发布 1.0 稳定版,被官方称为"持久化智能体框架领域的首个稳定大版本"。

摘自: https://www.runoob.com/ai-agent/langgraph-quick-start.html
想象你正在指挥一场交响乐演出:传统的 LLM Chain 就像演奏一首从头到尾的曲子,只能顺序播放;而
LangGraph则像一位指挥家,可以根据现场观众的反应随时调整演奏顺序,让某个乐章重复,或者跳转到特定段落。它让AI工作流拥有了"指挥"的智慧——能够循环、分支、回溯,真正实现复杂的自主决策。
- 诞生背景与核心问题:
- LangChain(2022 年 10 月发布)最初以"链(Chain)"为核心抽象,适合线性 LLM 调用组合;
- 但随着
AI Agent场景复杂化,开发者需要循环(ReAct 推理循环)、条件分支、状态持久化、错误恢复、人工审批等能力,线性链无法满足;- LangGraph 应运而生,将 Agent 建模为有向图,把【控制流】从【隐式的应用代码】中抽离到可检查、可可视化的图结构中。
-
设计灵感:受 Google Pregel(BSP 超步计算模型)、Apache Beam(流处理)和 NetworkX(图 API 风格)启发。
-
URLs:
发展历程
| 时间 | 里程碑 |
|---|---|
| 2024 年 1 月 | LangGraph 首次发布,作为 LangChain 生态的图编排扩展 |
| 2024 年 6 月 | v0.1 稳定版发布,引入生产级特性(持久化、HITL) |
| 2024 年 8 月 | LangGraph Studio 上线,首个 Agent 可视化 IDE |
| 2025 年 7 月 | v0.5 发布,锁定 API 为 1.0 做准备,99% 用户可无缝升级 |
| 2025 年 9 月 | v1.0 Alpha 发布,无破坏性变更 |
| 2025 年 10 月 22 日 | v1.0 GA 正式发布,与 LangChain 1.0 同步;官方称"持久化 Agent 框架首个稳定版" |
| 2026 年至今 | 持续迭代至 v1.2.x,新增 DeltaChannel、命令式 API 等 |
主要功能
- StateGraph 图编排:以用户定义的 State Schema(TypedDict / Pydantic)为中心,节点(Node)为计算单元,边(Edge)定义控制流,支持固定边与条件边。
- 循环与分支:原生支持 ReAct 风格的推理循环、条件路由、扇出/扇入(fan-out/fan-in),突破 DAG 限制。
- 持久化与检查点(Checkpointing):每步执行后自动保存状态,支持故障恢复、暂停/恢复、时间旅行(time travel)回滚。
- 人机协同(Human-in-the-Loop, HITL):可在任意节点中断执行,供人类审批、修改状态后继续。
- 流式输出:支持节点级、Token 级、事件级多种流式模式。
- 子图(Subgraph):将一组节点封装为子图,作为主图的一个节点复用,支持模块化与多 Agent 协作。
- 全面记忆:短期工作记忆(对话上下文)+ 长期跨会话记忆(Store)。
- 确定性与 Agentic 步骤混合:在同一张图中混合手写确定性逻辑(规则、校验)与 LLM 驱动的灵活步骤。
- Pregel 超步执行模型:并行节点在同一超步执行,超步结束后统一应用状态更新,通过 Reducer 函数合并多写冲突。
核心优势 *
- 可控性/细粒度控制:不抽象 Prompt 或架构,开发者完全掌控每一步的执行逻辑,可将领域知识直接编码进图拓扑。
通过审核检查和人工参与审批来引导代理行动。
LangGraph 为长时间运行的工作流程保留上下文,使 AI Agent 保持正常运行。
- 生产级的持久化:Checkpoint 机制是一等公民,支持 Postgres / SQLite / Redis 等后端,天然适配长运行工作流。
- 确定性与灵活性平衡、可扩展性:
- 确定性与灵活性平衡: 同一图中可混合硬编码规则与 LLM 推理,关键路径可控可审计。
- 底层且可扩展: 使用完全描述性的底层原语构建自定义智能体,不受限制定制的僵化抽象的束缚。设计可扩展的多智能体系统,每个智能体都扮演着根据你的用例量身定制的特定角色。
- 生态完整:与 LangChain(模型/工具集成)、LangSmith(可观测性/评估/部署)、Deep Agents(高层 Harness)无缝组合。
- 多语言支持:Python(主力)+ JS/TS(langgraphjs)独立实现。
- 可靠性/企业验证:Klarna、Uber、J.P. Morgan、LinkedIn、Replit、Elastic 等公司生产环境使用。
- 一流的流式传输支持。通过逐令牌流式传输和中间步骤的流式传输,LangGraph 让用户实时清晰地了解代理的推理和行动过程。
主要短板
- 学习曲线陡峭:低层级 API 意味着需要理解 State、Reducer、Channel、Pregel 等概念,上手成本高于 CrewAI 等高层框架。
- 样板代码较多:简单 Agent 也需定义 State、节点、边、编译,快速原型效率不如
create_agent/create_deep_agent。 - 调试复杂度:图结构 + 循环 + 状态合并,出错时定位难度高于线性链(需配合 LangSmith)。
- 与 LangChain 生态强绑定:虽可独立使用,但文档和示例大量使用 LangChain 组件,脱离生态后集成成本上升。
局限性
- 不提供高层 Agent 模式:没有内置的 ReAct / Plan-and-Execute / Multi-Agent 开箱实现,需自行组装(或使用上层 LangChain / Deep Agents)。
- 不内置上下文管理:无自动摘要、上下文卸载、Prompt 缓存等策略(这些由 Deep Agents 提供)。
- 不内置工具/MCP 生态:工具定义和集成依赖 LangChain 或自定义。
- 单图并发模型有限:Pregel 超步模型适合协调式工作流,不适合大规模并行数据处理(那是 Apache Beam / Spark 的领域)。
为什么选择 LangGraph?传统 LLM Chain vs. LangGraph 的主要差异
| 特性 | 传统 LLM Chain | LangGraph |
|---|---|---|
| 工作流结构 | 线性,单向执行 | 图结构,支持循环 |
| 状态管理 | 需手动管理 | 内置状态持久化 |
| 条件路由 | 实现复杂 | 原生支持 |
| 人机协作 | 需要额外开发 | 内置支持 interrupt |
| 多 Agent 协调 | 实现困难 | 一流支持 |
| 调试工具 | 有限 | LangGraph Studio |
适用场景
- 复杂业务工作流:如租赁申请审批(抽取→评分→自动通过/拒绝/人工升级)、保险理赔、订单处理。
- 多步推理 Agent:需要循环调用工具、自我修正的研究 Agent、代码 Agent。
- 多 Agent 协作:通过子图实现专家 Agent 分工与协调。
- 需要人工审批的高风险流程:金融合规、医疗诊断辅助、内容审核。
- 长运行任务:跨小时/天的批处理、定时任务、事件驱动的 Ambient Agent。
- 可审计要求高的系统:每步状态可追溯、可回放、可回滚。
对话机器人:需要记忆多轮对话上下文
自主 Agent:能够规划、使用工具、迭代思考
多 Agent 系统:多个 AI 协同完成复杂任务
审批工作流:需要人工审核的自动化流程
研究助手:需要多步骤推理和信息检索
同类竞品
| 框架 | 核心定位 | 优势 | 劣势 |
|---|---|---|---|
| CrewAI | 角色驱动的多 Agent 协作 | 低代码、角色/任务抽象直观、原型快 | 复杂流程定制难、确定性控制弱 |
| AutoGen (Microsoft) | 对话驱动的多 Agent 协调 | 灵活的对话式交互、研究友好 | 生产级持久化/HITL 较弱 |
| LlamaIndex Workflows | 事件驱动的工作流 | RAG/数据连接生态强 | Agent 编排能力相对新 |
| OpenAI Swarm | 轻量多 Agent 实验框架 | 极简、上手快 | 非生产级、无持久化 |
| Prefect / Temporal | 通用工作流引擎 | 成熟的持久化/重试/调度 | 非 LLM 原生,Agent 模式需自建 |
发展趋势
- 社区活跃度:GitHub 约 34.5K Stars、7,039 Commits、298 Contributors、43K+ 依赖项目,PyPI 月下载量约 5700 万次,MIT 协议,Python 占 99.6%。
- 版本演进:1.0 后 API 稳定,迭代聚焦性能优化(DeltaChannel)、命令式 API 扩展、企业级部署。
- 生态分层:LangGraph 作为底层运行时,向上支撑 LangChain
create_agent和 Deep Agentscreate_deep_agent,形成"运行时→框架→Harness"三层栈。 - 总结:LangGraph 已成为生产级有状态 Agent 编排的事实标准底层,正从"框架"演进为整个 LangChain 智能体栈的运行时基石。
2 工作原理与架构
概念术语
| 术语 | 说明 |
|---|---|
| State(状态) | 工作流的共享数据容器,用 TypedDict 或 Pydantic Model 定义,在节点间传递 |
| Node(节点) | 计算单元,接收 State 返回 State 更新(部分字段),可以是 Python 函数、LLM 调用、工具执行 |
| Edge(边) | 节点间的控制流,分为固定边(Fixed Edge)和条件边(Conditional Edge,由函数决定下一跳) |
| START / END | 图的入口和出口特殊节点 |
| Reducer(归约函数) | 当多个并行节点同时更新同一 State 字段时,用于合并值的函数(如消息列表追加 add_messages) |
| Channel(通道) | State 字段的底层存储抽象,管理读写与 Reducer 逻辑 |
| PregelLoop | LangGraph 的运行时引擎,实现 Pregel BSP(Bulk Synchronous Parallel)超步计算模型 |
| Super-step(超步) | 一轮并行节点执行 + 状态合并的周期;并行节点同属一个超步,顺序节点分属不同超步 |
| Checkpoint(检查点) | 每个超步结束后持久化的完整状态快照,用于恢复、回滚、HITL |
| Subgraph(子图) | 封装为单个节点的完整图,支持模块化复用和嵌套 |
| Command(命令) | v1.0 引入的节点返回值类型,可同时更新状态并路由到指定节点 |
Graph(图)
- Graph 是整个工作流的蓝图,定义了 Agent 的完整逻辑结构。它由节点(Nodes)和边(Edges)组成:
StateGraph
|-- Nodes(节点)
| |-- node_a
| |-- node_b
| +-- node_c
+-- Edges(边)
|-- START -> node_a
|-- node_a -> node_b(条件边)
|-- node_a -> node_c(条件边)
+-- node_b -> END
State(状态)
- State 是贯穿整个图的共享数据结构。每个节点可以读取和更新 State,更新后的 State 会传递给下一个节点。
from typing import TypedDict, Annotated
from langgraph.graph import add_messages
class MyState(TypedDict): # 自定义的状态 Class
messages: Annotated[list, add_messages] # 消息列表(自动追加)
user_name: str # 用户名称
step_count: int # 步骤计数
重要:
Annotated[list, add_messages]表示该字段使用add_messages作为 reducer——新消息会【追加】到【列表】而不是【覆盖】。这是 LangGraph 状态管理的核心机制。
- State 数据流转示意

每个节点读取 State,执行操作,返回更新后的部分字段
Nodes(节点)
- 节点是普通的 Python 函数,接收当前 State,返回更新后的 State(部分字段)。
def my_node(state: MyState) -> dict:
# 读取状态
messages = state["messages"]
# 执行操作...
result = "处理结果"
# 返回更新的字段(不需要返回所有字段)
return {"messages": [{"role": "ai", "content": result}]}
Edges(边)
- 边定义节点之间的流转方式:
- 普通边:固定路径,node_a -> node_b
- 条件边:根据 State 动态路由,node_a -> node_b 或 node_c
- 起始边:
START-> 第一个节点- 结束边:某节点 ->
END
架构与运行原理
2.1 分层架构
- LangGraph 核心架构

2.2 Pregel 超步执行模型
LangGraph 的运行时核心是 PregelLoop,借鉴 Google Pregel 的 BSP 模型:
- 超步开始:运行时确定当前超步需要执行的所有节点(可并行)。
- 并行执行:同一超步内的节点并发执行,各自读取当前 State 并产生部分更新。
- 屏障同步:所有节点完成后进入屏障,不允许跨超步读写。
- 状态合并:通过 Reducer 函数将各节点的更新合并到 State。
- 检查点持久化:将合并后的完整状态写入 Checkpoint 后端。
- 路由计算:根据边和条件边函数确定下一个超步的节点集合。
- 重复:直到到达
END或被中断。
2.3 状态管理与 Reducer
State 是 LangGraph 的核心数据抽象。每个字段关联一个 Channel,Channel 定义了该字段的 Reducer 逻辑:
- 无 Reducer(默认覆盖):最后一个写入者获胜(last-write-wins)。
add_messages:消息列表追加(专为对话历史设计,支持更新/删除消息)。- 自定义 Reducer:如
operator.add(列表追加)、自定义合并函数。
当并行节点更新同一字段时,Reducer 保证合并结果的确定性。
2.4 检查点与持久化
每个超步结束后,PregelLoop 自动将完整状态(含消息历史、自定义字段、元数据)序列化为 Checkpoint:
- 故障恢复:进程崩溃后从最近 Checkpoint 恢复,无需重跑已完成步骤。
- 暂停/恢复:HITL 中断时保存 Checkpoint,人类审批后从该点继续。
- 时间旅行:可回退到历史任意 Checkpoint,修改状态后重新执行(fork 分支)。
- 后端可插拔:内置 SQLite(本地开发)、Postgres(生产)、Redis,支持自定义。
2.5 人机协同(HITL)
通过在节点中返回 interrupt() 或在图配置中指定 interrupt_before / interrupt_after,实现:
- Agent 执行到指定节点前/后自动暂停。
- 人类通过 API 读取当前 State,审批或修改。
- 人类提交决策后,Agent 从 Checkpoint 恢复执行。
3 使用指南
安装部署
Python(pip / uv)
pip install -U langgraph
# 或
uv add langgraph
# 生产级 Postgres 检查点
pip install langgraph-checkpoint-postgres
JS/TS
npm install @langchain/langgraph
案例示范
最小示例
from langgraph.graph import StateGraph, MessagesState, START, END
def mock_llm(state: MessagesState):
return {"messages": [{"role": "ai", "content": "hello world"}]}
graph = StateGraph(MessagesState)
graph.add_node(mock_llm)
graph.add_edge(START, "mock_llm")
graph.add_edge("mock_llm", END)
graph = graph.compile()
result = graph.invoke({"messages": [{"role": "user", "content": "hi!"}]})
带条件分支与循环的 ReAct Agent 骨架
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import ToolNode, tools_condition
def agent_node(state):
# 调用 LLM,可能返回 tool_call 或最终回答
return {"messages": [llm.invoke(state["messages"])]}
graph = StateGraph(MessagesState)
graph.add_node("agent", agent_node)
graph.add_node("tools", ToolNode(tools))
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", tools_condition) # 有 tool_call → tools,否则 → END
graph.add_edge("tools", "agent") # 工具结果返回 agent,形成循环
graph = graph.compile()
启用持久化与 HITL
from langgraph.checkpoint.postgres import PostgresSaver
checkpointer = PostgresSaver.from_conn_string("postgresql://...")
graph = graph.compile(checkpointer=checkpointer, interrupt_before=["tools"])
# 执行(带 thread_id 标识会话)
config = {"configurable": {"thread_id": "session-123"}}
graph.invoke(input, config)
# 人类审批后恢复
graph.invoke(None, config)
F 附录:LangChain / LangGraph / Deep Agents 三者关系
F.1 本质定位
LangChain 官方将三者定义为同一开源智能体栈的三个层级,而非竞争关系:
| 维度 | LangGraph | LangChain | Deep Agents |
|---|---|---|---|
| 官方定位 | Agent Runtime(运行时) | Agent Framework(框架) | Agent Harness(线束/套壳) |
| 核心抽象 | StateGraph(图) | create_agent(最小 Agent 循环) |
create_deep_agent(全功能 Agent) |
| 控制粒度 | 最细(每一步可控) | 中等(Middleware 钩子) | 最粗(开箱即用) |
| 抽象程度 | 最低(不抽象 Prompt/架构) | 中(极简、无主见) | 最高(有主见的最佳实践) |
| 确定性 vs 灵活性 | 最大确定性(图拓扑编码领域逻辑) | 平衡(核心循环非确定,Middleware 注入确定步骤) | 最大灵活性(长运行、子 Agent 扇出、自动上下文管理) |
| 学习曲线 | 高 | 低 | 中 |
| 依赖关系 | 可独立使用 | 构建于 LangGraph 运行时之上 | 构建于 LangChain create_agent 之上(间接使用 LangGraph) |
F.2 层级依赖关系
关键事实:
- Deep Agents 本质上 = LangChain 核心 Agent 循环 + 一堆 Middleware(文件系统中间件、上下文管理中间件等)。
- LangChain 的
create_agent在 1.0 之后底层编译为 LangGraph 图执行,因此自动获得持久化、HITL、流式等能力。 - 三者完全可组合:可以把
create_deep_agent作为子图嵌入更大的 LangGraph 工作流,也可以在 Deep Agents 中调用自定义 LangGraph 子图。
F.3 确定性—灵活性光谱
F.4 功能对比矩阵
| 功能 | LangGraph | LangChain (create_agent) |
Deep Agents |
|---|---|---|---|
| 图编排(节点/边/条件分支) | ✅ 原生 | ❌(编译为图但不暴露) | ❌ |
| 循环 / ReAct | ✅ 手动构建 | ✅ 内置 | ✅ 内置 |
| 持久化 / Checkpoint | ✅ 一等公民 | ✅(继承自 LangGraph) | ✅(继承自 LangGraph) |
| Human-in-the-Loop | ✅ 原生 | ✅(继承) | ✅(继承) |
| 流式输出 | ✅ 多模式 | ✅ | ✅ + 子 Agent 独立流 |
| 子图 / 多 Agent | ✅ 手动组装 | ❌ | ✅ 内置 Subagents |
| 模型/工具集成 | 需配合 LangChain | ✅ 700+ 集成 | ✅ 继承 + MCP 原生 |
| 虚拟文件系统 | ❌ | ❌ | ✅ 内置(可插拔后端) |
| Skills(按需加载领域知识) | ❌ | ❌ | ✅ 内置(Agent Skills 标准) |
| Memory(跨会话持久偏好) | ❌(需自建 Store) | ❌ | ✅ 内置(AGENTS.md) |
| 自动摘要 / 上下文卸载 | ❌ | ❌ | ✅ 内置 |
| Prompt 缓存 | ❌ | ❌ | ✅ 内置 |
| 任务规划(Task Planning) | ❌ | ❌ | ✅ 可选 |
| 代码执行 / Sandbox | ❌ | ❌ | ✅ 可选(Sandbox + JS Interpreter) |
| 文件权限控制 | ❌ | ❌ | ✅ 声明式权限规则 |
| Middleware 扩展 | ❌(用节点替代) | ✅ | ✅ |
F.5 适用场景选型
| 场景 | 推荐层级 | 理由 |
|---|---|---|
| 简单 RAG 问答、单轮工具调用 | LangChain create_agent |
不需要子 Agent/文件系统,核心循环足够 |
| 复杂业务审批流(抽取→评分→自动/人工分支) | LangGraph | 需要将业务规则编码进图拓扑,确定性优先 |
| 通用研究 Agent / 编码 Agent / GTM Agent | Deep Agents | 需要文件系统、子 Agent、记忆、长运行上下文管理 |
| 多 Agent 专家协作(自定义分工协议) | LangGraph | 需要完全控制 Agent 间的通信与协调逻辑 |
| 高合规要求(每步可审计、可回滚) | LangGraph | 检查点 + 图可视化 + 确定性步骤 |
| 快速原型 / MVP | Deep Agents | 开箱即用,一行 create_deep_agent 启动 |
| 超低延迟敏感应用 | LangChain 或 LangGraph | 可精细控制哪些工具/上下文到达模型,减少开销 |
| 已有 LangGraph 工作流,需增加一个智能子任务 | 混合:Deep Agents 作为子图嵌入 | 三者可组合,不必二选一 |
F.6 官方选型建议(Rule of Thumb)
从 Deep Agents 开始。它是功能最全的 Agent Harness,绝大多数场景都够用。当需要建模复杂工作流或完全控制每一步时,再下沉到 LangChain 和 LangGraph。
- 已在用 LangGraph 且价值在于图的形状和确定性步骤 → 继续用 LangGraph。
- LangGraph 流程高度 Agentic(几乎全是 LLM 驱动)→ 可考虑迁移到 Deep Agents 以获得内置上下文管理。
Z FAQ for LangGraph
Q: LangGraph 必须和 LangChain 一起使用吗?
不需要。 LangGraph 可以完全独立使用,节点可以是任意 Python 函数。但文档和示例大量使用 LangChain 的模型/工具抽象,脱离生态后需自行集成 LLM SDK。
Q: LangGraph 和 LangChain Expression Language (LCEL) 是什么关系?
LCEL 适合线性/分支的 DAG 管道(RAG 等)。
LangGraph 在此基础上增加了循环、持久化、HITL 等能力。
简单 DAG 用 LCEL 即可,需要循环和状态持久化时用 LangGraph。
Q: LangGraph 的 Checkpoint 会保存 LLM 的原始输出吗?
会。Checkpoint 保存完整 State,包括消息历史(含 LLM 输出和工具调用),可用于回放、调试和审计。
Q: 如何在 LangGraph 中实现并行执行?
在 Pregel 模型中,同一超步内的多个节点自动并行执行。
通过条件边扇出到多个节点,或使用 Send API 动态生成并行节点实例(如 Map-Reduce 模式)。
Q: LangGraph 支持分布式执行吗?*
LangGraph 本身的 PregelLoop 在单进程内运行。
生产部署通过 LangSmith Deployment 平台提供横向扩展,Checkpoint 后端(Postgres)支持多实例共享状态。
Q: Deep Agents 是 LangGraph 的替代品吗?
不是。
Deep Agents 构建在 LangGraph 之上,是更高层的封装。
它将 LangGraph 作为运行时,自己负责上下文管理、子 Agent、文件系统等高层能力。
Y 推荐文献
- LangGraph 官方文档 - LangChain
- Building LangGraph: Designing an Agent Runtime from First Principles - LangChain Blog
- Deep Agents vs LangChain vs LangGraph - LangChain Blog
- Agent Frameworks, Runtimes, and Harnesses - LangChain Blog
- LangChain and LangGraph Reach v1.0 - LangChain Blog
- Deep Agents 官方文档 - LangChain
- Graph-Based Agentic AI with LangGraph - arXiv
- LangGraph
X 参考文献
- LangGraph - GitHub
- LangGraph overview - LangChain Docs
- Deep Agents vs LangChain vs LangGraph - LangChain Blog
- Deep Agents overview - LangChain Docs
- Building LangGraph: Designing an Agent Runtime from first principles - LangChain Blog
- LangChain and LangGraph Agent Frameworks Reach v1.0 Milestones - LangChain Blog
- LangGraph Complete Guide - AI Wiki
- LangGraph vs CrewAI: Multi-Agent Orchestration Compared - Nexus
- LangChain vs LangGraph vs Deep Agents: Pick a Rung, Not a Framework - dreaming.press
- LangGraph Architecture Research - GitHub
浙公网安备 33010602011771号