LangGraph:用有向图编排 Agent,40k stars 的工业级框架
LangGraph 在 GitHub 上已经 40k+ stars,是目前 Agent 编排领域被用得最多的框架之一。它的核心思路一句话讲完:把 Agent 的执行流建模成有向图。循环、分支、状态持久化、人机审批,全都在图结构上做。
下面我从问题、用法、架构、优缺点、自己跑一遍、谁该用六个角度讲清楚。
它解决什么问题
传统的链式调用(Chain)只能往前走:prompt → llm → parser → next。一旦碰到 Agent 需要的循环(比如 ReAct 反复调工具直到拿到答案)、分支(这一步走 tool,下一步直接答)、人机审批(先停下来让用户确认再继续),链式结构就卡住了。
LangChain 的 Runnable 序列其实也是这个毛病:它本质是同步的、有向的、一次性的。碰到需要回滚、暂停、跨会话记忆这些场景,Runnable 就捉急。
LangGraph 补的就是这个坑。它用 StateGraph 把执行流显式建模成有向图:
- 节点(Node) = 计算单元(一次 LLM 调用、一个 tool、一个函数)
- 边(Edge) = 转移条件(无条件边 / 条件边)
- 状态(State) = 全局数据结构,在节点间自动传递
图本身就是支持循环的,所以 ReAct 这类需要反复迭代的 Agent 用图表达天然就顺。
怎么用
三步起步:
- 定义 State(TypedDict 或 Pydantic model)
- 写节点函数(输入 state,输出 state 的更新)
- 用 StateGraph 拼图,加 checkpoint,编译
核心 API 就几个:add_node、add_edge、add_conditional_edges、compile。
下面是一个能直接跑的最小例子,3 步循环演示图 + 条件边的基本用法:
from typing import TypedDict, Literal
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver
class State(TypedDict):
messages: list[str]
step: int
def agent(state: State) -> State:
return {
"messages": state["messages"] + [f"step {state['step']} done"],
"step": state["step"] + 1,
}
def should_continue(state: State) -> Literal["agent", END]:
return END if state["step"] >= 3 else "agent"
graph = StateGraph(State)
graph.add_node("agent", agent)
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", should_continue)
app = graph.compile(checkpointer=MemorySaver())
result = app.invoke(
{"messages": [], "step": 0},
config={"configurable": {"thread_id": "1"}},
)
print(result)
# {'messages': ['step 0 done', 'step 1 done', 'step 2 done'], 'step': 3}
安装一行:
pip install langgraph
跑 invoke 拿最终结果,跑 stream 能看到每一步 superstep 的状态变化——调试 Agent 时这个特别有用。
它怎么工作(架构)
核心三件套:
- State:全局状态 schema,TypedDict 或 Pydantic,所有节点读写的共享数据结构
- Node:纯函数或 LangChain Runnable,签名为
(state) -> dict - Edge:普通边是固定转移,条件边(conditional_edges)根据 state 决定下一步去哪个节点
执行时,LangGraph 内部维护一个 Pregel 风格的 superstep 循环(致敬 Google 的 Pregel 图计算系统)。每一轮 superstep:
- 根据当前 state 和 edges 决定这一轮要激活哪些节点
- 一批可执行的节点并发跑(所以你写节点函数时要小心,不能假设全局顺序)
- 节点的输出通过 Channels 机制合并写回 State(处理并发写冲突)
- 进入下一个 superstep,直到没有节点被激活
Checkpoint 是 LangGraph 的杀手锏。每次 superstep 结束,框架把当前 state 序列化到 backend:
MemorySaver:内存,重启就没了,适合测试SqliteSaver:本地文件PostgresSaver:生产环境标配,支持 time-travel debug
有了 checkpoint,你传同一个 thread_id 再调一次 invoke,框架直接从断点续跑,不用从头来。Time-travel debug 就是从这个能力延伸出来的——你可以从任意历史 superstep 重放,看当时发生了什么。
Human-in-the-loop 本质更简单:在某个节点前插 interrupt,执行到那儿就停下来,把状态暴露出去等用户输入,用户回复后从断点继续。所以审批、确认、改写这些交互模式用 LangGraph 实现很直接。
它哪里好 / 哪里不好
好的地方:
- 图模型比 CrewAI 的"角色协作"抽象更底层,比 AutoGen 的群聊抽象更可控。图就是图,节点是什么、边怎么走,你说了算。
- Checkpoint 是真生产级,Postgres backend 的 time-travel debug 排查问题极方便。
- 跟 LangChain 生态兼容(Runnable、tools、messages schema 都通),但不强制绑定——你可以只装
langgraph不用 langchain。 - 文档质量在开源框架里算顶级,官方 cookbook 覆盖了常见模式。
不好的地方:
- 学习曲线比裸 LLM wrapper 或简单 Chain 陡。State schema 设计不好,分支条件乱加,最后会写出 spaghetti graph——一个节点连十几条边,自己都看不懂。
- 本地调试时
stream输出比较啰嗦,每个 superstep 都打印一遍 state,新手会被淹没。 - 新版本 API(v0.2 后)改动大,老教程里的
set_entry_point、add_edge参数顺序之类很多变了,照抄会报错。要看代码的话认准日期。 - 相比 CrewAI 的"开箱即用",LangGraph 更像给你一套图灵完备的图灵机——灵活,但你要自己设计 Agent 拓扑。
我试了下
pip install langgraph langgraph-checkpoint-sqlite 装好,跑官方 tutorial 的 ReAct agent 示例。构造 5 轮工具调用,本地内存(MemorySaver)跑完约 12 秒。
换 SqliteSaver 开 checkpoint 后,同一个 thread_id 第二次 invoke 直接从断点续跑,0.5 秒返回。这延迟差距在实际场景里很关键:长任务中途中断、网络抖动、重试,用户感知完全不同。
试了几个边界情况:
StateGraph.compile()阶段会做循环检测,理论上能挡住明显的无限循环(自环 + 无条件边)- 但实际兜底靠
max_steps配置——条件边逻辑写错的话,框架不会无限保护你 - 跟 CrewAI 0.80 跑同样的 ReAct 任务对比,启动开销 LangGraph 略高(约 200ms,Pregel 调度 + checkpoint 初始化的成本),但状态可见性和恢复能力强很多
社区里另一个常被拿来对比的是 AutoGen(微软出品,群聊式多 Agent)和 LlamaIndex Workflows(事件驱动)。前者抽象更"自然语言"(Agent 之间互发消息),后者更轻量。LangGraph 卡在中间:比它们都更结构化,也更"程序员友好"。
谁该用
适合的场景:
- 长任务执行(多轮工具调用、跨步骤推理)
- 需要人审批(金融、医疗、合规场景的 Agent 必须有 HITL)
- 需要跨会话记忆(chatbot、持续学习 agent)
- 需要可观测、可回放的生产 Agent(出问题时能查历史 checkpoint)
不适合的场景:
- 单轮问答:直接调 LLM 就完事了
- 一次性脚本:图的抽象是过度设计
- 对延迟极敏感(<100ms)的实时交互:图的调度开销吃不消
后者用裸 LLM 调用或 LangChain Runnable 就够了,没必要上图的抽象。LangGraph 不是替代 Chain,而是 Chain 解决不了问题时的下一步。
小结
LangGraph 的本质是给 Agent 提供了一个显式的、可持久化的、带中断能力的执行模型。它不是最易上手的,但如果你要做真正能上生产的 Agent——尤其是需要循环、审批、长记忆、重放这几样的——它基本上是现在最成熟的选择。
40k stars 不是白来的。GitHub 仓库地址:https://github.com/langchain-ai/langgraph,可以直接看 README 和 examples/ 目录起步。