模块 04 · 工作流编排

LangGraph 框架指南

围绕智能简历筛选系统，从一段脚本长成多 Agent、可恢复、可人工介入的生产级工作流。

17 章LangGraph

一本面向 Python 开发者的 LangGraph 系统性教程。全书围绕一个虚构但完整的业务——智能简历筛选系统——从一段三十行的脚本出发，一步步长成一个多 Agent、可恢复、可人工介入的生产级工作流。每一个核心机制的引入，都源于上一章暴露出来的真实工程问题。

适合谁读

熟练使用 Python，能独立完成日常脚本与服务端开发
已经会用 LangChain 调用模型、构造消息、绑定工具（本书不再铺垫这些内容）
希望系统掌握 LangGraph，而不是只抄得出一个 ReAct 模板

环境约定

全书代码基于 langgraph 1.x，模型调用走 OpenAI 兼容接口（可对接 OpenAI、阿里云百炼、DeepSeek 等任意兼容服务商）。

uv init resume-screener && cd resume-screener
uv add "langgraph>=1.0,<2.0" "langchain-openai>=1.0" python-dotenv

在工程根目录准备 .env：

OPENAI_API_KEY=sk-xxxxxx
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL=qwen-plus

OPENAI_BASE_URL 按你所选服务商填写；不设置则默认连接 OpenAI 官方端点。 ChatOpenAI 会自动读取 OPENAI_API_KEY 与 OPENAI_BASE_URL，因此书中代码只需关心模型名。

各章 demo 均为自包含脚本，可直接保存为 .py 文件运行：

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI

load_dotenv()
llm = ChatOpenAI(model=os.getenv("LLM_MODEL", "gpt-4o-mini"))

章节目录

第一部分 · 出发

第 1 章从一个失控的脚本说起 —— LLM 应用为什么需要编排引擎
第 2 章最小可运行图 —— 定义、编译、运行三步走

第二部分 · 数据与流转

第 3 章状态：图的数据心脏 —— 通道与 Reducer 机制
第 4 章让流程学会决策 —— 条件边、循环与安全阀
第 5 章并行世界：超步执行模型 —— Pregel 与 superstep 边界
第 6 章 Command：把控制权交进节点 —— goto 与 update 原语
第 7 章动态并行：Send 与 MapReduce —— 批量任务的扇出与归并

第三部分 · 能力扩展

第 8 章给图装上手脚：工具调用 —— ToolNode 与 ReAct 循环
第 9 章复用与封装：子图 —— 两种嵌入方式与状态共享
第 10 章从单图到团队：多 Agent 架构 —— 子图组合与路由协作

第四部分 · 生产化

第 11 章流式输出 —— 五种 stream_mode 与自定义流
第 12 章持久化：Checkpointer 与线程 —— 状态落盘与会话恢复
第 13 章时间旅行 —— 历史回溯、replay 与 fork
第 14 章中断与人在回路 —— interrupt 与恢复执行
第 15 章记忆管理 —— 短期裁剪与长期 Store
第 16 章容错：重试、超时与兜底 —— 让图在故障面前活下来

第五部分 · 收束

第 17 章全景回顾 —— 完整架构总览与进阶路线

每章的结构

全书各章保持统一骨架，方便对照与回顾：

正文：从问题出发讲透原理，配精炼可运行的 demo
常见坑与排错：真实开发中高频翻车点
动手练习：2~3 道巩固题
本章速查：API 与概念的一页化总结

阅读建议

严格按章节顺序读，后面的章节会复用前面搭建的图结构
每章 demo 建议亲手跑一遍，改几个参数观察行为差异
第 5、12、14 章是理解 LangGraph 运行时模型的三个关键节点，值得放慢速度

章节清单

01第 1 章从一个失控的脚本说起本章不写一行 LangGraph 代码，只回答一个问题：当 LLM 应用长到一定程度，为什么必然会走向"图"？10 分钟 · 5 个代码示例02第 2 章最小可运行图本章目标：跑通第一张 LangGraph 图，并吃透它的三个生命周期阶段——定义、编译、运行，以及最容易误解的一件事：节点返回的是"补丁"，不是"全量状态"17 分钟 · 10 个代码示例03第 3 章状态：图的数据心脏本章目标：理解图状态的真正身份——它不是普通字典，而是"一组通道（channel）的集合"；每个通道有自己的更新规则（reducer）。学完本章，"多节点写同一字段"这类经典 bug 将与你绝缘20 分钟 · 10 个代码示例04第 4 章让流程学会决策本章目标：掌握 addconditionaledges——让"下一步去哪"由运行时的状态决定。分支、循环、打回重做，都由这一个 API 承担。同时建立两条安全意识：循环必须有出口，出口要有安全阀15 分钟 · 8 个代码示例05第 5 章并行世界：超步执行模型本章目标：建立 LangGraph 执行模型的"节拍器"概念——超步（superstep）。理解它，并行的行为、汇合的时机、recursionlimit 的计数、以及并行写状态的种种规则，全都顺理成章。本章还会处理一个足…17 分钟 · 8 个代码示例06第 6 章 Command：把控制权交进节点本章目标：掌握节点内路由机制 Command——让节点在返回状态更新的同时声明"下一步去哪"。学完本章，你能在"条件边"与"Command"之间做出干净的选型，并用 Command 重写出更内聚的控制流13 分钟 · 6 个代码示例07第 7 章动态并行：Send 与 MapReduce本章目标：掌握 Send——LangGraph 中"运行时才知道并行几路"的扇出机制。学完本章，你能实现标准的 MapReduce 工作流：N 份输入并行处理、结果自动归并，而 N 在编译期完全未知14 分钟 · 5 个代码示例08第 8 章给图装上手脚：工具调用本章目标：让图里的节点具备"调用外部能力"的本事——查岗位库、查公司背景。核心是 ToolNode 与"模型节点 ↔ 工具节点"的循环结构，也就是 ReAct 模式在 LangGraph 中的标准落地16 分钟 · 4 个代码示例09第 9 章复用与封装：子图本章目标：把一张图变成另一个节点——掌握子图的两种嵌入方式（状态共享与状态转换），理解"编译产物是 Runnable"这句话在架构层面的真正威力。第 2 章埋下的伏笔，本章兑现16 分钟 · 4 个代码示例10第 10 章从单图到团队：多 Agent 架构本章目标：用前九章的全部积木搭出多 Agent 系统。理解"Agent = 带工具循环的子图"这个组合公式，掌握 Supervisor（主管协调）与 Swarm（同伴移交）两种主流协作拓扑，以及它们各自适合的问题形状17 分钟 · 6 个代码示例11第 11 章流式输出本章目标：系统掌握 stream 的五种模式——values / updates / messages / custom / debug，理解它们各自的粒度与适用场景，并学会用自定义流把图内部的事件推送出去。前几章已经多…17 分钟 · 9 个代码示例12第 12 章持久化：Checkpointer 与线程本章目标：让图"记住"执行历史。掌握 Checkpointer 的挂载方式与线程（thread）模型——它是会话恢复、断点重跑、时间旅行、中断恢复这四大能力的共同地基。第 1 章立下的"状态不可恢复"痛点，本章兑现13 分钟 · 6 个代码示例13第 13 章时间旅行本章目标：在第 12 章的检查点机制之上，掌握回放（replay）与分叉（fork）两种时间旅行形态。前者"重看历史"，后者"改写历史"——它们是调试复杂工作流和做 A/B 对比实验的核心武器14 分钟 · 6 个代码示例14第 14 章中断与人在回路本章目标：掌握 interrupt——图运行到关键节点主动暂停，等人来决策，再带着决策恢复执行。这是生产级 Agent 的分水岭能力：全自动与全自动 supervised 之间的区别，就在这一章16 分钟 · 4 个代码示例15第 15 章记忆管理本章目标：治理"记太多"与"记不住"两个相反的问题。短期记忆靠裁剪（把消息历史控制住），长期记忆靠 Store（跨线程的用户画像）。前者的核心武器是 RemoveMessage，后者的核心武器是带命名空间的 KV 存储22 分钟 · 4 个代码示例16第 16 章容错：重试、超时与兜底本章目标：让图在故障面前活下来。掌握三个层次的容错手段——节点级重试（RetryPolicy）、节点级超时与异常兜底、以及"错误重跑"（failure + replay 组合拳）。LLM 应用调的是不稳定的外部服务，容错…17 分钟 · 5 个代码示例17第 17 章全景回顾终章。把十六章积累的零件装配成一台完整的机器，给出一幅可以挂在墙上的总图，然后指出这本书没有讲、但你接下来该去哪9 分钟 · 2 个代码示例