LangGraph 入门:用状态、节点和连线构建工作流

一段任务只有“接收输入 → 调用函数 → 返回结果”时,用普通异步函数就很好理解。需求一旦变成“按类型走不同处理器”“等两个步骤完成再汇总”“检查不通过就修改”,需要关心的就不只是某个函数,而是整个执行过程。

例如,一个客服工具要先判断咨询类型,再分别准备退款、开票或普通问题的回复。后来又增加了查询订单、检查回复、交给人工确认等步骤。此时我们需要回答:当前有哪些数据?下一步为什么执行?失败后会重复哪些操作?

LangGraph 用状态、节点和边描述这类任务。本文从一个不依赖模型的工单分流案例开始,沿着一次运行解释它的工作方式,再讨论并发、循环和恢复。这里侧重原理与实现步骤,不展开具体项目的服务端代码。

一、先区分流程定义和运行状态

可以先把工作流分成两个对象:流程定义描述允许经过哪些步骤,运行状态记录某一次执行已经得到什么。

同一份工单分流定义,可以处理很多条咨询。第一条咨询走退款分支,第二条走开票分支,它们复用的是结构,各自的输入和结果仍需要隔离。以后接入检查点时,同一线程内的多次调用还可以延续状态,但这是需要明确配置的行为。

几个常见术语可以这样对应:

概念 负责什么 工单案例中的例子
State 保存后续步骤需要读取的数据 咨询内容、类别、回复草稿
Node 读取状态,完成一步处理并返回更新 分类、准备开票回复
Edge 表达后续节点的执行关系 分类完成后选择处理分支
Reducer 决定一个状态字段怎样接收更新 将新的处理记录追加到轨迹
Compile 把状态与节点关系组织成可执行的图 构建可反复调用的分流流程
Invoke 向图提交输入并取得执行结果 处理“请开电子发票”这次请求

START 和 END 是图的入口与结束标记,不需要各自实现一个业务处理函数。LangGraph 的节点既能调用模型,也能做普通计算或访问已有服务,详见官方概览。

状态也不必包含一切。咨询内容和分类结果属于业务数据;模型客户端、数据库连接等运行依赖,通常通过上下文或依赖注入提供。这样需要持久化的内容更清楚,也更容易单独检查节点行为。

二、用一个工单分流器说明路由

为了先观察控制流程,假设分类只使用明确的关键词规则:

  1. 包含“退款”,选择退款分支。
  2. 否则,包含“发票”,选择开票分支。
  3. 其余进入普通咨询分支。

图的结构如下。三个处理分支互斥,一次只选择其中一个:

工单分流流程:咨询先经过规则分类,再选择退款、开票或普通咨询中的一个分支,最后整理回复并结束

输入 按本例规则选择的分支 回复的目的
我要申请退款 退款 提示补充用于核对的信息
请开电子发票 开票 提示填写开票信息
课程在哪里看 普通咨询 引导补充问题详情
退款并补开发票 退款 按已经声明的优先级处理

这是一份教学用的规则推演,不是客服意图识别的完整方案。比如“不要退款,我只是问发票”也包含“退款”,仍会命中第一条规则。LangGraph 会按照定义调度,无法替分类规则理解否定含义。

这个局限反而有助于分清职责:分类是否正确,是分类节点的质量;分类之后是否进入约定分支,是图的控制逻辑。 将来把关键词分类替换成模型分类时,只要仍然输出约定的类别,后面的处理节点就可以继续复用。

模型分类还应校验结果是否属于允许的类别。遇到无法判断、多个意图或缺少信息时,可以增加“需要澄清”分支,而不是把所有异常都当作普通问题。

三、沿着一次运行观察状态变化

以“请开电子发票”为例,一开始只有咨询内容。分类节点产生类别,开票节点准备回复,最后的节点整理面向页面的结果。

执行位置 本步读取 本步写入 应继续保留的数据
接收输入 用户咨询 原始输入 原始输入
分类完成 原始输入 类别:开票 原始输入、类别
开票处理完成 类别及需要的业务信息 回复草稿 原始输入、类别、回复草稿
整理结果完成 类别、回复草稿 最终展示结果 本次运行所需的完整结果

节点通常返回自己负责的字段更新。例如,开票节点只更新回复内容,不需要把原始输入和类别再复制一遍。没有出现在更新里的其他字段,不会仅仅因为本节点未返回它们就被删除。

这样做能让数据职责更明确:查看某个字段的写入者,就知道应该检查哪个节点。把整份状态在每个节点里展开后返回,容易让节点无意中再次提交过时字段,在后续并行改造时尤其难排查。

节点最好也不要通过直接修改传入对象表达更新。返回明确的增量,让图运行时按字段规则处理,才能把更新过程和执行过程对应起来。状态定义与更新文档介绍了这一机制。

设计一个字段时,可以先确定三个问题:谁写它,谁读它,是否允许多次写入。比如,原始咨询只在入口写入;回复草稿可以在修改环节被替换;处理轨迹则可以持续追加。它们都在 State 中,更新方式却不相同。

四、Reducer 决定更新怎样合并

Reducer 可以理解成一个字段的更新规则:拿到已有值和本次增量,计算这个字段接下来的值。

常见策略有以下几种:

字段 可选择的更新策略 实现时需要明确的约束
当前分类 用新分类替换旧分类 同一阶段由谁负责分类
回复草稿 替换为本轮修改结果 哪一版是当前有效版本
处理轨迹 追加新的步骤记录 节点只能提交本次新增记录
各节点结果 按节点 ID 合并 不同节点是否会写同一个键

假设轨迹已经记录“分类”,开票节点只提交“开票处理”,合并后得到“分类 → 开票处理”。如果节点先把旧轨迹复制过来,再追加本次记录,并把整个数组提交给追加型 reducer,旧记录就会重复出现。

对象合并也要注意层级。按节点 ID 浅合并结果,可以同时保留分类结果和回复结果;但同一个 ID 再次写入时,通常会替换该键对应的值,不会自动递归合并内部字段。是否保留历史版本,应在数据结构中另行设计。

并发更新不能依赖“最后返回的请求获胜”

假设增加两个独立节点,一个查订单,一个查用户资料。如果它们都写一个名为 result 的普通字段,就需要回答两份结果究竟怎样共存。

对使用默认单值通道的字段,同一调度步内收到多个更新会产生并发更新问题。可以让两个节点分别写自己的字段,也可以为结果集合设计 reducer。不能仅靠请求返回的先后顺序,猜测哪个结果会留下。官方的并发状态更新错误说明讨论了这种情况。

对于不同键的合并,顺序通常不影响内容;对于同一键的覆盖或数组追加,顺序可能影响业务含义。如果最终页面需要稳定排序,应携带步骤编号等明确依据,在展示或汇总时排序,而不是把并发完成顺序当作业务顺序。

五、连线不只是箭头:三种语义要分开

状态解决“有什么数据”,连线解决“接下来执行什么”。有了正确的 reducer,并不代表节点一定会在正确的时间运行。

固定顺序:上一步完成后进入下一步

如果开票处理完成后总要整理回复,就可以使用固定边。这里的前提是,整理节点依赖的数据已经由前面的步骤产生。

条件分支:根据状态选择路径

分类节点先产生类别,路由逻辑再读取类别,选出退款、开票或普通咨询分支。路由函数的工作是选择下一步,业务字段的更新由对应节点完成,会更容易理解。

也不要同时给分类节点添加一条固定业务出边,再期待条件边自动屏蔽它。固定路径与条件路径可能都会触发,必须按实际需要设计。

全部汇合:等所有必需的支路完成

假设某项咨询需要同时查询订单和核对资料,然后统一形成回复。这时两个支路都应该执行,汇总节点需要等待两边都完成。数组形式的 addEdge 可以表达等待指定前置节点全部完成的关系。

它和本篇最初的三选一分流不同:

场景 哪些分支会执行 后续节点的等待条件
退款、开票、普通咨询三选一 只执行选中的一个 选中的分支完成
订单查询与资料核对 两个都执行 两个必需结果都已产生
根据条件选择若干支路 本次选中的集合 等待本次实际需要的结果集合

如果让最初的“整理回复”同时等待退款、开票和普通咨询三个节点,它就无法被正常触发,因为两个未选中的节点根本不会执行。这不一定报错,图可能结束而缺少期望的最终结果,所以验收时还要检查最终输出是否存在。

不同长度支路分别连接到汇总节点,也不等价于显式的全部等待。官方的顺序、分支与循环文档对这些调度差异有专门说明。实际实现应先写清等待条件,再选择相应 API。

六、循环需要业务退出条件

工单回复生成后,可能需要检查是否缺少必要信息。如果不合格,就带着反馈进入修改步骤,再次检查。这种过程可以表达为循环。

循环状态至少要保存当前草稿、检查结果、修改意见和已修改次数。业务规则可以约定最多修改两轮;达到次数上限仍不通过时,转入人工处理或返回待完善草稿。

这里有三个不同的限制:

  • 业务次数上限:控制“最多修改几轮”,决定达到上限后的产品行为。
  • 调度步数上限:控制图最多推进多少个 super-step,防止异常路径持续执行。
  • 时间预算:控制一次调用或整项任务最多等待多久。

recursionLimit 限制的是图的调度步数,不是 JavaScript 函数递归深度,也不能简单看作节点数量。同一步可以有多个并行节点,一个循环又可能跨越多个调度步。相关定义见 Graph API。

网络重试与业务循环也应分开。请求因为临时网络问题失败,可以在节点边界采用有限重试;草稿已经生成但质量不合格,则需要把反馈交给修改环节。两者的原因、输入和可能重复的操作都不同。

七、持久化与人工确认怎样接入

到目前为止,状态只说明图在运行时怎样传递数据。要支持“先暂停,明天确认后继续”,还需要保存和恢复执行进度。

运行日志、检查点、长期数据各有什么用途

数据 主要回答什么问题 工单场景中的例子
运行日志 发生了什么,哪里慢或失败 分类耗时、错误信息
Checkpoint 这个线程保存了怎样的图执行状态 待确认的草稿及恢复所需信息
长期业务数据或 Store 多次任务之间需要复用什么 用户偏好、长期知识

自托管 LangGraph 时,需要配置 checkpointer,再使用线程标识关联调用。线程标识既用于定位状态,也意味着应用需要检查谁可以读取或恢复这个线程。内存实现适合学习;跨进程重启恢复需要持久化存储。官方持久化文档区分了检查点与跨线程数据的用途。

恢复不是在原来的代码行原地继续

人工确认可以分成“生成草稿 → 暂停并展示 → 接收确认 → 继续处理”。调用方要把确认内容与正确线程对应起来,恢复后再校验确认结果。

使用 interrupt 时有一个重要细节:恢复会重新进入包含中断的节点,中断之前的普通代码可能再次执行。因此,在暂停前直接发送通知或提交外部任务,可能产生重复副作用。中断文档明确说明了这一恢复规则。

更容易管理的设计,是把可独立确认的步骤拆开,并为外部操作准备稳定的幂等标识和结果查询方式。即使有检查点,也不能假定外部系统的操作天然只会发生一次。

“取消”和“暂停等待确认”也应区分。取消表示终止等待或请求停止;暂停则需要保留可恢复状态和明确的恢复入口。页面上的一个停止按钮,不会自动实现人工审批流程。

八、实现时先验证数据,再增加智能

可以按下面的顺序搭建第一份图:

  1. 画出路径。 明确入口、正常结果、异常结果和结束位置。
  2. 定义状态。 列出每个字段的写入者、读取者与更新策略。
  3. 实现普通节点。 先用固定规则和确定结果检查数据传递。
  4. 连接并编译。 检查路由是否覆盖可能的类别,汇合条件是否正确。
  5. 观察一次运行。 对照输入、经过的节点和最终结果,定位每次更新。
  6. 逐步增加模型、并发或恢复。 每次只改变需要的部分,并补上对应的失败场景。

编译成功不代表业务规则正确。对于本篇案例,可以用“退款”“发票”“普通问题”“同时包含两个关键词”“否定退款”等输入,分别检查路由是否符合已经声明的规则。再补充空输入、未知类别、节点失败和最终结果缺失的情况。

这些是可用于验收的推演用例,没有替代真实模型评估或线上运行验证。以后接入模型分类时,还需要检查误分类和不确定输入,不能只看流程有没有执行到结束。

如果希望把流程放到可编辑画布里,可以看看 GitHub 上的 **LangChainWeb**。它提供前端编辑与结果展示的实现,适合观察节点配置、连线和运行反馈如何组织;图执行与模型服务需要另行接入。欢迎 Star,也欢迎交流可视化工作流的实现思路。

系列文章可以按需求继续阅读:

作者

hujinbin

发布于

2026-06-14

更新于

2026-11-15

许可协议

评论