LangGraph 入门:用状态、节点和连线构建工作流
一段任务只有“接收输入 → 调用函数 → 返回结果”时,用普通异步函数就很好理解。需求一旦变成“按类型走不同处理器”“等两个步骤完成再汇总”“检查不通过就修改”,需要关心的就不只是某个函数,而是整个执行过程。
例如,一个客服工具要先判断咨询类型,再分别准备退款、开票或普通问题的回复。后来又增加了查询订单、检查回复、交给人工确认等步骤。此时我们需要回答:当前有哪些数据?下一步为什么执行?失败后会重复哪些操作?
LangGraph 用状态、节点和边描述这类任务。本文从一个不依赖模型的工单分流案例开始,沿着一次运行解释它的工作方式,再讨论并发、循环和恢复。这里侧重原理与实现步骤,不展开具体项目的服务端代码。
一、先区分流程定义和运行状态
可以先把工作流分成两个对象:流程定义描述允许经过哪些步骤,运行状态记录某一次执行已经得到什么。
同一份工单分流定义,可以处理很多条咨询。第一条咨询走退款分支,第二条走开票分支,它们复用的是结构,各自的输入和结果仍需要隔离。以后接入检查点时,同一线程内的多次调用还可以延续状态,但这是需要明确配置的行为。
几个常见术语可以这样对应:
| 概念 | 负责什么 | 工单案例中的例子 |
|---|---|---|
| State | 保存后续步骤需要读取的数据 | 咨询内容、类别、回复草稿 |
| Node | 读取状态,完成一步处理并返回更新 | 分类、准备开票回复 |
| Edge | 表达后续节点的执行关系 | 分类完成后选择处理分支 |
| Reducer | 决定一个状态字段怎样接收更新 | 将新的处理记录追加到轨迹 |
| Compile | 把状态与节点关系组织成可执行的图 | 构建可反复调用的分流流程 |
| Invoke | 向图提交输入并取得执行结果 | 处理“请开电子发票”这次请求 |
START 和 END 是图的入口与结束标记,不需要各自实现一个业务处理函数。LangGraph 的节点既能调用模型,也能做普通计算或访问已有服务,详见官方概览。
状态也不必包含一切。咨询内容和分类结果属于业务数据;模型客户端、数据库连接等运行依赖,通常通过上下文或依赖注入提供。这样需要持久化的内容更清楚,也更容易单独检查节点行为。
二、用一个工单分流器说明路由
为了先观察控制流程,假设分类只使用明确的关键词规则:
- 包含“退款”,选择退款分支。
- 否则,包含“发票”,选择开票分支。
- 其余进入普通咨询分支。
图的结构如下。三个处理分支互斥,一次只选择其中一个:
| 输入 | 按本例规则选择的分支 | 回复的目的 |
|---|---|---|
| 我要申请退款 | 退款 | 提示补充用于核对的信息 |
| 请开电子发票 | 开票 | 提示填写开票信息 |
| 课程在哪里看 | 普通咨询 | 引导补充问题详情 |
| 退款并补开发票 | 退款 | 按已经声明的优先级处理 |
这是一份教学用的规则推演,不是客服意图识别的完整方案。比如“不要退款,我只是问发票”也包含“退款”,仍会命中第一条规则。LangGraph 会按照定义调度,无法替分类规则理解否定含义。
这个局限反而有助于分清职责:分类是否正确,是分类节点的质量;分类之后是否进入约定分支,是图的控制逻辑。 将来把关键词分类替换成模型分类时,只要仍然输出约定的类别,后面的处理节点就可以继续复用。
模型分类还应校验结果是否属于允许的类别。遇到无法判断、多个意图或缺少信息时,可以增加“需要澄清”分支,而不是把所有异常都当作普通问题。
三、沿着一次运行观察状态变化
以“请开电子发票”为例,一开始只有咨询内容。分类节点产生类别,开票节点准备回复,最后的节点整理面向页面的结果。
| 执行位置 | 本步读取 | 本步写入 | 应继续保留的数据 |
|---|---|---|---|
| 接收输入 | 用户咨询 | 原始输入 | 原始输入 |
| 分类完成 | 原始输入 | 类别:开票 | 原始输入、类别 |
| 开票处理完成 | 类别及需要的业务信息 | 回复草稿 | 原始输入、类别、回复草稿 |
| 整理结果完成 | 类别、回复草稿 | 最终展示结果 | 本次运行所需的完整结果 |
节点通常返回自己负责的字段更新。例如,开票节点只更新回复内容,不需要把原始输入和类别再复制一遍。没有出现在更新里的其他字段,不会仅仅因为本节点未返回它们就被删除。
这样做能让数据职责更明确:查看某个字段的写入者,就知道应该检查哪个节点。把整份状态在每个节点里展开后返回,容易让节点无意中再次提交过时字段,在后续并行改造时尤其难排查。
节点最好也不要通过直接修改传入对象表达更新。返回明确的增量,让图运行时按字段规则处理,才能把更新过程和执行过程对应起来。状态定义与更新文档介绍了这一机制。
设计一个字段时,可以先确定三个问题:谁写它,谁读它,是否允许多次写入。比如,原始咨询只在入口写入;回复草稿可以在修改环节被替换;处理轨迹则可以持续追加。它们都在 State 中,更新方式却不相同。
四、Reducer 决定更新怎样合并
Reducer 可以理解成一个字段的更新规则:拿到已有值和本次增量,计算这个字段接下来的值。
常见策略有以下几种:
| 字段 | 可选择的更新策略 | 实现时需要明确的约束 |
|---|---|---|
| 当前分类 | 用新分类替换旧分类 | 同一阶段由谁负责分类 |
| 回复草稿 | 替换为本轮修改结果 | 哪一版是当前有效版本 |
| 处理轨迹 | 追加新的步骤记录 | 节点只能提交本次新增记录 |
| 各节点结果 | 按节点 ID 合并 | 不同节点是否会写同一个键 |
假设轨迹已经记录“分类”,开票节点只提交“开票处理”,合并后得到“分类 → 开票处理”。如果节点先把旧轨迹复制过来,再追加本次记录,并把整个数组提交给追加型 reducer,旧记录就会重复出现。
对象合并也要注意层级。按节点 ID 浅合并结果,可以同时保留分类结果和回复结果;但同一个 ID 再次写入时,通常会替换该键对应的值,不会自动递归合并内部字段。是否保留历史版本,应在数据结构中另行设计。
并发更新不能依赖“最后返回的请求获胜”
假设增加两个独立节点,一个查订单,一个查用户资料。如果它们都写一个名为 result 的普通字段,就需要回答两份结果究竟怎样共存。
对使用默认单值通道的字段,同一调度步内收到多个更新会产生并发更新问题。可以让两个节点分别写自己的字段,也可以为结果集合设计 reducer。不能仅靠请求返回的先后顺序,猜测哪个结果会留下。官方的并发状态更新错误说明讨论了这种情况。
对于不同键的合并,顺序通常不影响内容;对于同一键的覆盖或数组追加,顺序可能影响业务含义。如果最终页面需要稳定排序,应携带步骤编号等明确依据,在展示或汇总时排序,而不是把并发完成顺序当作业务顺序。
五、连线不只是箭头:三种语义要分开
状态解决“有什么数据”,连线解决“接下来执行什么”。有了正确的 reducer,并不代表节点一定会在正确的时间运行。
固定顺序:上一步完成后进入下一步
如果开票处理完成后总要整理回复,就可以使用固定边。这里的前提是,整理节点依赖的数据已经由前面的步骤产生。
条件分支:根据状态选择路径
分类节点先产生类别,路由逻辑再读取类别,选出退款、开票或普通咨询分支。路由函数的工作是选择下一步,业务字段的更新由对应节点完成,会更容易理解。
也不要同时给分类节点添加一条固定业务出边,再期待条件边自动屏蔽它。固定路径与条件路径可能都会触发,必须按实际需要设计。
全部汇合:等所有必需的支路完成
假设某项咨询需要同时查询订单和核对资料,然后统一形成回复。这时两个支路都应该执行,汇总节点需要等待两边都完成。数组形式的 addEdge 可以表达等待指定前置节点全部完成的关系。
它和本篇最初的三选一分流不同:
| 场景 | 哪些分支会执行 | 后续节点的等待条件 |
|---|---|---|
| 退款、开票、普通咨询三选一 | 只执行选中的一个 | 选中的分支完成 |
| 订单查询与资料核对 | 两个都执行 | 两个必需结果都已产生 |
| 根据条件选择若干支路 | 本次选中的集合 | 等待本次实际需要的结果集合 |
如果让最初的“整理回复”同时等待退款、开票和普通咨询三个节点,它就无法被正常触发,因为两个未选中的节点根本不会执行。这不一定报错,图可能结束而缺少期望的最终结果,所以验收时还要检查最终输出是否存在。
不同长度支路分别连接到汇总节点,也不等价于显式的全部等待。官方的顺序、分支与循环文档对这些调度差异有专门说明。实际实现应先写清等待条件,再选择相应 API。
六、循环需要业务退出条件
工单回复生成后,可能需要检查是否缺少必要信息。如果不合格,就带着反馈进入修改步骤,再次检查。这种过程可以表达为循环。
循环状态至少要保存当前草稿、检查结果、修改意见和已修改次数。业务规则可以约定最多修改两轮;达到次数上限仍不通过时,转入人工处理或返回待完善草稿。
这里有三个不同的限制:
- 业务次数上限:控制“最多修改几轮”,决定达到上限后的产品行为。
- 调度步数上限:控制图最多推进多少个 super-step,防止异常路径持续执行。
- 时间预算:控制一次调用或整项任务最多等待多久。
recursionLimit 限制的是图的调度步数,不是 JavaScript 函数递归深度,也不能简单看作节点数量。同一步可以有多个并行节点,一个循环又可能跨越多个调度步。相关定义见 Graph API。
网络重试与业务循环也应分开。请求因为临时网络问题失败,可以在节点边界采用有限重试;草稿已经生成但质量不合格,则需要把反馈交给修改环节。两者的原因、输入和可能重复的操作都不同。
七、持久化与人工确认怎样接入
到目前为止,状态只说明图在运行时怎样传递数据。要支持“先暂停,明天确认后继续”,还需要保存和恢复执行进度。
运行日志、检查点、长期数据各有什么用途
| 数据 | 主要回答什么问题 | 工单场景中的例子 |
|---|---|---|
| 运行日志 | 发生了什么,哪里慢或失败 | 分类耗时、错误信息 |
| Checkpoint | 这个线程保存了怎样的图执行状态 | 待确认的草稿及恢复所需信息 |
| 长期业务数据或 Store | 多次任务之间需要复用什么 | 用户偏好、长期知识 |
自托管 LangGraph 时,需要配置 checkpointer,再使用线程标识关联调用。线程标识既用于定位状态,也意味着应用需要检查谁可以读取或恢复这个线程。内存实现适合学习;跨进程重启恢复需要持久化存储。官方持久化文档区分了检查点与跨线程数据的用途。
恢复不是在原来的代码行原地继续
人工确认可以分成“生成草稿 → 暂停并展示 → 接收确认 → 继续处理”。调用方要把确认内容与正确线程对应起来,恢复后再校验确认结果。
使用 interrupt 时有一个重要细节:恢复会重新进入包含中断的节点,中断之前的普通代码可能再次执行。因此,在暂停前直接发送通知或提交外部任务,可能产生重复副作用。中断文档明确说明了这一恢复规则。
更容易管理的设计,是把可独立确认的步骤拆开,并为外部操作准备稳定的幂等标识和结果查询方式。即使有检查点,也不能假定外部系统的操作天然只会发生一次。
“取消”和“暂停等待确认”也应区分。取消表示终止等待或请求停止;暂停则需要保留可恢复状态和明确的恢复入口。页面上的一个停止按钮,不会自动实现人工审批流程。
八、实现时先验证数据,再增加智能
可以按下面的顺序搭建第一份图:
- 画出路径。 明确入口、正常结果、异常结果和结束位置。
- 定义状态。 列出每个字段的写入者、读取者与更新策略。
- 实现普通节点。 先用固定规则和确定结果检查数据传递。
- 连接并编译。 检查路由是否覆盖可能的类别,汇合条件是否正确。
- 观察一次运行。 对照输入、经过的节点和最终结果,定位每次更新。
- 逐步增加模型、并发或恢复。 每次只改变需要的部分,并补上对应的失败场景。
编译成功不代表业务规则正确。对于本篇案例,可以用“退款”“发票”“普通问题”“同时包含两个关键词”“否定退款”等输入,分别检查路由是否符合已经声明的规则。再补充空输入、未知类别、节点失败和最终结果缺失的情况。
这些是可用于验收的推演用例,没有替代真实模型评估或线上运行验证。以后接入模型分类时,还需要检查误分类和不确定输入,不能只看流程有没有执行到结束。
如果希望把流程放到可编辑画布里,可以看看 GitHub 上的 **LangChainWeb**。它提供前端编辑与结果展示的实现,适合观察节点配置、连线和运行反馈如何组织;图执行与模型服务需要另行接入。欢迎 Star,也欢迎交流可视化工作流的实现思路。
系列文章可以按需求继续阅读:
- 想理解模型调用内部的数据转换:LangChain JavaScript 入门。
- 想判断自己的任务需要哪层抽象:LangChain 和 LangGraph 如何选择。
- 想串起对话设计、画布编辑和运行过程:从对话生成到可编辑工作流。
LangGraph 入门:用状态、节点和连线构建工作流
https://hjb.leheavengame.com/2026/06/14/LangGraph-入门:用状态、节点和连线构建工作流/

