框架

LangGraph:用有向图编排 Agent,40k stars 的工业级框架

把 Agent 当成图来跑:循环、分支、状态持久化、人机协同,一个框架搞定。LangGraph 已经成生产环境 Agent 编排的事实标准之一。

字号

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 用图表达天然就顺。

怎么用

三步起步:

  1. 定义 State(TypedDict 或 Pydantic model)
  2. 写节点函数(输入 state,输出 state 的更新)
  3. 用 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:

  1. 根据当前 state 和 edges 决定这一轮要激活哪些节点
  2. 一批可执行的节点并发跑(所以你写节点函数时要小心,不能假设全局顺序)
  3. 节点的输出通过 Channels 机制合并写回 State(处理并发写冲突)
  4. 进入下一个 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/ 目录起步。

来源: https://github.com/langchain-ai/langgraph