LangGraph：构建有状态长运行智能体的底层编排框架

官方信息表

一、项目背景：面向长运行、有状态智能体的底层编排

LangGraph 是 LangChain Inc 推出的低层（low-level）编排框架，专门用来构建、管理和部署长时间运行、有状态（long-running, stateful）的智能体。README 开篇就说，包括 Klarna、Replit、Elastic 等在内、正在塑造智能体未来的公司都在使用它。它的定位不是封装好的上层智能体产品，而是给你底层的编排能力，让你把任意工作流或智能体画成一张带状态的图来运行。

换句话说，当普通的"Prompt + 一次工具调用"式应用开始不够用——比如你需要智能体能自己循环思考、能在出错时回退、能在关键步骤停下来等人确认、能记住上次对话里你说过的话——你就进入了 LangGraph 的领域。README 把它描述为"low-level supporting infrastructure for any long-running, stateful workflow or agent"，也就是给任何长运行、有状态的工作流或智能体提供底层支撑设施，而不绑死具体业务形态。

安装命令非常简单：

pip install -U langgraph

README 还给了两条提示：如果你只是想快速搭智能体，可以看基于 LangGraph 构建的更高层包 Deep Agents，它能让智能体做规划、调用子智能体、并利用文件系统处理复杂任务；如果你用 JavaScript/TypeScript，对应的库是 LangGraph.js，文档见 JS 文档。

二、为什么用 LangGraph：五大核心能力

README 用 "Why use LangGraph?" 一节说明，它为任何长运行、有状态的工作流或智能体提供底层支撑基础设施，具体包括：

• 持久化执行（Durable Execution）：构建能在失败中存活、长时间运行的智能体，崩溃后能精确地从上次中断的地方自动恢复，详见持久化执行文档。
• 人在回路（Human-in-the-loop）：在执行过程中的任意一点插入人工监督，检查甚至修改智能体的状态，详见中断文档。
• 完整记忆（Comprehensive Memory）：打造真正有状态的智能体——既有为当前推理服务的短期工作记忆，也有跨会话的长期持久记忆，详见记忆文档。
• 用 LangSmith 调试：借助可视化工具深入观察复杂的智能体行为，追踪执行路径、捕捉状态转换、提供详细的运行时指标，详见 LangSmith。
• 生产级部署（Production-ready Deployment）：用专门为有状态、长运行工作流设计的可扩展基础设施，放心地部署复杂智能体系统，详见部署文档。

README 同时提示：开发、调试和部署 AI 智能体与 LLM 应用，建议配合 LangSmith 一起使用。

三、环境要求与安装

LangGraph 以 Python 包形式发布，要求可用的 Python 环境。安装即用：

pip install -U langgraph

-U 参数表示升级到最新版本。如果你希望用它搭配 LangChain 的组件，还需要另行安装 langchain 以及你要调用的模型（如 OpenAI、Anthropic 等）对应的 SDK；README 没有给出固定的 Python 版本号，按 LangChain 官方文档建议的现代 Python 版本使用即可。JS/TS 生态则通过 @langchain/langgraph 等 npm 包引入。

安装完成后，你不需要额外的数据库或中间件就能跑起一个最简单的图；但一旦你要用到"持久化执行""跨会话记忆""人在回路中断"这些能力，就需要按文档接入相应的存储后端（默认会把检查点写到你配置的持久层），并配合 LangSmith 做轨迹追踪。也就是说，它的"环境要求"是分层的：本地起步只要 Python 环境，上生产才需要补上持久化和观测这两块基础设施。

四、生态：与 LangChain 全家桶配合

虽然 LangGraph 可以单独使用，但它和任何 LangChain 产品都能无缝集成，给开发者一整套构建智能体的工具。README 把这称为"LangGraph ecosystem"——单用时它是一个干净的图执行库，但当你把它放进 LangChain 生态里，就同时拿到了模型接入、可观测、评估、部署这一整条流水线。README 建议把 LangGraph 与以下产品搭配：

• Deep Agents：构建能规划、调用子智能体、利用文件系统处理复杂任务的智能体。
• LangChain：提供大量集成和可组合组件，简化 LLM 应用开发。
• LangSmith：用于智能体评估与可观测——调试表现不佳的 LLM 应用、评估智能体轨迹、在生产中获得可见性、并持续改进。
• LangSmith Deployment：一个专门为长运行、有状态工作流打造的部署平台，轻松部署和扩展智能体；在团队间发现、复用、配置和共享智能体，并在 LangSmith Studio 里通过可视化原型快速迭代。这套组合的意思是：你在 LangGraph 里把图设计好，LangSmith 负责帮你看明白它跑得对不对、值不值得发布，Deployment 负责帮你把它稳稳地跑给真实用户用。

五、文档与学习资源

README 列出的官方学习入口包括：

• docs.langchain.com：综合文档，包含概念总览和使用指南。
• reference.langchain.com/python/langgraph：LangGraph 各包的 API 参考。
• LangGraph Quickstart：快速上手教程。
• Chat LangChain：和 LangChain 文档聊天、直接提问。

社区讨论请到 LangChain Forum 交流技术问题、想法和反馈。

其他资源还有：

• 指南（Guides）：docs.langchain.com/oss/python/learn，覆盖流式输出、添加记忆与持久化、设计模式（分支、子图等）的可直接运行代码片段。
• LangChain Academy：免费结构化课程，从零学 LangGraph 基础。
• 案例研究：built-with-langgraph，听行业领导者如何大规模落地 AI 应用。
• 贡献指南：contributing，学习如何给 LangChain 项目贡献代码并找到适合入门的 issue。
• 行为准则：Code of Conduct，社区参与的规范。

六、工作原理：为什么是"图"

LangGraph 把智能体抽象成一张图：节点（node）是一段处理逻辑，可以是一次大模型调用、一次工具执行或一段普通代码；边（edge）决定下一步走到哪个节点；整张图在一个共享的状态（state）上流转。这正是它受 Pregel 和 Apache Beam 这类"图计算/流式处理"系统启发的原因——把智能体的每一步看成图上的一次消息传递，把长期记忆和中间结果看成图状态的一部分。相比传统"一次 Prompt 到底"的链式调用，图结构天然支持循环、分支、条件跳转和子图，这也是它能表达"长运行、有状态"智能体的根本原因。

README 在致谢里强调，它的公开接口设计参考了 NetworkX——一个 Python 里经典的图论与网络分析库。也就是说，你可以像操作一张图那样，把节点、边、状态组织起来，而不是被一个固定的"智能体框架"绑死。这种低层定位的好处是灵活：你可以用它做最简单的链式调用，也可以搭出带循环审批、人工介入、失败重放的复杂业务流程；代价是你需要自己想清楚状态怎么定义、图怎么连，而不是开箱即用。

五大能力再深入一层

• 持久化执行：意味着智能体的每一步状态都会被落盘。跑到一半进程崩了、或者调用外部接口超时，恢复时不必从头再来，而是从最后一次检查点继续。这对要跑几分钟、几小时甚至跨天的任务尤其关键——比如一个要连续查十几个数据库、再调多次大模型的研究型智能体。
• 人在回路：在图的任意边上设一个"中断点"，跑到这里就暂停，把当前状态交给人审阅、修改甚至打回，人确认后再继续。这让 LangGraph 可以用在需要审批、对账、敏感操作前确认的真实业务里。
• 完整记忆：短期记忆支撑当前这一轮推理的上下文，长期记忆跨会话保留用户画像、历史偏好和中间结论。智能体因此不再是"每次对话都是陌生人"。
• LangSmith 调试：复杂智能体最头疼的是"它到底为什么这么想"。LangSmith 把每一次节点执行、状态跳转、工具调用都记录成可追踪的轨迹，让你可视化回放、定位哪一步出了问题。
• 生产级部署：有状态、长运行的智能体对基础设施要求很高——要持久化、要扩缩容、要处理并发会话。LangSmith Deployment 平台就是为这类负载设计的，让你不用自己造一套状态存储和调度系统。

典型适用场景

把这些能力组合起来，LangGraph 适合的场景就很清晰了。第一类是需要人审批的业务流程：比如报销审批、合同审核、对外发信前的确认——图在关键边上中断，等人看完状态再继续。第二类是长链路、易失败的自动化任务：比如要抓十几个网页、查多个数据库、再汇总成报告的研究智能体，中途任何一步失败都能从检查点续跑，而不是整条重来。第三类是需要跨会话记忆的助手：它记得你上次的偏好、你做过的决定，下一次接着聊，而不是每轮对话都从零开始。第四类是要上线给真实用户用的生产智能体：需要可观测、可评估、可水平扩展，这正是 LangSmith 全家桶补上的一环。反过来，如果你只是想做一个"单轮问答"或者"固定几条链调用"的小工具，README 也明说了可以直接上更高层的 Deep Agents，不必从图编排开始。

七、设计灵感与致谢

README 在致谢部分说明：LangGraph 受 Pregel 和 Apache Beam 启发；它的公开接口设计参考了 NetworkX。LangGraph 由 LangChain Inc 开发（也就是 LangChain 的作者团队），但可以脱离 LangChain 单独使用。这一点很重要：它不是 LangChain 的附庸，而是一个独立的低层编排库，你完全可以只用它来组织自己的图状态机。理解这三个灵感来源，有助于理解它为什么长这样：Pregel 和 Beam 给了"图上消息传递 + 检查点"的执行模型，NetworkX 给了开发者熟悉的图操作接口。

八、FAQ（常见问题）

Q1：LangGraph 和 LangChain 是什么关系？ A：LangGraph 由 LangChain Inc 开发，可以和 LangChain 全家桶无缝配合；但它本身是独立的低层编排库，可以不装 LangChain 直接使用。

Q2：它适合快速搭一个 demo 吗？ A：README 建议如果只是想快速搭智能体，可以用基于 LangGraph 的更高层包 Deep Agents；LangGraph 本身定位低层编排，给你更多控制权但需要自己组织图结构。

Q3：怎么安装？ A：Python 用 pip install -U langgraph；JS/TS 用对应的 LangGraph.js 库。

Q4：长运行、有状态具体指什么？ A：指智能体可以跨长时间运行、跨会话保留状态；崩溃后从断点自动恢复（持久化执行），中间可以插入人工审批（人在回路），并有短期+长期记忆。

Q5：部署和调试用什么？ A：README 推荐用 LangSmith 做可观测与评估，用 LangSmith Deployment 平台部署和扩展有状态智能体，并在 LangSmith Studio 里可视化迭代。

Q6：为什么说它"低层"？和直接写循环有什么区别？ A：低层意味着它不给你预设"智能体该怎么思考"，而是给你节点、边、状态、检查点这些原语。你可以把它理解成一个"带状态持久化和中断能力的图执行引擎"，比手写 while 循环加字典存状态更工程化，又比开箱即用的框架更灵活。

Q7：Klarna、Replit、Elastic 这类公司为什么用它？ A：README 点名这些公司是因为它们要把智能体跑在生产里：要处理真实用户的长会话、要在出错时可恢复、要在敏感操作前加人工审批、要能监控每一步。这些正是 LangGraph 五大能力覆盖的场景。

Q8：我是 JS/TS 技术栈，能用吗？ A：可以。README 明确指向 LangGraph.js 仓库和对应的 JS 文档，能力与 Python 版对齐。

九、跳转链接

• 项目仓库：langchain-ai/langgraph
• 官网：langchain.com/langgraph
• Python 文档：overview
• API 参考：reference.langchain.com
• 快速开始：Quickstart
• Deep Agents：Deep Agents
• LangGraph.js：langchain-ai/langgraphjs
• LangSmith：langchain.com/langsmith
• 社区论坛：forum.langchain.com
• 免费课程：LangChain Academy