PyLLM

主题

LangGraph 教程大纲 ​

总体设计思路 ​

LangGraph 是 LangChain 团队推出的图式工作流编排框架——它让你能够构建有状态、可中断、可持久化的 Agent 系统。如果说 LangChain 的 Agent 是"一次性执行到底"，那 LangGraph 的 Agent 就是"可以暂停等人审批、可以回溯历史状态、可以多 Agent 协作"。

本教程的设计遵循以下原则：

  1. 从概念到架构到实战：先建立"图=状态机"的核心认知，再逐步深入每个特性
  2. 每章一个核心能力：状态管理 → 路由 → 人机协作 → 循环 → 子图 → 持久化 → 多Agent，逐步叠加
  3. 两个完整实战项目：智能客服工单系统 + 自主研究助手，覆盖从需求到部署的全流程
  4. 面试深度 + 工程实战：不仅会用 API，更要理解 Interrupt 的底层原理、Checkpoint 的存储机制

第01章：LangGraph 核心概念入门（5节） ​

定位 ​

面向已经了解 LangChain 但还没接触过 LangGraph 的开发者。建立"图=状态机"的核心认知。

01-01 为什么需要 LangGraph ​

  • LangChain Agent 的局限：无状态、不可中断、不可回溯
  • LangGraph 的核心价值：有状态的图执行、人机协作、持久化
  • 适用场景判断：什么时候用 LangChain Agent，什么时候必须上 LangGraph

01-02 第一个有状态的图 ​

  • StateGraph 的定义：状态类型 + 节点函数 + 边
  • 编译与执行：compile() → invoke()
  • 与 LangChain LCEL 的对比：图 vs 链的本质区别

01-03 LangChain Agent vs LangGraph ​

  • ReAct Agent 的内部实现（其实就是一个图）
  • 什么时候 LangChain Agent 就够了
  • 什么时候必须用 LangGraph

01-04 核心概念全景 ​

  • State（状态）、Node（节点）、Edge（边）、Conditional Edge（条件边）
  • Interrupt（中断）、Checkpoint（检查点）、Subgraph（子图）
  • 概念之间的关系图

01-05 工具链与调试 ​

  • LangSmith 集成：可视化图的执行过程
  • LangGraph Studio：交互式图调试工具
  • 常用调试技巧与日志配置

第02章：状态机与图编程（5节） ​

定位 ​

LangGraph 的核心编程模型。掌握状态设计、节点编写、边路由的基本方法。

02-01 状态设计模式 ​

  • TypedDict vs Pydantic BaseModel：两种状态定义方式
  • 状态字段的增减策略：Annotated + reducer
  • 常见反模式：状态膨胀、不可变字段误用

02-02 节点编程模式 ​

  • 节点函数的签名：接收 State，返回部分 State
  • 纯函数 vs 副作用节点
  • 节点的错误处理与重试

02-03 边路由与拓扑结构 ​

  • 固定边：add_edge() 的用法
  • 条件边：add_conditional_edges() 的核心机制
  • 常见图拓扑：线性 / 分支 / 循环 / 并行

02-04 子图与组合模式 ​

  • 子图的基本概念：把一个图当作另一个图的节点
  • 子图的状态映射与接口定义
  • 子图组合的常见模式

02-05 实战模式与最佳实践 ​

  • 状态设计的 SOLID 原则
  • 图的可测试性设计
  • 常见架构模式速查

第03章：条件路由深度解析（5节） ​

定位 ​

条件路由是 LangGraph 区别于简单线性流程的核心能力。这一章从基本用法到 LLM 驱动的动态路由，全面覆盖。

03-01 条件边原理与实现 ​

  • 条件边的工作机制：路由函数 → 下一节点
  • 常见的路由模式：if-else / switch / 查表
  • 边界行为：路由函数返回不存在的节点名会怎样？

03-02 多层条件路由 ​

  • 链式路由：先判断 A，再判断 B
  • 分阶段决策：粗筛 → 细筛 → 最终选择
  • 如何避免"路由爆炸"这种架构恶化问题

03-03 LLM 驱动的动态路由 ​

  • 让大模型根据语义内容决定下一步
  • 动态路由的 Prompt 设计
  • 路由的可靠性保障：fallback + 人工兜底

03-04 路由的测试与调试 ​

  • 单元测试：验证每条路径的正确性
  • 集成测试：端到端路径覆盖
  • LangSmith 追踪路由决策过程

03-05 路由模式总结 ​

  • 路由设计模式速查表
  • 不同场景的推荐方案
  • 常见反模式与避坑指南

第04章：人机协作 (Human-in-the-Loop)（5节） ​

定位 ​

Interrupt 是 LangGraph 最独特的能力——让图在执行过程中暂停，等待人类输入后继续。这是构建审批流、确认对话框等场景的基础。

04-01 Interrupt 基础：让人在图的执行过程中介入 ​

  • Interrupt 的工作机制：暂停 → 持久化状态 → 等待输入 → 恢复执行
  • 基本用法：interrupt() + Command(resume=...)
  • 与 LangChain Agent 的本质区别

04-02 审批流与多级人工审核 ​

  • 单级审批、多级审批（主管→经理→总监）
  • 并行审批（多个部门同时审核）
  • 条件性审批（金额阈值决定审批级别）
  • 驳回与退回修改

04-03 Interrupt 高级用法与交互模式 ​

  • 条件性中断：只在特定条件下暂停
  • 多轮交互：多次 Interrupt 实现复杂对话
  • Interrupt 与子图的结合

04-04 构建交互式应用与 Interrupt 集成 ​

  • Web 前端集成：FastAPI + React
  • 聊天窗口集成：Slack / 飞书 / 钉钉
  • 移动端推送与审批

04-05 人机协作模式总结与最佳实践 ​

  • HITL 设计的核心原则
  • 常见架构模式
  • 长期实践中沉淀的经验教训

第05章：循环与迭代模式（5节） ​

定位 ​

循环结构是 LangGraph 构建复杂 Agent 的关键——自省循环让 Agent 自我改进，重试循环让 Agent 从错误中恢复。

05-01 自省循环基础：让 Agent 反思并改进 ​

  • "生成→评估→改进"的循环模式
  • 自省循环的 Prompt 设计
  • 何时停止循环：质量阈值 vs 最大迭代次数

05-02 重试与容错模式 ​

  • 简单重试、指数退避重试
  • 断路器模式
  • 级联失败的处理策略

05-03 循环中的状态管理与性能优化 ​

  • 状态膨胀问题：每次循环都在追加数据
  • 性能优化：只保留必要的历史状态
  • 循环执行的监控与诊断

05-04 高级循环模式：嵌套循环与并行迭代 ​

  • 两层嵌套循环：外层控制整体迭代、内层处理子任务
  • 多个独立循环并行执行
  • 循环与条件路由的组合

05-05 循环模式总结与实战指南 ​

  • 循环设计的核心决策框架
  • 综合实战案例

第06章：子图与模块化架构（5节） ​

定位 ​

子图不仅仅是"被复用的代码块"，它更是一种架构分层和组织策略。这一章从架构设计到测试策略，全面覆盖子图的使用方法。

06-01 子图架构设计：从可复用组件到完整系统 ​

  • 子图 vs 函数：为什么需要子图而不是简单的函数调用
  • 子图的划分原则：职责单一、边界清晰、独立可测试
  • 常见的子图架构模式

06-02 子图间的状态映射与数据流 ​

  • 父图和子图之间的状态传递机制
  • 字段名不同时的映射策略
  • 子图输出作为另一个子图输入的数据流转

06-03 子图的测试策略 ​

  • 子图的独立可测试性
  • 模拟父图环境的测试方法
  • 子图之间的集成测试

06-04 动态子图选择与注册表模式 ​

  • 根据运行时状态动态选择子图
  • 注册表模式：子图的注册、发现和调用
  • 实际案例：按文档类型选择解析子图

06-05 子图架构总结与工程化指南 ​

  • 子图工程化最佳实践
  • 常见反模式

第07章：持久化与时间旅行（5节） ​

定位 ​

Checkpointing 是生产级 LangGraph 应用的基石——没有持久化，一次崩溃就会丢失所有状态。时间旅行调试更是 LangGraph 独有的开发体验。

07-01 Checkpointing 基础：让图的状态可持久化 ​

  • MemorySaver 的局限：进程重启后数据丢失
  • Checkpoint 的工作机制：每步执行后自动保存完整状态快照
  • 基本用法：SqliteSaver / AsyncSqliteSaver

07-02 时间旅行调试与状态回溯 ​

  • 查看任意历史时刻的完整状态
  • 从某个历史点重新开始后续执行
  • 调试实战：定位"哪一步出了问题"

07-03 持久化后端选择与生产部署 ​

  • MemorySaver（开发） / SqliteSaver（单机） / PostgresSaver（生产）
  • 各后端的特性对比与适用场景
  • 配置方式与性能考量

07-04 Checkpoint 与 Interrupt 的协同工作 ​

  • Interrupt 必须配合 Checkpointing 才能正常工作
  • 两个机制的协同原理
  • 实际应用中的边界情况

07-05 持久化策略总结与生产最佳实践 ​

  • 生产级持久化策略指南
  • 备份与恢复
  • 性能优化

第08章：多智能体协作（5节） ​

定位 ​

当单个 Agent 的能力不足以应对复杂任务时，就需要多个 Agent 协同工作。LangGraph 提供了三种核心的多 Agent 协作模式。

08-01 多Agent架构概览：从单Agent到Agent团队 ​

  • 为什么需要多 Agent：各有所长，协同更强
  • 三种协作模式概览：Supervisor / Map-Reduce / Hand-off
  • 选型决策框架

08-02 Supervisor 模式深度解析 ​

  • 中央 Supervisor Agent 协调多个 Worker Agent
  • Worker 之间的依赖关系处理
  • 动态 Worker 注册与注销
  • Supervisor 决策逻辑的优化

08-03 Map-Reduce 并行模式 ​

  • "分发→并行执行→汇聚"的模式
  • 适合独立子任务的场景
  • 结果聚合与冲突解决

08-04 Hand-off 接力模式与状态传递 ​

  • Agent 之间像接力赛一样依次处理
  • 适合有明确流水线特征的任务
  • 状态传递与上下文保持

08-05 多Agent协作模式总结与选型指南 ​

  • 三种模式的对比分析
  • 组合策略：Supervisor + Map-Reduce 混合
  • 工程化最佳实践

第09章：项目一：智能客服工单系统（5节） ​

定位 ​

第一个完整实战项目。综合运用状态管理 + 条件路由 + Interrupt 人机协作 + 持久化，构建一个真实可用的客服工单系统。

09-01 项目概述与需求分析 ​

  • 智能客服工单系统的业务场景
  • 功能需求拆解与技术架构设计

09-02 核心模块实现：状态定义与图拓扑 ​

  • 定义完整的状态类型
  • 实现所有节点函数
  • 组装图并验证核心流程

09-03 API 服务层与前端界面 ​

  • FastAPI 构建 RESTful API
  • 简洁的 Web 前端界面

09-04 部署与优化 ​

  • Docker 容器化部署
  • 性能优化策略

09-05 监控与分析 ​

  • 系统可观测性设计
  • 运行数据分析与持续优化

第10章：项目二：自主研究助手 Agent（5节） ​

定位 ​

第二个完整实战项目。构建一个能自主规划研究路径、调用搜索工具、整合多源信息、生成研究报告的 Agent。

10-01 项目概述与需求分析 ​

  • 从"搜一下"到"帮我研究一下"的需求演进
  • 技术架构设计

10-02 核心模块实现 ​

  • 研究引擎的骨架：状态定义 + 图拓扑
  • 核心节点函数实现

10-03 多步推理与工具调用 ​

  • 让研究助手"会思考"：从机械执行到智能推理
  • 搜索/计算/文件操作工具的集成

10-04 结果整合与展示 ​

  • 从原始数据到洞察
  • 研究报告的自动生成

10-05 部署与扩展 ​

  • 从原型到产品
  • 扩展能力：更多工具、更多数据源

基于 MIT 许可发布

版权所有 © 2024-至今