源码深度学习 · 零基础友好 · 60 天升级版

LangGraph 源码学习

60 天 · 每天 30 分钟 · 逐层读懂 LangChain 团队的"状态图编排引擎"——把 LLM 应用建模成图,用 Pregel 引擎驱动,支持持久执行、人在环、流式。本教程已升级为 60 天深度版:真源码走读 + 设计取舍 + 边界坑点,0 基础友好

00

开篇 · 这是个什么框架

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 全定制。

关于它和 LangChain 的关系:LangChain 是"用 LLM 搭应用的工具箱"(模型、工具、链);LangGraph 是"编排引擎"——它是 LangChain 生态里 Agent 的底层运行时。你可以用 LangGraph 的预制 create_react_agent 快速起步,也能降到裸 StateGraph 完全自定义控制流。核心包在 libs/langgraph/langgraph/,检查点在 libs/checkpoint*,预制件在 libs/prebuilt/
01

架构全景(动起来看)

下图那颗发光小球是"你的图从定义落到 Pregel 引擎执行"的过程。从上到下:用户 API → 编译 → 执行引擎 → 底层。

L4 · 用户 API  ·  graph/ + prebuilt/ + func/
StateGraph加节点/边
create_react_agent预制
@entrypoint/@task函数式
State + reducers共享状态
L2 · 编译与执行  ·  pregel/
compile()图→Pregel
PregelLoopBSP 超步
_algo准备任务
PregelRunner并行执行
L3 · 通道与持久化  ·  channels/ + checkpoint*
Channels节点间通信
Checkpoint状态快照
SaverMemory/Sqlite/PG
interrupt人在环
L1 · 底层
Streaming5 种流模式
Serde序列化
Store长期记忆
SDK/CLI平台

LangGraph 的心智模型是"节点 + 边 + 共享状态,Pregel 超步执行"——经典 ReAct Agent 就是一张小图:

agent 节点调 LLM
决定下一步
条件边要调工具吗? 是→ tools 节点 ↺ 回 agent 否→ END
为什么用"图"? Agent 的控制流本质是"根据状态决定下一步做什么"——图(节点+条件边)天然表达这种控制流,还支持循环(Agent 反复调工具)、分支、并行。相比"一个大 while 循环",图更清晰、可组合、可视化、可持久化。这和你学过的 eino Graph、AutoGPT Graph 一脉相承。
02

怎么用这份教程

⏱️

每天 30 分钟

一天一个独立页面,跟着"今日小结 + 10 分钟动手 + 明日预告"收尾。

👶

零基础友好

不假设你懂图/Pregel/状态机,术语首次出现都有大白话解释。

📍

真源码 + 行号

关键代码标 文件:行号,逐行走读,可在真源码里跳转对照。

🎨

设计取舍 + 边界

每天讲"为什么这么设计"和"坑在哪",不止是 API 说明。

一条主线:从"StateGraph 怎么定义节点/边/状态"→"状态与数据流(reducers/通道)"→"控制流(条件边/Command/Send)"→"Pregel 引擎怎么超步执行(深水区)"→"Channels 通道全家族"→"Checkpoint 怎么让它可持久/可记忆(深水区)"→"interrupt 人在环/时间旅行"→"函数式 API 与子图"→"预制 ReAct Agent 与流式"→"运行时、生产、收官"。
S1

阶段 1 · 入门与心智

D01-06 · 项目全景、跑通第一个图、StateGraph/节点/边/State 基础
01

项目全景:与 LangChain 的关系

解决什么问题、libs 分包(langgraph/checkpoint/prebuilt/cli/sdk);读 README、pyproject。

≈30 min · 已就绪 NEW开始学 →
02

装环境 + 跑通第一个图

最小 StateGraph 例子,从零到能 invoke 的第一张图。

≈30 min开始学 →
03

StateGraph 基础

graph/state.py 的 StateGraph 类、add_node/add_edge/compile 签名走读。

≈30 min开始学 →
04

节点与边

graph/_node.py(StateNode/PregelNode 关系)、边的存储结构。

≈30 min开始学 →
05

State 与 TypedDict

状态 schema、graph/state.py 里 schema 解析、_get_channels。

≈30 min开始学 →
06

第一个对话图 + 心智小结

把前面串成能跑的图,建立"节点+边+状态"的心智模型。

≈30 min开始学 →
S2

阶段 2 · 状态与数据流

D07-12 · reducers、add_messages、累加通道、多字段并行写、I/O schema、Pydantic State
07

reducers 入门

Annotated[x, reducer]、graph/state.py 如何读出并绑定 reducer。

≈30 min开始学 →
08

add_messages 深入

graph/message.py 的 add_messages(去重/更新/RemoveMessage)。

≈30 min开始学 →
09

BinaryOperatorAggregate

channels/binop.py(operator.add 累加)如何把 reducer 落到通道。

≈30 min开始学 →
10

多字段状态与并行写

多 reducer、并行节点同时写同一字段时怎么合并。

≈30 min开始学 →
11

输入/输出 schema

input_schema/output_schema、私有中间字段如何被过滤。

≈30 min开始学 →
12

Pydantic State

bench/pydantic_state.py、_internal/_pydantic.py 校验流程。

≈30 min开始学 →
S3

阶段 3 · 控制流

D13-18 · 条件边、Branch 路由、Command、Send 扇出、递归上限、START/END
13

普通边 vs 条件边

add_conditional_edges、graph/_branch.py 走读,根据状态选下一步。

≈30 min开始学 →
14

Branch 路由源码

_branch.py 的 Branch 类、路径解析与目标映射。

≈30 min开始学 →
15

Command 对象

types.py 的 Command(goto/update/graph)跨节点跳转与更新。

≈30 min开始学 →
16

Send 动态扇出

types.py Send、map-reduce(bench/fanout_to_subgraph.py)。

≈30 min开始学 →
17

循环与递归上限

recursion_limit、GraphRecursionError(errors.py)如何保护死循环。

≈30 min开始学 →
18

START/END 与入口

constants.py START/END、set_entry_point 的底层含义。

≈30 min开始学 →
S4

阶段 4 · Pregel 执行引擎 (核心深水区)

D19-26 · BSP 模型、super-step 主循环、任务准备、执行器、读写、I/O 映射、重试、调试画图
19

BSP / Pregel 模型

为什么是超步、pregel/__init__.py 的 Pregel 类总览。

≈30 min开始学 →
20

super-step 主循环

pregel/_loop.py(PregelLoop.tick / _first)逐段走读。

≈30 min开始学 →
21

任务准备 _algo.py

prepare_next_tasks / apply_writes:选谁跑、写入怎么落。

≈30 min开始学 →
22

执行器 _runner/_executor.py

PregelRunner、并行/顺序执行、异常聚合。

≈30 min开始学 →
23

PregelNode 读写

pregel/_read.py(PregelNode)、_write.py(ChannelWrite)。

≈30 min开始学 →
24

输入输出映射 _io.py

map_input / map_output:外部 dict 与内部通道怎么互转。

≈30 min开始学 →
25

重试与超时

pregel/_retry.py、_internal/_retry.py、RetryPolicy(types.py)。

≈30 min开始学 →
26

调试与画图

pregel/debug.py、_draw.py、stream mode=debug。

≈30 min开始学 →
S5

阶段 5 · Channels 通道

D27-32 · 通道抽象、LastValue、累加类、Topic、Ephemeral/Untracked、AnyValue/NamedBarrier
27

通道抽象 base.py

BaseChannel(update/get/checkpoint/from_checkpoint)四件套。

≈30 min开始学 →
28

LastValue

channels/last_value.py:最常见的覆盖写通道。

≈30 min开始学 →
29

累加类通道

binop.py 再深入 + delta.py,累加/增量语义。

≈30 min开始学 →
30

Topic

channels/topic.py:发布订阅 / 累积列表语义。

≈30 min开始学 →
31

EphemeralValue & Untracked

ephemeral_value.py、untracked_value.py:不持久化的通道。

≈30 min开始学 →
32

AnyValue & NamedBarrierValue

any_value.py、named_barrier_value.py:同步屏障语义。

≈30 min开始学 →
S6

阶段 6 · 持久化与记忆 (核心深水区)

D33-40 · Checkpoint 概念、保存点接口、Memory/Sqlite/Postgres、id 体系、serde、Store 长期记忆
33

Checkpoint 概念

为什么要存档、libs/checkpoint base(BaseCheckpointSaver、Checkpoint TypedDict)。

≈30 min开始学 →
34

保存点接口

get_tuple / put / list / put_writes 四个方法逐个走读。

≈30 min开始学 →
35

InMemorySaver

checkpoint 库 memory 实现,最简单的存档器。

≈30 min开始学 →
36

SqliteSaver

libs/checkpoint-sqlite 实现走读,落地到本地文件。

≈30 min开始学 →
37

PostgresSaver

libs/checkpoint-postgres(生产用)、migrations 建表。

≈30 min开始学 →
38

thread / checkpoint_ns / 超步

checkpoint 的 id 体系、pregel/_checkpoint.py。

≈30 min开始学 →
39

序列化 serde

_internal/_serde.py、checkpoint serde(JsonPlusSerializer)。

≈30 min开始学 →
40

Store 长期记忆

checkpoint 库 store(BaseStore,跨 thread、语义检索)。

≈30 min开始学 →
S7

阶段 7 · 中断与人在环

D41-46 · interrupt 原理、Command(resume=)、静态断点、时间旅行、durability、replay 幂等
41

interrupt() 原理

types.py interrupt、pregel 如何抛出/恢复执行。

≈30 min开始学 →
42

Command(resume=)

恢复执行、_scratchpad.py 如何暂存中断点。

≈30 min开始学 →
43

静态断点

interrupt_before / interrupt_after 的编译期设置与运行期效果。

≈30 min开始学 →
44

时间旅行

get_state_history / update_state(pregel),回到过去分叉重跑。

≈30 min开始学 →
45

durability 模式

"exit" / "async" / "sync",什么时候真正落盘。

≈30 min开始学 →
46

replay 与幂等

_internal/_replay.py,重复执行如何避免副作用。

≈30 min开始学 →
S8

阶段 8 · 函数式 API 与子图

D47-52 · @entrypoint/@task、func 与 pregel、子图基础/隔离、CachePolicy、节点级重试
47

@entrypoint / @task

func/__init__.py:用函数式写法替代显式建图。

≈30 min开始学 →
48

func 与 pregel 的关系

@task 如何在底层变成一个 Pregel 节点。

≈30 min开始学 →
49

子图基础

add_node(子图)、父子图状态如何共享。

≈30 min开始学 →
50

子图状态隔离与转换

不同 schema 的子图、stream subgraphs 逐层流式。

≈30 min开始学 →
51

缓存 CachePolicy

types.py CachePolicy、_internal/_cache.py:节点结果缓存。

≈30 min开始学 →
52

节点级重试与容错

RetryPolicy 组合、真实用法与失败降级。

≈30 min开始学 →
S9

阶段 9 · 预制件与流式

D53-58 · create_react_agent、ToolNode、tools_condition、流式 5 模式、流式底层
53

create_react_agent 总览

prebuilt/chat_agent_executor.py 结构,预制 ReAct Agent 全貌。

≈30 min开始学 →
54

create_react_agent 逐行①

模型节点、绑定工具,从图定义到编译的细节。

≈30 min开始学 →
55

ToolNode 源码

prebuilt/tool_node.py:并行工具调用、错误处理。

≈30 min开始学 →
56

tools_condition & 校验

tool_node 的 tools_condition、tool_validator.py。

≈30 min开始学 →
57

流式 5 模式

values/updates/messages/custom/debug(pregel stream + _messages.py)。

≈30 min开始学 →
58

流式底层

_messages.py、StreamProtocol,如何逐 token 推给前端。

≈30 min开始学 →
S10

阶段 10 · 运行时·生产·收官

D59-60 · 运行时与部署、六框架对比与学习/求职建议
59

运行时与部署

runtime.py(Runtime/context)、config.py、LangGraph Platform/CLI(libs/cli)、errors.py 总览。

≈30 min开始学 →
60

收官 · 知识地图串讲

全 60 天知识地图串讲 + 六框架对比 + 学习/求职建议。

≈30 min开始学 →

🚀 60 天深度版已就绪!10 个阶段、60 讲,真源码走读 + 设计取舍 + 边界坑点。建议按顺序学,准备好了就从 Day 01 · 项目全景 开始。