参考资料

• LangChain Agents
• LangGraph 文档

LangGraph（01） - LangGraph 入门

读完后，你应能完成以下任务：

• 绘制“LangGraph（01） - LangGraph 入门 / 直线链 vs 状态图”的关键对象与数据流，解释“差别就一个词：图能有环，链不能。”，并用源码位置、日志或 Trace 标注证据。
• 为“LangGraph（01） - LangGraph 入门 / 四个核心概念”设计正常与异常输入，验证“State 是一个字典，从头流到尾，每个节点往里读写。”，输出首个偏差位置与回归测试结果。
• 实现“LangGraph（01） - LangGraph 入门 / 条件边：图能分支和循环的关键”的最小代码或配置，检验“普通边（add_edge）是「A 执行完无条件去 B」。”，输出命令、结果与 Diff，并说明不适用边界。

核心知识清单

• State、Node、Edge 与 START/END
• Conditional Edge 与 Command 路由
• Checkpointer、thread_id 与状态恢复
• Interrupt 与 Human-in-the-loop
• Durable Execution、幂等节点与重放
• Streaming、错误分支与循环上限

一、与进阶篇的分工

本篇保留为 LangGraph 入门：重点讲 State、Node、Edge 和条件循环。进阶图编排请读 75《图编排引擎》和 76《Agentic RAG》，那里会把状态图用于多 Agent 和自我修正 RAG 闭环。

二、LangGraph 入门的真实应用场景

你的知识库 Agent 上线了，但有个问题：用户问「报销咋整」这种大白话，检索命中率很低，因为知识库里写的是「报销发票几天内提交」。

理想的处理是：检索不到 → 把问题改写成检索友好的形式 → 再检索一次。 注意这里有个「回头重试」的动作——检索失败后要绕回去重新检索。

这正是 LangChain 直线链的死穴。prompt | retrieve | llm 是一条单向流水线，数据只能往前流，没法「检索失败了再绕回检索」。要表达这种循环和分支，就需要把应用建模成一张图。这就是 LangGraph。

三、直线链 vs 状态图

LangChain（直线链）：
  retrieve → prompt → llm → END        数据只能往前，没法回头

LangGraph（状态图）：
                  ┌──── 命中 ────→ answer → END
  retrieve ──判断─┤
                  └─ 没命中 → rewrite ──┐
                       ↑                │
                       └────────────────┘   改写完绕回 retrieve（循环）

差别就一个词：图能有环，链不能。 Agent 的「想一步、做一步、看结果、不行再来一遍」本质就是循环，所以复杂 Agent 几乎都用图来建模。

四、四个核心概念

概念	是什么	对应 demo
State	贯穿全程的共享状态字典	state
Node	图上的节点，读 state 改 state	retrieve_node 等
Edge	边，决定节点执行完去哪	add_edge
Conditional Edge	条件边，按 state 决定去哪	add_conditional_edge

State 是一个字典，从头流到尾，每个节点往里读写。Node 是函数，签名统一是 (state) -> state：

五、条件边：图能分支和循环的关键

普通边（add_edge）是「A 执行完无条件去 B」。条件边（add_conditional_edge）是「A 执行完，由一个路由函数看 state 决定去哪」。这就是分支和循环的来源：

组装图的时候，rewrite 节点用一条普通边连回 retrieve，就形成了「检索-改写-再检索」的循环：

六、图引擎：驱动 state 在图上跑，并防死循环

图引擎做的事很简单：从入口节点开始，执行节点、看边、跳到下一个节点，直到 END。但有了环就有死循环风险，所以必须加步数上限兜底：

max_steps 不是可选项。条件边一旦逻辑写错（比如忘了 rewritten 标记），图就会在两个节点间无限横跳。这是用图最容易踩的坑。

七、工程上真正会踩的坑

• 条件边逻辑漏出口导致死循环。忘了标记「已改写过」，图就在 retrieve 和 rewrite 间无限横跳。每条循环边都要有明确的退出条件，且引擎层面用 max_steps 兜底。
• state 字段约定不清。多个节点读写同一个 state，谁写了什么字段没约定好，后面的节点读到意外的值。State 的结构要像接口一样定清楚。
• 该用链却上了图。固定流程（解析→检索→回答，不回头）用 LangChain 的链就够了，套图反而把简单逻辑复杂化。只有真需要循环/分支/回退时才上图。
• 图太大没法调试。节点一多，光看代码想不清数据怎么流。真实 LangGraph 配合 LangSmith 可视化 trace，自己实现的话至少把每个节点的 state 变化打出来（demo 里就这么做的）。

八、一句话面试答法

LangGraph 和 LangChain 什么区别，什么时候用图？ LangChain 的链是直线流水线，数据只能往前流；LangGraph 把应用建模成带状态的图，支持条件分支和循环。核心是 State（共享状态）、Node（读写 state 的节点）、Edge（决定去哪的边，分条件边和固定边）。固定流程用链就够，但 Agent 那种「做一步看结果不行再来一遍」的循环、或者「检索不到先改写再重试」的回退，必须用图。用图时一定要给循环边设退出条件、引擎层加步数上限防死循环。

九、动手实践：36 LangGraph 入门

用纯 Python 标准库实现 LangGraph 的核心：State（共享状态）、Node（节点）、Edge（边，含条件边）、Graph（图引擎）。用一个「检索不到就改写问题重试」的 ReAct 风格 Agent，演示直线链做不到的条件分支 + 循环。

9.1 在线运行

零依赖，纯标准库，离线可跑。不需要 pip install langgraph。

9.2 预期输出

=== 场景 1：问题直接命中（无需改写）===
  [retrieve] query='报销发票几天内提交' hit=True
  [answer] 根据资料：员工报销需在消费后 7 天内提交发票，超过 30 天不予受理。
最终答案：根据资料：员工报销需在消费后 7 天内提交发票，超过 30 天不予受理。

=== 场景 2：口语问题没命中 → 改写 → 再检索命中 ===
  [retrieve] query='报销咋整' hit=False
  [rewrite] '报销咋整' -> '报销发票几天内提交'
  [retrieve] query='报销发票几天内提交' hit=True
  [answer] 根据资料：员工报销需在消费后 7 天内提交发票，超过 30 天不予受理。
最终答案：根据资料：员工报销需在消费后 7 天内提交发票，超过 30 天不予受理。

场景 2 是重点：检索没命中 → 走条件边到 rewrite → rewrite 回到 retrieve（循环）→ 这次命中 → 回答。这是直线链（LangChain LCEL）做不到的。

9.3 代码 ↔ 概念对应

LangGraph 概念	本 demo 的 mini 实现
State（共享状态）	贯穿所有节点的 state 字典
Node（节点）	retrieve_node / rewrite_node / answer_node
Edge（固定边）	add_edge，如 rewrite -> retrieve
Conditional Edge（条件边）	add_conditional_edge + route_after_retrieve
循环	rewrite 的固定边回到 retrieve
图引擎驱动执行	StateGraph.invoke
END 终止	END 常量 + 防死循环 max_steps

9.4 真实 LangGraph 怎么用

这个 demo 是「代码版的 mini LangGraph」。真实项目里：

pip install langgraph

API 名字几乎一一对应。LangGraph 真正多给你的是：状态持久化（checkpoint）、人在回路（中断等人确认）、并行节点。但核心模型就是本 demo 这套「状态在图上按条件边流动」。

9.5 动手改

• 把 route_after_retrieve 里的「改写过就回答」逻辑去掉，再跑场景 2 的一个永远命不中的问题，观察 max_steps 防死循环兜底。
• 加一个「人工确认」节点，在 answer 前插入，体会人在回路。
• 给 REWRITE_MAP 加更多改写规则，让改写节点更聪明。

9.6 可运行源码：LangGraph 入门

main.py

十、总结

• 与进阶篇的分工：进阶图编排请读 75《图编排引擎》和 76《Agentic RAG》，那里会把状态图用于多 Agent 和自我修正 RAG 闭环。
• 直线链 vs 状态图：差别就一个词：图能有环，链不能。
• 四个核心概念：State 是一个字典，从头流到尾，每个节点往里读写。
• 条件边：图能分支和循环的关键：普通边（add_edge）是「A 执行完无条件去 B」。
• 图引擎：驱动 state 在图上跑，并防死循环：max_steps 不是可选项。
• 一句话面试答法：LangChain 的链是直线流水线，数据只能往前流；