AI应用开发之LangGraph解析

LangGraph 源码分析（langgraph-main）

本文档基于 langgraph-main 仓库的静态阅读整理，采用「先目录结构、再各文件功能、最后类/函数说明」的三段式组织，不展示具体代码实现。

定位：LangGraph 是一个低层编排框架（low-level orchestration framework） ，用于构建有状态、长运行（stateful, long-running）的 AI agent。其执行模型受 Google Pregel 与 Apache Beam 启发（消息传递 + 超步（super-step）并行），公共接口（图、节点、边）借鉴 NetworkX 风格。

下载链接：https://github.com/langchain-ai/langgraph

章节一：项目用途说明
- [1.1 这个项目的用途是什么](#1.1 这个项目的用途是什么)
- [1.2 核心功能用途](#1.2 核心功能用途)
- [1.3 与 LangChain 的关系](#1.3 与 LangChain 的关系)
- [1.4 包分层](#1.4 包分层)
章节二：如何使用
- [2.1 前置条件](#2.1 前置条件)
- [2.2 安装步骤](#2.2 安装步骤)
- [2.3 使用方式](#2.3 使用方式)
- [2.4 关键配置项说明](#2.4 关键配置项说明)
- [2.5 常见问题](#2.5 常见问题)
章节三：仓库总览
- [3.1 核心特性（来自 README）](#3.1 核心特性（来自 README）)
- [3.2 顶层目录结构](#3.2 顶层目录结构)
- [3.3 包依赖分层（来自 AGENTS.md）](#3.3 包依赖分层（来自 AGENTS.md）)
- [3.4 examples 目录（学习入口）](#3.4 examples 目录（学习入口）)
[章节四：libs/langgraph ------ 核心框架包](#章节四：libs/langgraph —— 核心框架包)
- [4.1 目录结构](#4.1 目录结构)
- [4.2 graph/ ------ 图构建层](#4.2 graph/ —— 图构建层)
- [4.3 pregel/ ------ Pregel 执行引擎（核心）](#4.3 pregel/ —— Pregel 执行引擎（核心）)
- [4.4 channels/ ------ 状态通道](#4.4 channels/ —— 状态通道)
- [4.5 managed/ ------ 托管状态值](#4.5 managed/ —— 托管状态值)
- [4.6 func/ ------ 函数式 API](#4.6 func/ —— 函数式 API)
- [4.7 types.py ------ 公共类型](#4.7 types.py —— 公共类型)
- [4.8 根级文件](#4.8 根级文件)
- [4.9 _internal/ ------ 内部基础设施](#4.9 _internal/ —— 内部基础设施)
[章节五：libs/checkpoint ------ 检查点与记忆抽象](#章节五：libs/checkpoint —— 检查点与记忆抽象)
- [5.1 目录结构](#5.1 目录结构)
- [5.2 base/ ------ 检查点核心](#5.2 base/ —— 检查点核心)
- [5.3 serde/ ------ 序列化](#5.3 serde/ —— 序列化)
- [5.4 cache/ ------ 检查点缓存](#5.4 cache/ —— 检查点缓存)
- [5.5 store/ ------ 长期记忆（跨线程）](#5.5 store/ —— 长期记忆（跨线程）)
- [5.6 其他](#5.6 其他)
[章节六：libs/checkpoint-postgres / checkpoint-sqlite ------ 持久化实现](#章节六：libs/checkpoint-postgres / checkpoint-sqlite —— 持久化实现)
- [6.1 checkpoint-postgres（包 langgraph-checkpoint-postgres）](#6.1 checkpoint-postgres（包 langgraph-checkpoint-postgres）)
- [6.2 checkpoint-sqlite（包 langgraph-checkpoint-sqlite）](#6.2 checkpoint-sqlite（包 langgraph-checkpoint-sqlite）)
[章节七：libs/checkpoint-conformance ------ 一致性测试套件](#章节七：libs/checkpoint-conformance —— 一致性测试套件)
[章节八：libs/cli ------ 命令行工具（langgraph CLI）](#章节八：libs/cli —— 命令行工具（langgraph CLI）)
- [8.1 目录结构](#8.1 目录结构)
- [8.2 子命令与文件说明](#8.2 子命令与文件说明)
[章节九：libs/prebuilt ------ 开箱即用组件](#章节九：libs/prebuilt —— 开箱即用组件)
- [9.1 目录结构](#9.1 目录结构)
- [9.2 类/函数说明](#9.2 类/函数说明)
[章节十：libs/sdk-py ------ Python 客户端](#章节十：libs/sdk-py —— Python 客户端)
- [10.1 目录结构](#10.1 目录结构)
- [10.2 类/函数说明](#10.2 类/函数说明)
章节十一：libs/sdk-js
章节十二：学习路线与关键文件索引
- [12.1 建议阅读顺序](#12.1 建议阅读顺序)
- [12.2 高频关键文件速查](#12.2 高频关键文件速查)
- [12.3 与 LangChain 的关系](#12.3 与 LangChain 的关系)

章节一：项目用途说明

1.1 这个项目的用途是什么

LangGraph 是一个有状态 AI Agent 编排框架，用于构建长运行、可恢复、支持人机协同的智能体系统。它解决的核心问题是：

状态持久化：Agent 执行到一半崩溃后，能从最近检查点恢复，不必从头重跑
长时间运行：支持跨小时甚至跨天的 Agent 任务（如深度研究、多步决策）
人机协同（HITL）：在关键节点暂停，等待人工审批/编辑后继续
动态图结构 ：运行时根据状态动态决定下一步走哪个节点（Send 动态分支）

典型用途：

深度研究 Agent：多轮搜索、阅读、综合，最终生成带引用的报告
编码 Agent：多文件修改、运行测试、根据结果迭代
工作流编排：多步骤业务流程（审批 → 执行 → 验证）
多 Agent 协作：Supervisor 分发任务给多个 Worker，汇总结果
RAG 系统：检索 → 判断相关性 → 生成 → 验证循环

1.2 核心功能用途

功能	说明
状态图（StateGraph）	定义节点（计算单元）+ 边（数据流），编译为可执行图
检查点（Checkpoint）	每步执行自动持久化状态，支持崩溃恢复、时间旅行（回放历史）
人机协同（HITL）	`interrupt()` 原语在节点中暂停，人工批准/编辑后 `resume` 继续
动态分支（Send）	运行时向指定节点发送一次性输入，实现动态扇出（如并行处理多个子任务）
流式输出	多种 stream mode（values/updates/messages/debug），实时推送执行进度
长期记忆（Store）	跨线程持久化键值记忆，支持向量检索、TTL 过期
子图（SubGraph）	将子图作为节点嵌入主图，实现模块化复用
检查点后端	内存（InMemorySaver）、SQLite、Postgres 三种持久化实现
重试策略	节点级 `retry_policy`，自动重试失败步骤
函数式 API	`@task` + `@entrypoint` 轻量写法，适合简单场景

1.3 与 LangChain 的关系

LangChain 提供组件（模型、工具、消息、检索器等），LangGraph 提供编排（有状态图执行、检查点、HITL、记忆）。两者配合使用：用 LangChain 的 init_chat_model 创建模型，用 LangGraph 的 StateGraph 组装工作流。

1.4 包分层

包	职责
`langgraph-checkpoint`	检查点抽象 + 序列化 + Store 抽象（最底层）
`langgraph-checkpoint-sqlite/postgres`	生产级检查点持久化实现
`langgraph`（核心）	StateGraph 构建 + Pregel 执行引擎 + 流式 + HITL
`langgraph-prebuilt`	开箱即用组件（`create_react_agent`、`ToolNode`）
`langgraph-sdk`	Python 客户端（调用远程 LangGraph 服务）
`langgraph-cli`	命令行工具（`langgraph dev` / `up` / `deploy`）

章节二：如何使用

2.1 前置条件

依赖	说明
Python 3.10 及以上	项目运行环境
`langgraph` 包	`pip install langgraph`（自动安装 checkpoint 依赖）
LLM 提供商 API Key	按需配置（OpenAI / Anthropic 等）
可选：`langgraph-checkpoint-sqlite`	`pip install langgraph-checkpoint-sqlite`，本地持久化检查点
可选：`langgraph-checkpoint-postgres`	`pip install langgraph-checkpoint-postgres`，生产级持久化
可选：`langgraph-cli`	`pip install langgraph-cli`，部署工具

2.2 安装步骤

安装核心包 ：pip install langgraph
（可选）安装持久化后端 ：pip install langgraph-checkpoint-sqlite 或 langgraph-checkpoint-postgres
（可选）安装 CLI ：pip install langgraph-cli
配置 LLM API Key：设置环境变量

2.3 使用方式

方式一：本地 Python 脚本（最简单）

从 langgraph.graph 导入 StateGraph
定义状态 schema（TypedDict 或 Pydantic）
创建 StateGraph，添加节点（add_node）和边（add_edge / add_conditional_edges）
编译：graph = builder.compile(checkpointer=InMemorySaver())
执行：graph.invoke({"messages": [...]}, config={"configurable": {"thread_id": "..."}})

方式二：使用预构建 ReAct Agent（推荐）

从 langgraph.prebuilt 导入 create_react_agent
传入 LangChain 模型和工具列表
一行代码得到完整 ReAct Agent，支持工具调用循环

方式三：LangGraph 平台部署（生产）

将 Agent 图导出为 langgraph.json 配置
运行 langgraph dev（开发模式）或 langgraph up（生产模式）
通过 langgraph-sdk 客户端调用远程 Agent
支持多租户、定时任务（Cron）、流式响应

方式四：时间旅行与调试

获取检查点历史：graph.get_state_history(config)
从历史检查点回放：graph.invoke(None, config={"configurable": {"checkpoint_id": "..."}})
在 LangSmith 中可视化执行轨迹

2.4 关键配置项说明

配置项	说明
`checkpointer`	检查点器（`InMemorySaver` / `SqliteSaver` / `PostgresSaver`），实现可恢复会话
`store`	长期记忆（`InMemoryStore` / `SqliteStore`），跨线程持久化
`thread_id`	会话线程标识，不同 thread 独立状态
`recursion_limit`	最大执行步数（默认 25），防止无限循环
`stream_mode`	流式输出模式：`values`（全状态）/ `updates`（增量）/ `messages`（LLM 消息）/ `debug`（内部任务）
`retry_policy`	节点级重试策略（次数、延迟、退避）
`interrupt_before/after`	在指定节点前后暂停，等待人工输入
`Send`	动态向指定节点发送输入（运行时扇出）

2.5 常见问题

问题	解决方法
Agent 无限循环	设置 `recursion_limit`，或在路由函数中增加终止条件
检查点空间占用大	使用 `PostgresSaver` 的 `prune` 策略清理旧线程；或 `SqliteSaver` 自动管理
流式输出格式复杂	使用 `stream_mode="messages"` 直接获取 LLM 消息流
远程调用超时	配置 `langgraph-sdk` 的超时参数；或改用本地 `invoke`
子图状态不传递	子图需要显式声明输入/输出 schema，与主图对齐

章节三：仓库总览

3.1 核心特性（来自 README）

特性	说明
Durable execution（持久化执行）	每个图的执行都可被检查点（checkpoint）持久化，进程崩溃后可以从最近检查点恢复，支持长时间运行的 agent
Human-in-the-loop（人工介入）	通过 `interrupt` / 中断机制在节点执行中途暂停图，等待人工审批/编辑后 resume
Comprehensive memory（全面记忆）	短期记忆：线程内检查点状态；长期记忆：`Store` 跨线程持久化（含向量检索、TTL）
LangSmith 调试	与 LangSmith 集成做 trace 观测、调试与评估

生态配套：Deep Agents （构建在 LangGraph 之上的高层 agent 包）、LangChain （组件生态）、LangSmith （观测/调试/部署平台）、LangSmith Deployment（托管部署）。

3.2 顶层目录结构

复制代码

langgraph-main/
├── .github/                     # CI workflows、ISSUE_TEMPLATE、脚本、THREAT_MODEL.md（威胁模型文档）
├── docs/                        # llms.txt（LLM 友好索引）、redirects.json、generate_redirects.py
├── examples/                    # 大量 Jupyter notebook 示例
├── libs/                        # 所有 Python/JS 包源码（monorepo）
│   ├── checkpoint/              # langgraph-checkpoint：检查点抽象 + 序列化 + 缓存 + Store 抽象
│   ├── checkpoint-conformance/  # 检查点实现的一致性测试套件
│   ├── checkpoint-postgres/     # Postgres 检查点/Store/缓存实现
│   ├── checkpoint-sqlite/      # SQLite 检查点/Store/缓存实现
│   ├── cli/                     # langgraph CLI（langgraph dev / up / build / deploy ...）
│   ├── langgraph/               # 核心框架包
│   ├── prebuilt/                # langgraph-prebuilt：开箱即用的 React agent 等
│   ├── sdk-py/                  # langgraph-sdk：Python 客户端（调用远程/本地 LangGraph server）
│   └── sdk-js/                  # 仅 README（JS SDK 独立仓库发布）
├── AGENTS.md                    # monorepo 组织与开发规范（包依赖图、make 命令）
├── Makefile                     # 顶层构建/测试入口
└── README.md                    # 项目介绍

3.3 包依赖分层（来自 AGENTS.md）

复制代码

checkpoint
   ├── checkpoint-postgres
   ├── checkpoint-sqlite
   ├── prebuilt
   └── langgraph            （核心，依赖 checkpoint）
sdk-py ──► langgraph + cli
sdk-js   （独立）

开发约定：每个库独立放在 libs/<name> 下；提交 PR 前执行 make format、make lint、make test（可 TEST=path/to/test.py make test 指定单个测试文件）；docstring 中禁用 Sphinx 双反引号。

3.4 examples 目录（学习入口）

examples/ 下为 notebook 示例，覆盖：react-agent-from-scratch（从零手搓 ReAct agent）、subgraph（子图）、tool-calling（工具调用）、multi_agent（多 agent 协作）、rag（检索增强）、reflexion（反思模式）、rewoo 等，是理解 API 的直观材料。

章节四：libs/langgraph ------ 核心框架包

包根 libs/langgraph/langgraph/ 是一个 namespace 包 （没有根级 __init__.py），直接由根级模块 + 子包构成。

4.1 目录结构

复制代码

libs/langgraph/langgraph/
├── callbacks.py     # 图执行回调与事件
├── config.py        # 运行上下文访问器
├── constants.py     # START / END 等常量
├── errors.py        # 图运行时异常体系
├── runtime.py       # 运行时上下文对象
├── types.py         # 公共类型：interrupt / Send / Command / Checkpointer 等
├── typing.py        # 内部类型工具
├── version.py       # 版本号
├── warnings.py      # 警告辅助
├── graph/           # StateGraph 构建器
├── pregel/          # Pregel 执行引擎（核心）
├── channels/        # 状态通道（state channels）
├── managed/         # 由运行时托管的特殊状态值
├── func/            # @task / @entrypoint 函数式 API
└── _internal/       # 内部基础设施

4.2 graph/ ------ 图构建层

文件	功能
`__init__.py`	导出公共 API：`START`、`END`、`StateGraph`、`CompiledStateGraph`、`MessageGraph`、`MessagesState`、`add_messages`
`state.py`	图构建器与编译产物
`message.py`	面向消息（LLM 对话）的特化图与 reducer
`_node.py`	节点规格 dataclass
`_branch.py`	条件分支规格
`ui.py`	面向 UI 的消息原语

类/函数说明

StateGraph ：核心构建器。方法：add_node（添加计算节点，接受 Runnable/Callable，可带 metadata、retry_policy、cache_policy、timeout、is_error_handler、trace_policy）、add_edge（固定边，支持多来源汇聚）、add_conditional_edges（根据路由函数动态选支）、add_sequence（快捷链式连接）、set_entry_point（指定入口节点）、compile()（编译为可执行 CompiledStateGraph，可传入 checkpointer、store、stream 配置）。
CompiledStateGraph ：编译产物，继承自 Pregel，即真正可执行对象。提供 get_graph/get_graph_v2（导出可视化图结构）、copy、validate、get_state/get_state_history（读取线程状态与检查点历史）、update_state（人工改写状态）、stream/astream/invoke/ainvoke、clear_cache、以及 attach_node/attach_edge/attach_branch（供框架内部组装图）。
add_messages：消息列表的 reducer------把新消息增量合并进状态（按 id 追加/替换/删除），是 LLM 对话状态的标准 reducer。
MessagesState ：预定义的状态 schema，含 messages 键并使用 add_messages。
MessageGraph ：以 MessagesState 为状态的便捷子类。
REMOVE_ALL_MESSAGES：哨兵值，用于从状态中清空全部消息。
StateNodeSpec （_node.py）：描述一个节点的完整规格（runnable、metadata、retry_policy、cache_policy、is_error_handler、timeout、trace_policy），供编译期与运行时使用。
BranchSpec （_branch.py）：描述条件分支（路由函数 + 路由结果到目标节点的映射）。
UIMessage / push_ui_message / delete_ui_message （ui.py）：在图执行中向外部 UI 流式推送/删除临时消息，不污染持久化状态。

4.3 pregel/ ------ Pregel 执行引擎（核心）

Pregel 是整个框架的心脏：把 StateGraph 编译成「通道 + 任务」的执行计划，按超步（super-step）调度执行，支持检查点、流式输出、重试、缓存。

文件	功能
`main.py`	`Pregel` 主类 + `NodeBuilder`
`protocol.py`	Pregel/Stream 协议定义
`debug.py`	执行轨迹 → 可视化结构（graph + checkpoint 视图）
`remote.py`	远程图代理
`_loop.py`	执行循环
`_algo.py`	任务调度算法（核心）
`_call.py`	任务调用封装
`_checkpoint.py`	检查点工具函数
`_executor.py`	后台任务执行器
`_io.py`	通道读/写与 Command 映射
其余 `_*.py`	流式、重试、超时等支撑

类/函数说明

Pregel （main.py）：核心执行类（继承 Runnable）。方法：get_graph、copy、validate、get_state / get_state_history / update_state、stream / astream（多种 stream mode：values/updates/messages/debug 等）、invoke / ainvoke（单次调用至完成）、clear_cache。
NodeBuilder （main.py）：节点配置 DSL，方法 subscribe_to（读哪些通道）、read_from、do（执行体）、write_to（写哪些通道）、add_retry_policies、set_timeout、build。
PregelProtocol / StreamProtocol / StreamChunk （protocol.py）：抽象执行协议，使本地/远程、同步/异步实现可互换。
map_debug_tasks / map_debug_checkpoint （debug.py）：把内部任务/检查点映射为 debug 流模式下的可视化结构。
RemoteGraph / RemoteException （remote.py）：把本地图代理到远程 LangGraph server 执行。
PregelLoop / SyncPregelLoop / AsyncPregelLoop / DuplexStream （_loop.py）：执行循环。每个超步：取当前通道快照 → 选出可执行任务 → 并发执行 → 应用写回；DuplexStream 同时承担输入队列与输出流。
apply_writes / prepare_next_tasks / prepare_push_task_send / should_interrupt （_algo.py）：调度核心------把一批写操作合并进通道、计算下一批任务、处理 Send 动态分支、判断是否需要中断（HITL）。
call 封装 （_call.py）：统一任务调用入口（同步/异步、重试、超时、事件发射）。
empty_checkpoint / create_checkpoint / copy_checkpoint / channels_from_checkpoint （_checkpoint.py）：检查点的创建/复制/反通道化工具。
BackgroundExecutor / AsyncBackgroundExecutor / next_tick （_executor.py）：后台任务线程池与事件循环调度。
read_channel / read_channels / map_command （_io.py）：通道读取与 Command 对象到写的映射。

4.4 channels/ ------ 状态通道

通道是 Pregel 执行模型中「状态变量」的底层实现，每个通道封装一种合并语义。

BaseChannel （抽象基类）：copy / checkpoint / from_checkpoint / get / is_available / update / consume / finish。
具体通道：
- LastValue：最后写入值获胜（默认语义）。
- LastValueAfterFinish：finish 阶段才发布。
- Topic ：消息主题，追加式（配合 EphemeralValue 等）。
- AnyValue：首个写入生效。
- EphemeralValue：用完即弃，不进入检查点。
- UntrackedValue：不被检查点跟踪。
- NamedBarrierValue：命名屏障，用于同步「所有分支都就绪」。
- BinaryOperatorAggregate ：二元算子聚合（即 reducer，add_messages 就是它的一种特化）。
- DeltaChannel：增量历史通道，支撑 delta 检查点（历史重建时只需少量数据）。

4.5 managed/ ------ 托管状态值

ManagedValue（抽象基类）：运行时自动填充的状态值，用户不可写。
IsLastStep：当前步是否为最后一步（需指定 recursion_limit）。
RemainingSteps：剩余可执行步数。

4.6 func/ ------ 函数式 API

__init__.py 导出 task 与 entrypoint：
- @task：把普通函数注册为后台任务（可依赖其他 task，自动推导 DAG）。
- @entrypoint：声明图的入口任务。这是比 StateGraph 更轻量的「函数式」写法。

4.7 types.py ------ 公共类型

interrupt(value) ：函数------在节点中抛出中断，图暂停并持久化，resume 时继续（HITL 核心原语）。
Send：动态分支------运行时向指定节点发送一次性输入（动态扇出）。
Command：复合写操作------同时更新状态、路由到下一个节点、返回输出。
Checkpointer ：检查点器类型（BaseCheckpointSaver 及 memory/sqlite/postgres 实现）。
StreamMode：流模式（values / updates / messages / debug ...）。
StreamWriter：向 stream 写入自定义数据的句柄。
RetryPolicy / TimeoutPolicy / CachePolicy / TracePolicy：节点级策略配置。
Durability：检查点持久化强度（如 write-time / sync）。
StateSnapshot：线程状态快照（values、next 节点、metadata、created_at、parent 等）。
ensure_valid_checkpointer：校验传入的 checkpointer 合法性。

4.8 根级文件

callbacks.py ：GraphCallbackHandler（执行期回调分发）；事件类 GraphInterruptEvent / GraphLifecycleEvent / GraphResumeEvent（中断、生命周期、恢复事件）。
config.py ：节点内访问运行上下文：get_config（当前 Runnable 配置）、get_store（长期记忆 Store 句柄）、get_stream_writer（流式写入器）。
constants.py ：START、END（特殊节点名）、TAG_NOSTREAM / TAG_HIDDEN（trace 标签）。
errors.py ：异常体系------GraphRecursionError（超步数限制）、GraphInterrupt / NodeInterrupt（HITL 中断）、NodeError（节点错误捕获/重抛）、GraphBubbleUp（异常冒泡控制）、GraphDrained、EmptyChannelError 等。
runtime.py：运行时上下文对象（把 config、store、writer 打包传给节点）。
warnings.py：弃用/迁移警告辅助。

4.9 _internal/ ------ 内部基础设施

文件	功能
`_config.py`	`merge_configs` / `patch_config` / `ensure_config`、`DEFAULT_RECURSION_LIMIT`
`_constants.py`	保留写键（`INPUT` / `INTERRUPT` / `RESUME` / `ERROR` / `TASKS` / `RETURN` / `PREVIOUS`）、配置键、命名空间分隔符（`NS_SEP` / `NS_END`）、推送/拉取标记（`PUSH` / `PULL`）
`_fields.py`	状态 schema 字段解析（reducer、默认值、Channel 推断）
`_future.py`	跨线程 Future 链接（同步/异步桥接）
`_pydantic.py`	`create_model`（动态生成状态 model）
`_queue.py`	`AsyncQueue` / `SyncQueue` / `Semaphore`（流式输出队列）
`_replay.py`	`ReplayState`------time-travel 回放（从历史检查点重放到某一步）
`_retry.py`	`default_retry_on`（默认重试异常判断）
`_runnable.py`	`RunnableCallable` / `coerce_to_runnable`（把任意 callable 包成 Runnable）
`_scratchpad.py`	`PregelScratchpad`：单次执行的临时上下文（step、stop、call_counter、resume 值）
`_serde.py`	序列化器白名单构建
`_timeout.py`	节点超时工具
`_typing.py`	内部类型判断工具

章节五：libs/checkpoint ------ 检查点与记忆抽象

包 langgraph-checkpoint，其他包（postgres/sqlite/prebuilt/langgraph）都依赖它。

5.1 目录结构

复制代码

libs/checkpoint/langgraph/checkpoint/
├── base/      # 检查点核心类型与 Saver 抽象
├── serde/     # 序列化体系
├── cache/     # 检查点缓存
└── store/     # 长期记忆（跨线程）抽象

5.2 base/ ------ 检查点核心

Checkpoint （TypedDict）：单个检查点------id（版本化的 lexicographic 可比较 id）、ts（时间戳）、channel_values、channel_versions、versions_seen、pending_sends、metadata。
CheckpointTuple（NamedTuple）：检查点 + 该点上的 pending writes + config。
PendingWrite：一条未应用到检查点的写操作（通道、值、来源任务）。
BaseCheckpointSaver （Generic 基类）：所有检查点器的抽象------put / put_writes / get_tuple / list（+ Async 变体 aput / aget_tuple / alist）；泛型参数表示其序列化器类型。
empty_checkpoint / create_checkpoint / copy_checkpoint：检查点构造与浅拷贝工具。
DeltaChannelHistory：delta 通道的历史结构（支撑增量检查点）。
LATEST_VERSION = 2 、WRITES_IDX_MAP：版本常量与写索引映射。
id.py：检查点 id 生成------UUID v6/v7/v8（时间有序，便于排序与分区）。

5.3 serde/ ------ 序列化

SerializerProtocol：序列化器协议（runtime_checkable）。
JsonPlusSerializer ：默认序列化器，基于 ormsgpack，JSON 扩展类型（支持 dict/list/TypedDict/pydantic 等）；提供 with_msgpack_allowlist（严格白名单模式，只允许安全类型进入 msgpack 二进制通道------SAFE_MSGPACK_TYPES）。
EncryptedSerializer：AES 加密封装（依赖 PyCryptodome），用于敏感状态。
event_hooks.py ：SerdeEvent 监听/发射（序列化/反序列化事件钩子，供安全审计）。
_msgpack.py：严格模式白名单机制。

5.4 cache/ ------ 检查点缓存

BaseCache （抽象基类）：get / set（带 TTL）+ 异步变体。
InMemoryCache：进程内实现（RLock + TTL 过期）。
RedisCache：Redis 实现（MGET/pipeline 批量 + TTL）。

5.5 store/ ------ 长期记忆（跨线程）

BaseStore （抽象基类）：键为 (namespace, item_key) 的两级 KV 记忆。核心方法：put / get / search（支持向量检索 + TTL + 过滤）；操作类型 TypedDict：Item / SearchItem / GetOp / SearchOp / PutOp / ListNamespacesOp；配置：TTLConfig / IndexConfig。
AsyncBatchedBaseStore：后台批处理 + 后台清理（TTL sweep）的 Store 基类。
embed.py ：嵌入函数解析（embeddings 配置 → 实际 embedding 模型）。
InMemoryStore：进程内实现（含向量搜索、TTL 线程）。

5.6 其他

memory.py ：InMemorySaver ------内存检查点器，开发/测试默认；MemoryStore（便捷入口）。
serialize.py ：serde 顶层工具。

章节六：libs/checkpoint-postgres / checkpoint-sqlite ------ 持久化实现

6.1 checkpoint-postgres（包 `langgraph-checkpoint-postgres`）

复制代码

langgraph/checkpoint/postgres/
├── __init__.py
├── _async.py / _sync.py
└── migrations.py

PostgresSaver / AsyncPostgresSaver ：基于 psycopg 连接池的检查点器。关键方法：from_conn_string（连接工厂）、setup（建表 + 迁移）、put / put_writes / get_tuple / list、prune （按策略清理旧线程检查点）、get_delta_channel_history（两阶段查询重建 delta 通道峰值内存------先查索引再按窗口拉取，避免全量回放）。
ShallowPostgresSaver ：仅保存最新检查点（已弃用，被 prune 策略替代）。
MIGRATIONS：DDL 迁移脚本列表。
PRUNE_STRATEGIES：清理策略（按线程数/按天数/按运行数等）。

6.2 checkpoint-sqlite（包 `langgraph-checkpoint-sqlite`）

复制代码

langgraph/checkpoint/sqlite/
├── __init__.py
├── _sync.py / _async.py
├── _delta.py
└── store/            # SqliteStore / AsyncSqliteStore + 向量索引

SqliteSaver / AsyncSqliteSaver ：SQLite 检查点器。from_conn_string 返回上下文管理器（自动 PRAGMA WAL、busy_timeout）；版本号格式 {v:032}.{h:016}（32 位大版本 + 16 位同版本序号）。
_delta.py：用递归 CTE 回溯检查点链 + UNION ALL 重建 delta 通道历史（SQL 侧完成峰值内存计算，避免 Python 全量回放）。
SqliteStore / AsyncSqliteStore ：SQLite 长期记忆------TTL 后台清扫、向量嵌入列、MIGRATIONS / VECTOR_MIGRATIONS。
SqliteCache：SQLite 检查点缓存。

章节七：libs/checkpoint-conformance ------ 一致性测试套件

目的：任何新的 CheckpointSaver/Store 实现都必须通过同一套能力测试，保证行为一致。

复制代码

langgraph/checkpoint/conformance/
├── capability.py    # 能力探测
├── validate.py      # 异步主运行器
├── report.py        # 能力报告
├── callbacks.py     # 进度回调
└── spec/            # 9 个能力测试套

Capability （Enum）：逐项探测 saver 是否覆写了哪些方法（如 put_writes、list、delete_thread、copy_thread、prune、get_delta_channel_history）；DetectedCapabilities.from_instance 自动判定。
validate：异步主运行器------按探测结果选择要执行的能力套并汇总。
ProgressCallbacks / CapabilityReport：进度通知与结果报告。
spec/ 下 9 个能力套 ：put、put_writes、get_tuple、list、delete_thread、delete_for_runs、copy_thread、prune、delta_channel_history。

章节八：libs/cli ------ 命令行工具（langgraph CLI）

包 langgraph-cli（v0.4.38），用于开发、构建、部署 LangGraph 应用（基于 Docker 镜像 + LangSmith 控制面）。

8.1 目录结构

复制代码

langgraph_cli/
├── cli.py                    # Click 主命令入口
├── config.py                 # langgraph.json 解析
├── deploy.py                 # 构建 + 上传 + 控制面 API
├── docker.py                 # 镜像构建
├── exec.py                   # 命令执行器
├── archive.py                # 源码 tarball
├── dependency_tracking.py    # Python 依赖追踪
├── host_backend.py           # 控制面客户端
├── image_reference.py        # 镜像引用解析
├── progress.py               # 进度展示
├── schemas.py                # 配置 schema
├── templates.py              # 项目模板
├── uv_lock.py                # uv lock 依赖锁定
├── _ignore.py                # .gitignore/.dockerignore 过滤
├── analytics.py              # 匿名遥测
└── constants.py              # 常量

8.2 子命令与文件说明

主命令（cli.py） ：子命令 up（本地起服务）、build（构建镜像/包）、dockerfile（生成 Dockerfile）、dev（开发模式热重载）、validate（校验 langgraph.json）、new（从模板创建项目）、deploy（部署到控制面）。
config.py ：解析 langgraph.json------图的入口、Python 版本、平台发行版（Distros）等。
deploy.py：构建产物 + 上传 + 调用 LangSmith 控制面 API 完成部署。
docker.py：构建 Docker 镜像，检测本地构建能力（fallback 到远程构建）。
exec.py ：CommandRunner + asyncio 桥接（同步壳层里跑异步命令）。
archive.py：把源码打成 tarball 供远程构建。
dependency_tracking.py：追踪 Python 包依赖（用于 lock 与部署清单）。
host_backend.py ：ControlPlaneEndpoints / HostBackendClient------控制面端点解析与 HTTP 客户端。
image_reference.py ：ImageReference 解析 repo:tag / repo@digest 格式。
progress.py：spinner 等进度 UI。
schemas.py：配置 TypedDict（校验用）。
templates.py：项目模板（Deep Agent / Agent / New LangGraph Project）。
uv_lock.py ：依赖 → uv lock / Docker 内安装。
_ignore.py ：按 .gitignore / .dockerignore 过滤上下文。
analytics.py：匿名遥测。
constants.py ：DEFAULT_CONFIG = "langgraph.json"、DEFAULT_PORT = 8123 等。

章节九：libs/prebuilt ------ 开箱即用组件

包 langgraph-prebuilt，提供常见 agent 模式的现成实现（构建在 langgraph 之上）。

9.1 目录结构

复制代码

langgraph/prebuilt/
├── __init__.py
├── chat_agent_executor.py    # create_react_agent
├── tool_node.py              # ToolNode
├── tool_validator.py         # 工具调用校验
├── interrupt.py              # 工具调用前的 HITL 中断
├── _tool_call_transformer.py # 工具调用流式转换
└── _tool_call_stream.py      # 工具调用流式细节

9.2 类/函数说明

create_react_agent （chat_agent_executor.py）：一行创建一个 ReAct 风格 agent（模型 + 工具列表 + 可选 checkpointer/store），内部组装 StateGraph（agent 节点 + 工具节点 + 路由）。
ToolNode （tool_node.py）：把一批工具调用解析为可执行 Runnable（执行工具并写回结果）。
ToolCallTransformer （_tool_call_transformer.py）：把 LLM 的工具调用事件转换为可读的工具调用流式输出。
tools_condition：路由函数------有未处理的工具调用 → 走 ToolNode，否则结束。
ValidationNode （tool_validator.py）：校验工具调用参数是否合法（schema 检查）。
InjectedState / InjectedStore / ToolRuntime：让工具函数注入读取 agent 状态 / 长期记忆 / 运行时句柄的专用参数类型。
interrupt 相关 （interrupt.py）：工具调用前的人工审批中断（HITL 标准用法）。

章节十：libs/sdk-py ------ Python 客户端

包 langgraph-sdk（v0.4.9），用于调用远程或本地 LangGraph 服务（server）的 HTTP/WS 客户端。

10.1 目录结构

复制代码

langgraph_sdk/
├── client.py            # 客户端主类
├── auth/                # 鉴权（API key / 控制面 token）
├── encryption/          # 敏感字段加密
├── priority/            # PrioritySettings（请求优先级）
├── cache.py             # 连接/会话缓存
└── stream/              # 流式引擎
    ├── 控制器 + 传输层（SSE / WebSocket）
    └── multi_cursor_buffer（多游标缓冲）

10.2 类/函数说明

LangGraphClient / SyncLangGraphClient：主客户端（异步/同步双版本）。
资源子客户端（各有 Sync 版）：
- ThreadsClient：线程（对话会话）的 CRUD + 状态读取。
- RunsClient：运行（run）的创建/等待/取消/流式结果。
- StoreClient：长期记忆读写（对应 server 侧 Store）。
- AssistantsClient：assistant（图的部署单元）管理。
- CronClient：定时任务（cron run）管理。
stream/：流式引擎------控制器 + SSE/WebSocket 双传输 + 多游标缓冲（同时消费多种 stream mode）。
auth/：API key / 控制面 token 鉴权。
encryption/：请求中敏感字段加密。
priority/ ：PrioritySettings 请求优先级配置。

章节十一：libs/sdk-js

目录中只有 README.md------JS SDK 源码不在本仓库（独立发布到 npm），README 指向其独立仓库。

章节十二：学习路线与关键文件索引

12.1 建议阅读顺序

入口：README.md + AGENTS.md（宏观定位与依赖关系）。
核心模型 ：libs/langgraph/langgraph/types.py（interrupt/Send/Command 原语）→ graph/state.py（StateGraph 构建）→ pregel/main.py（Pregel 执行）→ channels/（状态语义）→ _algo.py（调度算法）。
持久化 ：checkpoint/base/（抽象）→ checkpoint/memory.py（最简单实现，理解接口）→ checkpoint-sqlite / checkpoint-postgres（生产实现，重点看 delta 历史机制）。
长期记忆 ：checkpoint/store/（BaseStore + InMemoryStore）。
开箱即用 ：prebuilt/chat_agent_executor.py（create_react_agent 内部就是 StateGraph 的标准用法示例）。
工具链 ：cli/cli.py（子命令）→ config.py / deploy.py（部署流程）；sdk-py/client.py（客户端）。
动手：examples/ 的 notebook（react-agent-from-scratch 最适合配合源码读）。

12.2 高频关键文件速查

想了解的内容	去看
图怎么定义（节点/边/条件）	`libs/langgraph/langgraph/graph/state.py`
执行引擎（超步调度）	`libs/langgraph/langgraph/pregel/main.py` + `pregel/_algo.py` + `pregel/_loop.py`
状态变量合并语义	`libs/langgraph/langgraph/channels/`
HITL 中断/resume	`libs/langgraph/langgraph/types.py`（`interrupt`）+ `errors.py`（`GraphInterrupt`）
检查点存取	`libs/checkpoint/langgraph/checkpoint/base/` + `memory.py`
生产级检查点（Postgres/SQLite）	`libs/checkpoint-postgres/`、`libs/checkpoint-sqlite/`（含 `_delta.py` 增量重建）
跨线程长期记忆	`libs/checkpoint/langgraph/checkpoint/store/`
一行造 ReAct agent	`libs/prebuilt/langgraph/prebuilt/chat_agent_executor.py`
命令行/部署	`libs/cli/langgraph_cli/`
远程调用（SDK）	`libs/sdk-py/langgraph_sdk/`
一致性测试	`libs/checkpoint-conformance/`

12.3 与 LangChain 的关系

LangChain 提供组件（模型、工具、检索器、消息类型等），LangGraph 提供编排（有状态的图执行、检查点、HITL、记忆）。
langgraph-prebuilt 是两者的「胶水层」------create_react_agent 接收 LangChain 的 model/tools，内部用 LangGraph 的 StateGraph 组装。
检查点体系（checkpoint）与 LangSmith 的 trace 配合，实现「可恢复、可回放、可观测」的长运行 agent。

AI应用开发之LangGraph解析

LangGraph 源码分析（langgraph-main）

目录

章节一：项目用途说明

1.1 这个项目的用途是什么

1.2 核心功能用途

1.3 与 LangChain 的关系

1.4 包分层

章节二：如何使用

2.1 前置条件

2.2 安装步骤

2.3 使用方式

2.4 关键配置项说明

2.5 常见问题

章节三：仓库总览

3.1 核心特性（来自 README）

3.2 顶层目录结构

3.3 包依赖分层（来自 AGENTS.md）

3.4 examples 目录（学习入口）

章节四：libs/langgraph ------ 核心框架包

4.1 目录结构

4.2 graph/ ------ 图构建层

4.3 pregel/ ------ Pregel 执行引擎（核心）

4.4 channels/ ------ 状态通道

4.5 managed/ ------ 托管状态值

4.6 func/ ------ 函数式 API

4.7 types.py ------ 公共类型

4.8 根级文件

4.9 _internal/ ------ 内部基础设施

章节五：libs/checkpoint ------ 检查点与记忆抽象

5.1 目录结构

5.2 base/ ------ 检查点核心

5.3 serde/ ------ 序列化

5.4 cache/ ------ 检查点缓存

5.5 store/ ------ 长期记忆（跨线程）

5.6 其他

章节六：libs/checkpoint-postgres / checkpoint-sqlite ------ 持久化实现

6.1 checkpoint-postgres（包 langgraph-checkpoint-postgres）

6.2 checkpoint-sqlite（包 langgraph-checkpoint-sqlite）

章节七：libs/checkpoint-conformance ------ 一致性测试套件

章节八：libs/cli ------ 命令行工具（langgraph CLI）

8.1 目录结构

8.2 子命令与文件说明

章节九：libs/prebuilt ------ 开箱即用组件

9.1 目录结构

9.2 类/函数说明

章节十：libs/sdk-py ------ Python 客户端

10.1 目录结构

10.2 类/函数说明

章节十一：libs/sdk-js

章节十二：学习路线与关键文件索引

12.1 建议阅读顺序

12.2 高频关键文件速查

12.3 与 LangChain 的关系

6.1 checkpoint-postgres（包 `langgraph-checkpoint-postgres`）

6.2 checkpoint-sqlite（包 `langgraph-checkpoint-sqlite`）