LangGraph工作流编排框架

LangGraph 是 LangChain 团队维护的开源编排框架与运行时，用于将有状态的工作流或智能体流程表示为图。它的基本构件是共享状态、节点和边：节点执行计算，边决定后续路径。流程可以包含普通程序逻辑、模型调用和外部工具，也可以在条件分支、循环、暂停和恢复之间切换。LangGraph 不要求应用必须使用 LangChain 的模型或工具抽象。

LangGraph 1.0 于 2025 年 10 月 22 日宣布发布，作为该项目首个稳定大版本。本文以截至 2026 年 10 月 3 日查阅的开源 Python 1.x 文档为依据，主要解释 StateGraph 与图执行概念。不同语言包、补丁版本和托管服务的接口可能不同；流式 API 的版本差异会单独标出。

LangGraph 面向需要自行组织执行路径的开发者。与提供常见模型—工具循环等高层抽象的 LangChain 相比，LangGraph 处在更底层：开发者描述任务由哪些步骤组成、各步骤读写什么数据，以及满足什么条件时跳转或结束。它既能编排智能体，也能编排确定性程序，因此“图”并不意味着每个节点都由大模型驱动。

例如，客服流程可以先解析问题，再检索资料、起草答复，最后依规则提交审核。解析和检索可以是普通代码，起草步骤可以调用模型，审核步骤可以暂停等候人工输入。LangGraph 提供的重点是控制流和运行时能力；业务规则、模型选择、提示词、外部系统权限和最终答复质量仍由应用负责。若需求只是标准的工具调用循环，LangChain 的高层 agent 接口可能更直接；其官方文档说明，LangChain agent 建立在 LangGraph 运行时之上。

官方资料：LangGraph 概览；LangChain 与 LangGraph 1.0 发布说明

在常用的 StateGraph API 中，状态是流程当前的数据快照，通常由开发者定义的 schema 描述。状态可保存输入、检索结果、审批标记或对话消息等。每个节点接收当前状态，执行一段同步或异步函数，并返回部分更新；它不必重写整个状态。每个状态字段可以配置 reducer，说明新值是覆盖旧值，还是与旧值合并。例如，列表字段可累积多步结果，而普通字段通常以最新更新替换旧值。

节点既可以调用模型，也可以查询数据库、调用 API 或执行常规计算。边定义控制流：固定边连接必经步骤，条件边依据状态选择目的节点；有向路径可以回环，也可以让多个后续节点在同一执行步并行运行。START 表示图的入口，END 表示终点。节点内也可以用路由机制组合更新状态和指定下一节点。图建好后需调用 compile；编译阶段会检查基本结构，并可设置检查点等运行选项。

例如，一条问题处理流程可把原始问题、分类结果、检索证据、草稿和审核状态设为不同字段：分类节点只写类别，条件边将账单问题送往账务步骤、一般问题送往检索步骤，撰写节点再汇合证据并产出草稿。该字段安排只是设计示例，LangGraph 不规定业务 schema；哪些内容要保存、哪些可按需重算，由应用决定。

这些抽象不会自动把业务意图变成正确流程。分支条件、循环退出条件、字段合并方式都需要设计和测试；同一步并行节点若更新同一字段，也要选好 reducer，避免数据冲突或意外覆盖。

官方资料：Graph API 概览

LangGraph 将已编译图作为可执行流程。应用把初始状态交给图运行，并可选择一次性取得结果，或通过流式接口逐步读取更新。其图执行模型受 Pregel 启发，按离散的 super-step（可理解为一轮图节点执行）推进：某一轮中被调度的节点处理收到的状态并产生更新，后续节点据此进入下一轮；适合并行执行的节点可以处在同一轮。流程在没有待运行节点、且没有待传递消息时结束。

图定义的路由是显式的，但节点内部仍可能包含具有不确定性的操作。模型输出会随模型、提示词和调用条件变化；网络服务也可能超时或返回错误。因此，图可以让步骤和路径更容易被描述、观察与控制，却不会自动保证每次运行结果相同、符合业务规则或成功完成。调用模型或工具的重试策略、超时、校验和错误分支应按应用风险设计。

官方资料：Graph API 概览；LangGraph 设计说明：从第一性原理构建运行时

检查点（checkpoint）是图状态在执行过程中的快照。配置 checkpointer 后，LangGraph 可将检查点按 thread ID 组织起来，让一次流程的状态能够在后续运行中继续使用。官方文档将其用于对话连续性、故障恢复、人工审核和回看历史执行。检查点通常对应 super-step 边界；它不是对数据库、邮件或其他外部副作用的事务性回滚。

检查点和长期存储也不是同一概念：checkpointer 保存某个 thread 的图状态；store 则保存由应用定义、可跨 thread 查询的数据。内存型 saver 适合实验，但进程重启会丢失其数据。需要跨重启保存状态时，应选持久化后端，并考虑备份、访问控制、加密、保留期限、存储增长及敏感信息管理。官方文档列出同步、异步和仅在退出时写入等持久化模式，分别在写入时机、故障恢复范围与执行开销之间取舍。

持久化也不等于“恰好执行一次”。若节点执行到一半后暂停或重试，恢复时该节点可能从函数开头再次运行；已发生的外部副作用可能重复。发送付款指令、创建工单或写入数据库等操作应使用幂等键、upsert 或先读后写等保护，并在实际部署中验证失败和恢复场景。

持久化策略还会影响失败恢复窗口。官方列出的 exit 模式只在运行退出时写入中间状态；若进程在运行中崩溃，尚未写入的状态无法从该区间恢复；async 模式在后续步骤运行时异步写入，开销较低但进程崩溃时可能来不及写完；sync 模式在进入下一步前同步写入，持久性更强但会增加等待开销。具体取舍应结合可接受的数据丢失范围和运行时延要求评估。

官方资料：Persistence 概览；Checkpointers：检查点、线程与持久化模式

流式接口可在流程运行时暴露不同类型的信息，例如状态快照、节点更新、模型消息片段或应用自定义事件。调用方可以据此显示进度或逐步处理结果，但具体事件能否显示为用户界面上的文本，取决于节点、模型提供方、传输层和前端如何实现；“框架支持流式”不代表每个模型调用都会产出可见 token 流，也不代表用户看到的就是已经校验的最终结果。

人工介入可通过 interrupt() 在节点执行处暂停，并把可序列化的中断内容交给调用方。需要检查点与同一个 thread ID 才能保存并恢复流程；应用随后可用恢复输入继续执行。文档特别提醒，恢复会从含有 interrupt 的节点开头重跑，因此中断前的代码可能再执行。另一个容易忽略的边界是，图中称为“内部”或 private 的状态通道不会自动从 values 流中隐藏；若状态含有敏感字段，应用需限制输出通道或过滤事件。审批页面、操作者身份认证、权限校验、通知时限和是否允许执行危险工具，都是应用或部署系统要落实的控制，不能只靠出现一个 interrupt 调用来保证。

接口也在演进：当前 Python 文档称统一的 stream(..., version="v2") 输出格式需要 LangGraph 1.1 或更高版本；事件流 API 则是 1.2 引入的新接口。它们是特定版本的 API 事实，不应误读成所有 1.x 项目都能直接使用。

官方资料：Streaming；Interrupts

当流程需要明确步骤和分支、混合确定性代码与模型调用、反复循环、等待人工审核，或按会话保存运行状态时，图式编排可能便于表达和维护。若流程短而固定，直接写普通函数或使用更高层 agent 抽象，可能更简单。图的节点划分也有取舍：拆得细能增加观察和恢复的边界，但会扩大编排结构与持久化开销；粒度过粗则可能让调试和失败恢复更难。实际设计时，可把需要独立重试、审核、观察或复用的环节分开，把紧密耦合且总是一起失败/恢复的步骤留在同一节点；如在一个节点中执行多个外部操作，则须关注恢复时整段节点重跑的影响。上线前还应测试正常路径、条件分支、循环终止、超时和恢复路径，并用重复提交等方式检验幂等策略。评估对象应包括整条应用流程，而不只是图能否成功编译。

部署时要区分开源框架和托管服务。LangGraph 可单独使用；LangSmith Deployment 是一类部署选项，官方文档也列出混合、独立服务器和自托管等模式。选型取决于团队的基础设施、运维能力和控制要求；使用开源图 API 不意味着必须使用某个托管服务。无论选何种运行方式，生产准备还需要应用自身完成密钥和权限管理、数据治理、监控与评估、并发和资源限制、后端容量规划及故障演练。官方所称的持久化、流式或人机协同能力描述的是框架接口和机制，并不构成对可用性、模型正确性、合规性、吞吐量或业务结果的保证。

官方资料：LangGraph 概览；官方部署选项