LangGraph 源码学习
60 天 · 每天 30 分钟 · 逐层读懂 LangChain 团队的"状态图编排引擎"——把 LLM 应用建模成图,用 Pregel 引擎驱动,支持持久执行、人在环、流式。本教程已升级为 60 天深度版:真源码走读 + 设计取舍 + 边界坑点,0 基础友好。
开篇 · 这是个什么框架
LangGraph 是 LangChain 团队推出的底层编排框架,用于构建有状态、多角色的 LLM 应用/智能体。核心思想:把智能体的工作流建模成一张"状态图"——节点是干活的函数、边是控制流、所有节点共享一份"状态(State)"。它由 Google 的 Pregel(图计算)模型驱动,天生支持持久执行、人在环、流式、记忆。
🚀 本教程已升级为 60 天深度版:相比旧的 20 天版,我们把内容拆成 10 个阶段,每天都做到真源码走读(带真实 file:line)+ 逐行大白话讲解 + 数据结构/控制流内联 SVG + "为什么这么设计"的取舍 + 边界坑点。从 StateGraph 到 Pregel 深水区、Channels、Checkpoint、interrupt、函数式 API、prebuilt,全部读到源码里去。0 基础也能跟。
🎯 一句话:在 LangGraph 里,一个智能体 = 一张状态图(StateGraph)。你定义若干节点(函数,读共享状态、返回状态更新)和边(谁连谁、条件路由),编译后由 Pregel 引擎一"超步(super-step)"一超步地执行——节点通过通道(channels)通信,状态每步可被检查点(checkpoint)保存,从而能崩溃恢复、时间旅行、中断续跑。
状态图 StateGraph
节点 + 边 + 共享状态(带 reducer 的 TypedDict)。
Pregel 引擎
BSP 超步模型:节点并行跑、写通道、触发下游。
Checkpoint 持久化
每步存快照 → 崩溃恢复、时间旅行、人在环、记忆。
预制 Agent
create_react_agent 开箱即用;也能降到裸 StateGraph 全定制。
create_react_agent 快速起步,也能降到裸 StateGraph 完全自定义控制流。核心包在 libs/langgraph/langgraph/,检查点在 libs/checkpoint*,预制件在 libs/prebuilt/。架构全景(动起来看)
下图那颗发光小球是"你的图从定义落到 Pregel 引擎执行"的过程。从上到下:用户 API → 编译 → 执行引擎 → 底层。
LangGraph 的心智模型是"节点 + 边 + 共享状态,Pregel 超步执行"——经典 ReAct Agent 就是一张小图:
决定下一步→ 条件边要调工具吗? 是→ tools 节点 ↺ 回 agent 否→ END
怎么用这份教程
每天 30 分钟
一天一个独立页面,跟着"今日小结 + 10 分钟动手 + 明日预告"收尾。
零基础友好
不假设你懂图/Pregel/状态机,术语首次出现都有大白话解释。
真源码 + 行号
关键代码标 文件:行号,逐行走读,可在真源码里跳转对照。
设计取舍 + 边界
每天讲"为什么这么设计"和"坑在哪",不止是 API 说明。
项目全景:与 LangChain 的关系
解决什么问题、libs 分包(langgraph/checkpoint/prebuilt/cli/sdk);读 README、pyproject。
装环境 + 跑通第一个图
最小 StateGraph 例子,从零到能 invoke 的第一张图。
StateGraph 基础
graph/state.py 的 StateGraph 类、add_node/add_edge/compile 签名走读。
节点与边
graph/_node.py(StateNode/PregelNode 关系)、边的存储结构。
State 与 TypedDict
状态 schema、graph/state.py 里 schema 解析、_get_channels。
第一个对话图 + 心智小结
把前面串成能跑的图,建立"节点+边+状态"的心智模型。
reducers 入门
Annotated[x, reducer]、graph/state.py 如何读出并绑定 reducer。
add_messages 深入
graph/message.py 的 add_messages(去重/更新/RemoveMessage)。
BinaryOperatorAggregate
channels/binop.py(operator.add 累加)如何把 reducer 落到通道。
多字段状态与并行写
多 reducer、并行节点同时写同一字段时怎么合并。
输入/输出 schema
input_schema/output_schema、私有中间字段如何被过滤。
Pydantic State
bench/pydantic_state.py、_internal/_pydantic.py 校验流程。
普通边 vs 条件边
add_conditional_edges、graph/_branch.py 走读,根据状态选下一步。
Branch 路由源码
_branch.py 的 Branch 类、路径解析与目标映射。
Command 对象
types.py 的 Command(goto/update/graph)跨节点跳转与更新。
Send 动态扇出
types.py Send、map-reduce(bench/fanout_to_subgraph.py)。
循环与递归上限
recursion_limit、GraphRecursionError(errors.py)如何保护死循环。
START/END 与入口
constants.py START/END、set_entry_point 的底层含义。
BSP / Pregel 模型
为什么是超步、pregel/__init__.py 的 Pregel 类总览。
super-step 主循环
pregel/_loop.py(PregelLoop.tick / _first)逐段走读。
任务准备 _algo.py
prepare_next_tasks / apply_writes:选谁跑、写入怎么落。
执行器 _runner/_executor.py
PregelRunner、并行/顺序执行、异常聚合。
PregelNode 读写
pregel/_read.py(PregelNode)、_write.py(ChannelWrite)。
输入输出映射 _io.py
map_input / map_output:外部 dict 与内部通道怎么互转。
重试与超时
pregel/_retry.py、_internal/_retry.py、RetryPolicy(types.py)。
调试与画图
pregel/debug.py、_draw.py、stream mode=debug。
通道抽象 base.py
BaseChannel(update/get/checkpoint/from_checkpoint)四件套。
LastValue
channels/last_value.py:最常见的覆盖写通道。
累加类通道
binop.py 再深入 + delta.py,累加/增量语义。
Topic
channels/topic.py:发布订阅 / 累积列表语义。
EphemeralValue & Untracked
ephemeral_value.py、untracked_value.py:不持久化的通道。
AnyValue & NamedBarrierValue
any_value.py、named_barrier_value.py:同步屏障语义。
Checkpoint 概念
为什么要存档、libs/checkpoint base(BaseCheckpointSaver、Checkpoint TypedDict)。
保存点接口
get_tuple / put / list / put_writes 四个方法逐个走读。
InMemorySaver
checkpoint 库 memory 实现,最简单的存档器。
SqliteSaver
libs/checkpoint-sqlite 实现走读,落地到本地文件。
PostgresSaver
libs/checkpoint-postgres(生产用)、migrations 建表。
thread / checkpoint_ns / 超步
checkpoint 的 id 体系、pregel/_checkpoint.py。
序列化 serde
_internal/_serde.py、checkpoint serde(JsonPlusSerializer)。
Store 长期记忆
checkpoint 库 store(BaseStore,跨 thread、语义检索)。
interrupt() 原理
types.py interrupt、pregel 如何抛出/恢复执行。
Command(resume=)
恢复执行、_scratchpad.py 如何暂存中断点。
静态断点
interrupt_before / interrupt_after 的编译期设置与运行期效果。
时间旅行
get_state_history / update_state(pregel),回到过去分叉重跑。
durability 模式
"exit" / "async" / "sync",什么时候真正落盘。
replay 与幂等
_internal/_replay.py,重复执行如何避免副作用。
@entrypoint / @task
func/__init__.py:用函数式写法替代显式建图。
func 与 pregel 的关系
@task 如何在底层变成一个 Pregel 节点。
子图基础
add_node(子图)、父子图状态如何共享。
子图状态隔离与转换
不同 schema 的子图、stream subgraphs 逐层流式。
缓存 CachePolicy
types.py CachePolicy、_internal/_cache.py:节点结果缓存。
节点级重试与容错
RetryPolicy 组合、真实用法与失败降级。
create_react_agent 总览
prebuilt/chat_agent_executor.py 结构,预制 ReAct Agent 全貌。
create_react_agent 逐行①
模型节点、绑定工具,从图定义到编译的细节。
ToolNode 源码
prebuilt/tool_node.py:并行工具调用、错误处理。
tools_condition & 校验
tool_node 的 tools_condition、tool_validator.py。
流式 5 模式
values/updates/messages/custom/debug(pregel stream + _messages.py)。
流式底层
_messages.py、StreamProtocol,如何逐 token 推给前端。
运行时与部署
runtime.py(Runtime/context)、config.py、LangGraph Platform/CLI(libs/cli)、errors.py 总览。
收官 · 知识地图串讲
全 60 天知识地图串讲 + 六框架对比 + 学习/求职建议。
🚀 60 天深度版已就绪!10 个阶段、60 讲,真源码走读 + 设计取舍 + 边界坑点。建议按顺序学,准备好了就从 Day 01 · 项目全景 开始。