LangGraph 核心库详解：从 README 到构建有状态长时运行 Agent 的源码级解读

本文以 LangGraph 核心包（libs/langgraph）的 README 为骨架，完整覆盖其定位、安装方式、与 LangChain 的分工关系，并结合当前仓库的源码结构与 pyproject.toml 元数据，带你读懂这个"低层编排框架"到底由哪些模块组成、依赖如何划分、设计灵感从何而来。读完后，你将清楚 LangGraph 在 Agent 技术栈中的位置，并能定位到各核心能力（状态图、Pregel 执行引擎、流式、通道、检查点）对应的源码目录。

一、LangGraph 是什么：低层 Agent 编排框架

README 对 LangGraph 的核心定义是：

LangGraph is a low-level orchestration framework for building, managing, and deploying long-running, stateful agents. LangGraph provides the infrastructure for durable execution, streaming, human-in-the-loop, persistence, memory, and more.

即 LangGraph 是一个低层编排框架，面向"长时间运行、有状态"的 Agent 应用，提供以下基础设施能力：

• Durable execution（持久执行）：执行过程可中断、可恢复，依赖检查点（checkpoint）机制落盘；
• Streaming（流式输出）：节点级、消息级的增量输出；
• Human-in-the-loop（人机协同）：在关键节点暂停执行、等待人工介入后继续；
• Persistence（持久化）与 Memory（记忆）：会话状态与长期记忆的存储抽象。

"低层"意味着它不做黑盒封装：你显式地声明图（节点与边）、定义状态模式与 reducer，从而获得对控制流与延迟的精确控制。这与当前仓库的源码结构完全吻合——核心包 langgraph/ 目录下并没有"开箱即用的 Agent"，而是一组执行原语：

目录	职责
graph/	图构建 API：StateGraph、MessageGraph、节点/边声明
pregel/	执行引擎（Pregel 类），负责超步（superstep）调度、循环与迭代
channels/	状态通道：LastValue、Topic、EphemeralValue 等状态更新语义
stream/	流式基础设施：传输、转换器（transformers）、run stream
func/	函数式 API（装饰器风格的图定义）
managed/	托管值（如 IsLastStep），由运行时注入的只读状态字段
types.py	核心类型：State、NodeSpec、Interrupt、Send 等
constants.py	全局常量，包括保留节点名 START、END

二、快速安装与版本事实

README 给出的安装方式是：

uv add langgraph

结合仓库中的 pyproject.toml 可以确认当前核心包的关键元数据：

• 包名与版本：langgraph，当前版本 1.2.11；
• Python 要求：>=3.10（classifiers 覆盖 3.10～3.13）；
• 许可证：MIT；
• 核心依赖：
  • langchain-core>=1.4.7,<2
  • langgraph-checkpoint>=4.1.0,<5.0.0（检查点基类与内存实现）
  • langgraph-sdk>=0.4.2,<0.5.0（远程运行/流式 SDK）
  • langgraph-prebuilt>=1.1.0,<1.2.0（预构建组件，如 ToolNode）
  • xxhash>=3.5.0、pydantic>=2.7.4

值得注意的是依赖版本均带上界约束（如 <2、<5.0.0），从 版本策略相关描述 和依赖声明可以推断，该项目采用较严格的语义化版本管理，升级主版本前需要显式验证兼容性。

另外，pyproject.toml 中通过 [tool.uv.sources] 把 langgraph-prebuilt、langgraph-checkpoint、langgraph-checkpoint-sqlite、langgraph-checkpoint-postgres、langgraph-sdk、langgraph-cli 指向 monorepo 内的本地可编辑路径，说明核心库与这些周边包在同一仓库中协同开发。

三、LangGraph 与 LangChain 的分工

README 中有一段明确的选型指引，原文语义为：

• 何时用 LangGraph：当你有"高级需求"——需要确定性工作流与 agentic 工作流组合、重度定制、以及精细的延迟控制时；
• 何时用 LangChain：当你想使用预构建的 Agent 架构与模型集成、快速搭建 LLM 应用时；
• 两者的关系：LangChain 的 agents 正是构建在 LangGraph 之上，从而获得持久执行、流式、人机协同、持久化等能力；普通用户直接使用 LangChain agents 时甚至无需了解 LangGraph。

一句话总结：LangChain 提供高层便捷，LangGraph 提供底层控制，且上层能力（LangChain agents）复用下层引擎。这也解释了仓库结构：libs/langgraph（核心引擎）与 libs/prebuilt（预构建件，如 ToolNode、ChatAgentExecutor）分属两个包，预构建件依赖而非替代核心引擎。

四、核心包的对外 API 面

尽管 README 篇幅不长，但结合源码可以确认核心包的公开 API 面非常克制。图构建入口在 graph/init.py 中，全部导出仅 6 项：

from langgraph.constants import END, START
from langgraph.graph.message import MessageGraph, MessagesState, add_messages
from langgraph.graph.state import StateGraph

__all__ = (
    "END",
    "START",
    "StateGraph",
    "add_messages",
    "MessagesState",
    "MessageGraph",
)

可以看到三个核心构建原语：

1. StateGraph：通用状态图，节点间通过用户定义的状态模式与更新规则（reducer）通信；
2. MessageGraph / MessagesState：面向消息列表的特化图，消息追加由 add_messages reducer 完成；
3. START / END：保留的入口/出口节点名，所有图都从 START 开始、在 END 结束。

而真正驱动图运行的执行引擎在 pregel/init.py 中导出：

from langgraph.pregel.main import NodeBuilder, Pregel

__all__ = ("Pregel", "NodeBuilder")

Pregel 是 StateGraph 编译（compile()）后的产物类型，负责多轮 superstep 执行、循环判定、流式事件发射与检查点写入——这正是 README 所说"durable execution、streaming、human-in-the-loop"这些基础设施能力的落点。

从源码结构看，核心包还提供 stream/ 子包（包含 run_stream.py、transformers.py 等）支撑多协议流式输出，以及 runtime.py、callbacks.py 支撑运行期上下文与事件回调，为上层 CLI/Server 部署场景提供统一入口。

五、设计灵感与工程背景

README 的 Acknowledgements 一节给出了清晰的技术血统：

• Pregel（Google 的图并行计算模型）：LangGraph 的执行引擎命名与"bulk-synchronous parallel（ BSP）"超步调度思想直接来源于此；
• Apache Beam：流/批统一处理模型的设计参照；
• NetworkX：图的公共接口（节点、边的声明方式）借鉴自 NetworkX。

同时 README 明确说明：LangGraph 由 LangChain Inc 开发，可以脱离 LangChain 单独使用。依赖声明印证了这一点——langchain-core 只是依赖之一，核心执行引擎（Pregel、channels）本身不强制绑定任何 LLM 框架。

六、monorepo 中的位置：周边能力如何与核心库协作

当前仓库是一个多包 monorepo，libs/ 目录下与核心库协同的包（均在 pyproject.toml 的 tool.uv.sources 中声明为本地可编辑源）包括：

包目录	作用
libs/checkpoint	检查点抽象与内存实现（langgraph-checkpoint），是"durable execution"的地基
libs/checkpoint-postgres	Postgres 检查点后端（含异步、shallow 变体）
libs/checkpoint-sqlite	SQLite 检查点后端（含 delta 通道迁移、TTL 等测试）
libs/checkpoint-conformance	检查点后端的统一一致性测试规范（conformance spec）
libs/prebuilt	预构建组件：ToolNode、ChatAgentExecutor 等
libs/sdk-py	客户端 SDK：threads/runs/assistants 管理及流式传输（HTTP/WebSocket）
libs/cli	CLI 工具：本地运行、部署、依赖分析

这种分层与 README 的能力宣称一一对应：核心包负责图与执行引擎，checkpoint 系包负责状态持久化的多种后端（并有独立的 conformance 规范验证各后端行为一致），prebuilt 提供开箱组件，sdk 与 cli 负责远程运行与部署链路。

仓库根目录下的 examples/ 提供了大量可运行示例（react-agent、multi-agent-collaboration、plan-and-execute、RAG 系列、human-in-the-loop 等），README 中提到的"文档与教程"即对应这些示例与外部官方文档站。

七、文档与贡献入口

README 最后给出了三个后续入口（原文为外部文档站链接，此处仅说明其内容指向，请查阅官方文档站）：

1. API Reference：langgraph 包的完整 API 文档；
2. LangGraph Docs：概念指南、教程与示例；
3. Quickstart：五分钟跑通第一个图的入门教程。

版本方面，README 指向官方的 Releases 与 Versioning 策略页面；结合 pyproject.toml 中 Development Status :: 5 - Production/Stable 的分类器与严格的主版本上界依赖，可以确认该库处于生产稳定阶段，升级跨主版本时建议对照依赖约束逐一验证。

贡献方面，README 明确欢迎新特性、基础设施改进与文档改进，详细流程见官方贡献指南。

小结

• 定位：LangGraph 是构建长时运行、有状态 Agent 的低层编排框架，核心能力为持久执行、流式、人机协同、持久化与记忆；
• 安装：uv add langgraph，当前版本 1.2.11，要求 Python ≥ 3.10；
• 选型：需要确定性 + agentic 混合流程、重度定制与延迟控制时用 LangGraph；快速搭建 LLM 应用用 LangChain（其 agents 本身就构建在 LangGraph 之上）；
• 源码地图：图构建看 langgraph/graph/，执行引擎看 langgraph/pregel/，状态语义看 langgraph/channels/，流式看 langgraph/stream/，持久化后端看 libs/checkpoint 系列；
• 血统：执行模型受 Pregel 与 Apache Beam 启发，图 API 受 NetworkX 启发，可脱离 LangChain 独立使用。