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

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

【免费下载链接】langgraphBuild resilient agents.项目地址: https://gitcode.com/GitHub_Trending/la/langgraph

本文以 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"，而是一组执行原语：

二、快速安装与版本事实

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_messagesreducer 完成；
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中声明为本地可编辑源）包括：

这种分层与 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 独立使用。

【免费下载链接】langgraphBuild resilient agents.项目地址: https://gitcode.com/GitHub_Trending/la/langgraph