先判断是否真的需要状态图
本章目标
理解 LangGraph 解决的工程问题，并明确它与普通函数、ReAct 循环和 LangChain Agent 的边界。
ReAct 不是错误，隐式控制流才是风险
ReAct 把推理、行动和观察放入循环。简单工具 Agent 用几十行代码即可完成，不需要为了“图”而使用图。
当需求加入以下任意两三项时，手写循环会迅速承担状态机职责：
- 条件分支和返工循环。
- 多个外部查询并行执行。
- 人工审批和长时间等待。
- 进程重启后的恢复。
- 多个专业 Worker 的职责隔离。
- 每一步的耗时、成本与输入输出审计。
ReAct 并不天然只能串行，也不天然无状态。问题在于常见实现把状态、路由、重试和副作用都藏在一个 while 中，后续很难独立测试和恢复。
LangGraph 的三个核心构件
- State：一次运行的共享数据契约。
- Node：读取 State，执行纯计算或副作用，返回局部更新。
- Edge：决定下一步，支持固定、条件、循环和并行路径。
flowchart LR
START --> classify[意图识别]
classify -->|业务问题| fanout[并行分发]
classify -->|其他问题| manual[人工队列]
fanout --> kb[知识库]
fanout --> order[订单系统]
kb --> proposal[方案子图]
order --> proposal
proposal --> approval[人工审批]
approval -->|通过| execute[幂等执行]
approval -->|拒绝| END
execute -->|暂时失败| execute
execute -->|成功或耗尽| END
适用边界
| 场景 | 推荐方案 |
|---|---|
| 两三个固定步骤、无恢复要求 | 普通函数或 Runnable |
| 标准工具调用 Agent | 先评估 LangChain create_agent |
| 分支、循环、并行、审批和恢复并存 | StateGraph |
| 核心账务事务 | 数据库事务负责一致性，LangGraph 只负责协调 |
先做工作流复杂度盘点
决定引入状态图之前，先回答下面五个问题。只有“是”的数量逐渐增多，图编排的收益才会超过认知成本。
| 问题 | 如果回答“是”意味着什么 |
|---|---|
| 是否存在两个以上业务分支 | 需要显式路由和分支测试 |
| 是否需要暂停数分钟甚至数天 | 需要 Checkpointer，而不是常驻协程 |
| 是否有必须等待全部完成的并行任务 | 需要 join 语义和状态合并规则 |
| 是否会执行退款、发券、发消息等副作用 | 需要审批点、幂等键和审计记录 |
| 是否要求进程重启后继续 | 需要稳定 thread_id 和持久存储 |
一个只有“分类—回答”两步的问答接口，普通函数通常更清晰。一个包含订单查询、政策检索、人工审批、退款执行和失败转人工的流程，继续堆叠 if、while 和后台任务，最终也会形成一个没有名字、无法观察的状态机。
不要把业务一致性交给图
LangGraph 决定“下一步调用哪个能力”，不负责替代数据库事务。退款节点即使只被图调用一次，也可能因为网络超时出现“服务端已成功、客户端未收到响应”的不确定状态。解决办法是下游服务接受稳定幂等键，并能查询最终结果，而不是相信内存中的 attempts。
本教程采用以下职责划分：
- 图：路由、等待、恢复、重试预算和人工介入。
- 业务数据库：审批单、退款单、唯一约束和审计事实。
- 外部服务：在自己的事务边界内保证幂等执行。
- API 网关：认证、租户识别、限流和请求大小控制。
本章验收
- 为自己的一个业务流程输出状态字段表、节点与边图。
- 为每个循环写出成功条件、失败条件和最大预算。
- 列出全部外部副作用及其幂等键和最终一致性责任方。
- 能解释为什么该流程值得使用状态图，而不是普通函数。
本章没有代码作业。如果无法指出哪个系统对副作用的最终一致性负责，就不应进入编码阶段。