LangGraph怎么用？从状态定义到节点路由与断点恢复的入门指南

先理解LangGraph的执行模型

LangGraph适合把一个有多个步骤、分支或循环的任务表示成状态图。图中的状态是节点之间共享的数据，节点负责读取当前状态并返回更新，边决定下一步执行哪个节点。这样，业务流程不再只是函数的线性调用，而是可以观察每一步状态如何变化。

状态通常先用一个结构定义，例如包含topic、draft、passed和attempts等字段。节点不必返回完整状态，只需返回本次要更新的字段。字段如何合并由reducer决定：未配置reducer的字段通常会被新值替换；需要追加列表、合并消息或执行自定义合并时，应为对应字段声明合适的reducer。这个区别很重要，否则重试节点可能意外覆盖之前积累的信息。

图的入口和出口可以用START与END表示。普通边适合固定顺序，条件边则根据当前状态选择下一步。完成节点注册和连线后，调用compile得到可执行图，再通过invoke等接口传入初始状态。

搭建一个有限循环工作流

下面用一个小型流程说明执行机制：先生成草稿，再进行规则检查；如果不合格，就返回修改节点，最多重复三次，合格则结束。

1. 定义状态：准备topic、draft、passed、issues和attempts字段。attempts用于记录已经生成或修改的次数，passed表示规则检查结果，issues保存可操作的修改意见。
2. 创建图：使用StateGraph(State)创建构建器，然后注册draft、check等节点。draft节点根据topic生成或修改draft，并返回新的draft与attempts；check节点读取draft，执行长度、格式或关键词等规则，返回passed和issues。
3. 设置固定连接：把START连接到draft，把draft连接到check。这样每次进入流程都会先产生内容，再进入检查。
4. 设置条件路由：定义route函数读取passed和attempts。passed为真时返回finish；未通过且attempts小于3时返回revise；达到上限仍未通过时返回stop。使用add_conditional_edges把finish和stop映射到END，把revise映射回draft。
5. 编译和调用：调用compile()生成可执行图，再用初始状态调用invoke。例如初始状态只需提供topic、空的draft、默认的passed和attempts等字段，具体缺省值应与状态定义保持一致。

这里有两个终止条件：规则通过，或者修改次数达到上限。前者是业务条件，后者是安全边界。即使业务代码出现误判或路由错误，也不应让图无限循环。调用时还可以在配置中设置recursion_limit作为执行步数保护，但它不能替代业务上的attempts判断；前者是运行保护，后者是流程规则。

条件路由容易出错的地方

路由函数返回的值必须和条件边映射中的键一致。如果返回了未注册的结果，图无法按预期找到下一节点。建议把路由结果限制为少量明确的分支，并为失败、超限等情况保留可观察的状态字段，而不是直接丢弃原因。

修改节点也不一定要重新生成全部内容。它可以读取issues，只返回修订后的draft和递增后的attempts。节点之间只传递状态更新，能够减少耦合，也方便在检查点中查看每一步发生了什么。

用checkpointer保存和恢复状态

如果希望流程在中断后继续，需要在编译图时传入官方支持的checkpointer实例。checkpointer负责在图的执行步骤之间保存状态快照；thread_id则是查找某条执行线程快照的重要标识。调用时通常把thread_id放在配置的configurable部分，例如使用一个稳定的草稿编号，而不是每次随机生成。

同一个thread_id用于同一条工作流时，系统可以定位此前保存的状态。在人工审批、interrupt或异常恢复场景中，应按照当前官方接口提供恢复参数，并使用相同thread_id继续执行；更换thread_id通常意味着开始查找另一条执行线程。checkpointer保存的是图状态和执行上下文，不等于替外部系统完成事务回滚。

外部操作必须自行保证幂等

假设某个节点在数据库写入、发送邮件或调用支付接口后进程崩溃，检查点可能只记录到操作前或操作后的某一侧。恢复时，该节点有机会再次执行，单靠保存状态不能保证外部副作用只发生一次。

涉及外部写入时，应使用业务幂等键、唯一约束、upsert、去重记录或可查询的操作状态。节点恢复前先根据幂等键确认结果，能够避免重复创建订单或重复发送通知。开发阶段可以先使用简单的内存检查点观察状态变化，生产方案则应根据当前LangGraph官方文档选择适合的持久化实现，并核对对应版本的接口和导入路径。

掌握状态定义、节点返回更新、固定边、条件边和检查点后，就能把更复杂的流程拆成可观察的小步骤。真正上线前，还应运行验证路由、超限、恢复和外部失败等场景，不能把未经验证的示例直接当作生产实现。