LangGraph：构建具备韧性的有状态 AI 智能体

1. 项目概述

LangGraph 是一个低级编排框架，用于构建、运行和管理长时间运行的有状态 AI 智能体——它解决了将智能体从脆弱的原型转变为具备韧性、生产级系统的问题，该系统能够循环、分支、暂停并从故障中恢复。

2. 背景与定位

LangGraph 由 LangChain 团队创建，旨在填补简单提示链库无法填补的空白：现实世界中的智能体需要重试、自我纠正、等待人工批准，并在长时间运行或中断的执行过程中保持状态。其核心使命是让开发者对智能体逻辑和状态拥有精确的底层控制——而不是将所有东西都隐藏在高级黑盒背后——同时仍提供生产系统所需的持久性保证。

在架构上，LangGraph 将智能体的工作流建模为有状态的有向循环图，灵感来自 Google 的 Pregel 和 Apache Beam，API 风格受 NetworkX 影响。这使其有别于纯线性流水线框架：典型的链执行固定序列的步骤并丢弃中间上下文，而 LangGraph 维护一个共享的、有类型的状态对象，图中的每个节点都可以读取和更新该对象，并且图可以循环回自身以进行反思、重试或迭代规划。截至 2026 年，LangGraph 还作为 LangChain 自有智能体的底层执行运行时，使其成为 LangChain 生态系统中复杂智能体工作流的通用基础。

3. 功能类别

🧩 图编排 — 用于定义节点、边和条件路由的核心 API。代表性示例：StateGraph、条件边、循环图、子图、受 Pregel 启发的执行模型。目的：将任意复杂的智能体控制流（包括循环和分支）表达为图，而不是固定脚本。
💾 持久执行与持久化 — 用于在崩溃中幸存并恢复工作的机制。代表性示例：检查点、基于线程的状态持久化、任务重试、可恢复运行。目的：让智能体在故障或重启后准确地从中断处继续，而不是从头开始。
🧠 记忆系统 — 用于智能体的短期和长期记忆原语。代表性示例：共享状态对象、跨会话长期记忆存储、记忆感知检索。目的：为智能体提供当前任务的工作记忆和跨对话的持久记忆。
🧑‍⚖️ 人在回路控制 — 内置中断和批准机制。代表性示例：中断节点、状态检查、手动状态编辑、敏感操作前的批准网关。目的：让人类在智能体采取重大行动之前审查、暂停或重定向智能体。
🔍 调试与可观测性 — 用于可视化和追踪智能体运行的工具。代表性示例：LangGraph Studio、LangSmith 追踪集成、从任意检查点重放运行、分支重放调试。目的：使原本不透明的多步智能体行为变得可检查和可复现。
🚀 部署基础设施 — 用于在生产中运行智能体的工具和服务。代表性示例：LangGraph Platform、可扩展任务队列、流式 API、服务器模板。目的：将智能体从本地脚本移动到可扩展、受监控的生产服务。

4. 核心亮点

循环图模型 — 与线性流水线不同，LangGraph 图可以循环回先前的节点，这对于重试逻辑、自我纠正以及 ReAct 或规划与执行等迭代推理模式至关重要。
持久执行 — 智能体可以在进程崩溃或中断中持久化，并从离开的确切位置恢复，而不是从头开始重新启动长任务。
一流的人工监督 — 人在回路批准是内置的图原语（中断节点），而不是事后附加到框架上的。
组合记忆模型 — 同时支持短期工作状态和长期持久记忆，让智能体在任务内和跨会话保持上下文。
深度可观测性 — 与 LangSmith 和 LangGraph Studio 的原生集成提供可视化图检查、执行追踪和基于重放的调试。
框架无关的控制 — 作为低级库，LangGraph 不强制特定的智能体架构；团队可以在相同原语上实现 ReAct 风格的智能体、多智能体系统或完全自定义的控制流。

5. 按角色的使用场景

通用开发者 — 构建需要分支逻辑、重试或多步工具使用的自定义对话或任务执行智能体，这些超出了简单提示链所能提供的功能。
DevOps/SRE — 使用 LangGraph Platform 部署和操作长时间运行的智能体工作流，具备持久执行和检查点功能，以在基础设施中断中幸存。
数据/研究科学家 — 使用 LangGraph Studio 进行可视化检查和快速调试，以原型化和迭代复杂的智能体架构（多智能体协作、反思循环、工具增强推理）。
项目经理 — 引入人在回路批准网关，以便处理敏感或高风险操作的智能体在继续之前需要签署，从而降低运营风险。

6. 入门指南

找到你需要的内容 — 浏览官方文档和 API 参考，获取关于图、状态、持久化和部署的指南：

https://langchain-ai.github.io/langgraph/

安装和集成 — 通过 pip 将 LangGraph 添加到 Python 项目中（也提供 JavaScript/TypeScript 版本 LangGraph.js）：

pip install -U langgraph

贡献 — 复刻仓库，查看贡献指南，并提交拉取请求：

git clone https://github.com/langchain-ai/langgraph.git

7. 项目结构（可选）

langgraph/
├── .github/     # CI 工作流和仓库配置
├── docs/        # 官方文档站点的文档源
├── examples/    # 示例智能体实现和使用模式
└── libs/        # 核心库包（图引擎、检查点、预构建组件）

libs/ 包含核心编排引擎和支持持久执行的检查点/持久化实现。
examples/ 是在编写自己的代码之前查看工作智能体图的最快方式。
docs/ 镜像已发布的文档站点，是查找最新 API 变更的好地方。

8. 相关生态系统

LangChain — 提供 LangGraph 智能体通常编排的组件库（模型、工具、检索器）；截至 2026 年，LangChain 自有的智能体运行在 LangGraph 运行时上。
LangSmith — 用于追踪、调试和监控 LangGraph 智能体运行的可观测性和评估平台。
LangGraph Platform — 用于在生产中部署和扩展 LangGraph 智能体的托管基础设施。
LangGraph Studio — 用于检查图结构、单步执行和从检查点重放运行的可视化调试器。
Deep Agents — 位于 LangGraph 之上的高级智能体构建层，适合需要更多开箱即用脚手架的团队。
LangGraph.js — 面向在 Python 生态系统之外构建智能体的团队的 JavaScript/TypeScript 对应版本。

9. 许可证

✅ 根据 MIT 许可证，可免费使用、修改和分发，包括用于商业和专有产品。
✅ 明确授予再授权和销售软件副本的许可。
❌ 不提供任何担保；作者不对因使用软件而产生的损害负责。
ℹ️ 代码的任何实质性副本或再分发都必须包含 MIT 许可证文本和版权声明。

10. 常见问题

问：使用 LangGraph 需要 LangChain 吗？
答：不需要。LangGraph 是一个独立的低级编排库，尽管它与 LangChain 组件自然集成，并且截至 2026 年，它是 LangChain 自有智能体运行时的基础。

问：LangGraph 与简单提示链有何不同？
答：提示链执行固定的线性步骤序列。LangGraph 将工作流建模为具有共享状态的有向循环图，因此智能体可以循环、分支、重试并暂停以等待人工输入。

问：LangGraph 智能体能在崩溃或重启中幸存吗？
答：能。通过其检查点和持久化机制，LangGraph 支持持久执行，允许智能体从上次保存的状态恢复，而不是从头开始。

问：有可视化的方式调试智能体图吗？
答：有，LangGraph Studio 提供可视化界面来检查图结构、查看每个节点的状态，并从任意检查点重放执行。

问：LangGraph 在 Python 之外可用吗？
答：可用，LangGraph.js 为 JavaScript 和 TypeScript 项目提供等效功能。

11. 快速链接

仓库：https://github.com/langchain-ai/langgraph
官方文档：https://langchain-ai.github.io/langgraph/
贡献指南：https://github.com/langchain-ai/langgraph/blob/main/CONTRIBUTING.md
社区/讨论：https://github.com/langchain-ai/langgraph/discussions

12. 总结

LangGraph 为全球的开发团队提供了一个持久、可检查的基础，用于构建超越简单线性提示链的智能体——开箱即用地支持循环、分支、人工监督和崩溃恢复。它最适合需要生产级可靠性和对智能体行为进行细粒度控制的开发者和团队，从原型化新智能体架构的个人工程师到在面向客户的产品中大规模操作智能体的组织。