LangGraph 深度解读

“程序即有向图，状态在 Channel 中流淌”

一句话定位

LangGraph 把 Agent 的决策流程建模为有向图，用 Channel 传递状态、Pregel 引擎执行，是当前状态管理最严谨的 Agent 工作流引擎。

设计哲学上最精彩的地方

LangGraph 的核心洞察是：复杂 Agent 的行为不是一条直线，而是一张图。循环（反复修改方案直到达标）、分支（根据质量决定发布还是返工）、并行（多个子任务同时推进）——这些在链式模型里极难表达的逻辑，在图模型中是一等公民。

日常类比：地铁线路图。你从起点出发，遇到换乘站（条件边）按规则选方向，可以做环线（循环图），可以在某站等人（human-in-the-loop），还能在任意站存档（checkpoint）下次继续坐。LangGraph 就是 Agent 世界的地铁网络。

最精彩的设计是 Channel 系统。当多个并行节点同时往同一个 state key 写入结果时，LastValue Channel 只保留最后一个值（适合覆盖型状态如 current_answer），BinaryOperatorAggregate Channel 用 reducer 函数合并所有写入（适合累积型状态如 messages）。一个 Annotated 类型标注就决定了并发冲突的解决策略，这是极其优雅的设计。

Pregel 引擎：图计算的心脏

LangGraph 的执行引擎叫 Pregel，致敬 Google 的图计算框架。核心文件 pregel/__init__.py 长达 4380 行，是整个项目最复杂也最关键的部分。

Pregel 采用同步超步（superstep）模型：同一超步内的节点并行执行，超步之间严格有序。这保证了状态一致性——你永远不会读到一个”半更新”的状态。代价是不能跨超步流水线化，但对于 Agent 场景（每步都可能改变决策方向），这个代价完全值得。

Checkpoint 机制让图的执行可以中断后恢复、回滚到历史状态、甚至 fork 分支探索。保存的是完整 Channel 快照而非增量 diff，所以恢复是 O(1) 的。

GraphInterrupt：Human-in-the-Loop 的标杆实现

GraphInterrupt 不是简单的暂停——它把当前状态完整存入 Checkpoint，人类可以在任意时间后恢复，甚至可以修改 state 再恢复。这比传统的回调或 webhook 模式强大得多，因为人类不只是”批准/拒绝”，还可以”修改条件后继续”。

局限性：图也有边界

LangGraph 的学习曲线是六大框架中最陡的。Channel、Pregel、Checkpoint 三层抽象需要时间消化，对于”一个 Agent 调一个工具回答问题”这种简单场景，用 LangGraph 是过度工程化。

此外，LangGraph 和 LangChain 的绑定虽然理论上可解耦，但实际使用中很难完全脱离 LangChain 生态。~400 文件的核心虽然精简，Pregel 单文件 4380 行的复杂度却集中了大量维护风险。

本地代码结构

langgraph/
├── libs/
│   ├── langgraph/
│   │   ├── graph/          # StateGraph 定义、Node/Edge 抽象
│   │   ├── channels/       # LastValue/BinaryOperatorAggregate
│   │   ├── pregel/         # Pregel 执行引擎（4380 行核心）
│   │   ├── checkpoint/     # Checkpoint 持久化接口
│   │   └── constants.py    # 全局常量（START/END 节点等）
│   ├── checkpoint-sqlite/  # SQLite Checkpoint 后端
│   ├── checkpoint-postgres/ # PostgreSQL Checkpoint 后端
│   └── sdk/                # LangGraph Cloud SDK
└── docs/                   # 文档站源码

本地关键文件