LangGraph 保姆级入门教程：从环境搭建到状态管理，一篇吃透 AI Agent 核心原理

文章目录

• • 第1章 开发环境配置
  • • 1.1 Miniconda 安装与配置
    • • 1.1.1 下载 Miniconda
      • 1.1.2 Windows 系统安装步骤
      • 1.1.3 macOS 系统安装步骤
      • 1.1.4 Linux 系统安装步骤
    • 1.2 Conda 虚拟环境管理
    • • 1.2.1 Conda 常用命令速查表
      • 1.2.2 创建课程专用环境
      • 1.2.3 激活虚拟环境
      • 1.2.4 配置 pip 国内镜像源（中国大陆用户推荐）
    • 1.3 PyCharm IDE 安装与项目创建
    • • 1.3.1 下载 PyCharm
      • 1.3.2 Windows 系统安装 PyCharm
      • 1.3.3 macOS 系统安装 PyCharm
      • 1.3.4 创建课程项目
      • 1.3.5 使用 PyCharm 终端
    • 1.4 依赖包安装详解
    • • 1.4.1 核心依赖包说明
      • 1.4.2 安装依赖包
    • 1.5 API Key 配置与环境变量管理
    • • 1.5.1 获取 DeepSeek API Key
      • 1.5.2 创建 .env 环境变量文件
      • 1.5.3 在代码中读取 .env 文件
    • 1.6 Jupyter Notebook 配置与使用
    • • 1.6.1 启动 Jupyter Notebook
      • 1.6.2 验证 Kernel 配置
      • 1.6.3 Jupyter Notebook 基本使用
    • 1.7 环境验证完整流程
    • • 1.7.1 基础命令验证
      • 1.7.2 代码验证脚本
    • 1.8 常见问题与解决方案
    • • Q1: `conda` 命令找不到？
      • Q2: PyCharm 中找不到 Conda 环境？
      • Q3: `pip install` 速度很慢或者超时？
      • Q4: 安装依赖时报错 `Microsoft Visual C++ 14.0 is required`？
      • Q5: Jupyter 中找不到 `Python (langgraph)` Kernel？
      • Q6: `import langgraph` 报 `ModuleNotFoundError`？
      • Q7: 模型调用时报 `AuthenticationError`（认证错误）？
      • Q8: 模型调用时报网络连接错误？
      • Q9: 想把环境恢复到初始状态重新安装？
      • Q10: PyCharm 中代码补全不工作？
    • 环境配置检查清单
  • 第2章 LangGraph 概述与定位
  • • 2.1 LangChain 与 LangGraph 的关系
    • • 2.1.1 LangChain 1.x 的定位变化
      • 2.1.2 LangGraph 的定位
      • 2.1.3 二者的定位对比
    • 2.2 LangGraph 的核心价值
    • • 2.2.1 有状态的执行模型
      • 2.2.2 循环与分支的原生支持
      • 2.2.3 可靠的持久化与恢复
      • 2.2.4 一流的流式支持
      • 2.2.5 原生 Human-in-the-Loop
    • 2.3 什么时候应该使用 LangGraph
    • • 2.3.1 适合使用 LangGraph 的场景
      • 2.3.2 可能不需要 LangGraph 的场景
    • 2.4 LangGraph 的技术架构概览
  • 第3章 LangGraph 运行时底层原理
  • • 3.1 Pregel 计算模型
    • • 3.1.1 为什么选择 Pregel 模型
      • 3.1.2 Pregel 的核心思想
    • 3.2 Superstep（超步）机制详解
    • • 3.2.1 什么是 Superstep
      • 3.2.2 为什么需要 Superstep
    • 3.3 图运行的三个阶段
    • • 3.3.1 计划/路由阶段（Plan / Routing）
      • 3.3.2 执行阶段（Execution）
      • 3.3.3 状态更新/提交阶段（Update / Commit）
      • 3.3.4 完整流程示意
    • 3.4 Channel 状态通道机制
    • • 3.4.1 什么是 Channel
      • 3.4.2 Channel 的类型
      • 3.4.3 Channel 与节点触发的关系
      • 3.4.4 从源码角度理解 Channel
  • 第4章 图的基本构成要素
  • • 4.1 State（状态）：共享数据的核心载体
    • • 4.1.1 State 的本质
      • 4.1.2 State 的特点
    • 4.2 Node（节点）：业务逻辑的执行单元
    • • 4.2.1 节点函数的基本形式
      • 4.2.2 节点的核心规则
      • 4.2.3 节点可以做什么
    • 4.3 Edge（边）：控制流程的流转关系
    • • 4.3.1 边的类型
      • 4.3.2 边的方向
      • 4.3.3 条件边的灵活性
    • 4.4 START 与 END：图的边界标记
    • • 4.4.1 START：图的入口
      • 4.4.2 END：图的出口
      • 4.4.3 一个简单的三要素示例
  • 第5章 Graph API vs Functional API
  • • 5.1 两种 API 的设计哲学
    • • 5.1.1 Graph API 的设计哲学
      • 5.1.2 Functional API 的设计哲学
    • 5.2 Graph API：声明式图构建
    • • 5.2.1 Graph API 的典型代码结构
      • 5.2.2 Graph API 的优势场景
    • 5.3 Functional API：命令式函数流程
    • • 5.3.1 Functional API 的典型代码结构
      • 5.3.2 Functional API 的优势场景
    • 5.4 核心区别对比
    • 5.5 选型建议与最佳实践
    • • 5.5.1 学习路径建议
      • 5.5.2 项目选型建议
      • 5.5.3 混合使用
      • 5.5.4 本教程的侧重点
  • 第6章 第一个 LangGraph 程序
  • • 6.1 完整的三步构建流程
    • 6.2 定义全局状态
    • 6.3 创建 StateGraph 实例
    • 6.4 定义节点函数
    • 6.5 添加节点和边
    • 6.6 编译图
    • 6.7 调用图并查看结果
    • 6.8 完整代码逐行解析
    • • 6.8.1 执行过程深度追踪
    • 6.9 本章小结
  • 第7章 图结构可视化
  • • 7.1 Mermaid 图表语法简介
    • 7.2 获取 Mermaid 源码
    • 7.3 渲染为 PNG 图片
    • • 7.3.1 draw_mermaid_png() 方法
    • 7.4 Jupyter 环境中的快捷展示
    • • 7.4.1 使用 IPython.display 展示 PNG
      • 7.4.2 最快捷的方式：display(graph)
    • 7.5 保存可视化图片到文件
    • • 7.5.1 可视化复杂图示例
      • 7.5.2 自定义 Mermaid 样式（可选）
    • 7.6 本章小结
  • 第8章 状态（State）管理深度解析
  • • 8.1 状态 Schema 的三种定义方式
    • 8.2 TypedDict 详解与推荐用法
    • • 8.2.1 基本用法
      • 8.2.2 为什么推荐 TypedDict
      • 8.2.3 TypedDict 的两种定义语法
    • 8.3 dataclass 状态定义
    • • 8.3.1 基本用法
      • 8.3.2 dataclass 的特点
    • 8.4 Pydantic BaseModel 状态定义
    • • 8.4.1 基本用法
      • 8.4.2 Pydantic 的校验能力
    • 8.5 三种方式的校验行为对比
    • • 8.5.1 输入字段不匹配（初始调用时）
      • 8.5.2 节点返回字段不匹配
    • 8.6 节点中读取状态的最佳实践
    • • 8.6.1 读取字段的方法
      • 8.6.2 读取状态的注意事项
    • 8.7 节点更新状态的核心规则
    • • 8.7.1 只返回需要更新的字段
      • 8.7.2 返回空字典
    • 8.8 本章小结
  • 第9章 State Reducer 状态合并机制
  • • 9.1 Reducer 的本质与作用
    • • 9.1.1 为什么需要 Reducer
      • 9.1.2 Reducer 的定义
      • 9.1.3 Reducer 的核心特征
    • 9.2 如何定义自定义 Reducer
    • • 9.2.1 定义 Reducer 函数
      • 9.2.2 将 Reducer 与状态字段关联
    • 9.3 Annotated 类型注解机制
    • • 9.3.1 Annotated 的基本用法
      • 9.3.2 LangGraph 如何使用 Annotated
    • 9.4 内置 Reducer：operator.add
    • • 9.4.1 operator.add 的行为
      • 9.4.2 使用 operator.add 的完整示例
    • 9.5 内置 Reducer：add_messages
    • • 9.5.1 为什么需要 add_messages
      • 9.5.2 add_messages 的合并逻辑
      • 9.5.3 add_messages 使用示例
    • 9.6 默认覆盖行为（Last-Write-Wins）
    • • 9.6.1 默认覆盖示例
      • 9.6.2 什么时候使用默认覆盖
    • 9.7 Overwrite：绕过 Reducer 强制覆盖
    • • 9.7.1 Overwrite 的作用
      • 9.7.2 Overwrite 使用示例
      • 9.7.3 Overwrite 的使用场景
    • 9.8 并行更新冲突处理
    • • 9.8.1 有 Reducer 的字段：安全合并
      • 9.8.2 无 Reducer 的字段：可能出错
    • 9.9 本章小结
  • 第10章 多状态 Schema 高级用法
  • • 10.1 四类状态：输入、输出、全局、私有
    • • 10.1.1 为什么需要多 Schema
    • 10.2 状态设计的工程规范
    • • 10.2.1 规范一：输入和输出状态应该是全局状态的子集
      • 10.2.2 规范二：私有状态与全局状态避免字段重名
      • 10.2.3 规范三：节点函数应明确声明入参和返回类型
      • 10.2.4 规范四：节点不应访问入参类型中不存在的字段
      • 10.2.5 规范五：节点返回字典尽量与返回类型注解一致
    • 10.3 源码层面的状态记录机制
    • • 10.3.1 状态字段的记录过程
      • 10.3.2 状态的裁剪规则
    • 10.4 状态裁剪与访问控制
    • 10.5 多状态 Schema 完整案例
    • 10.6 案例执行过程深度分析
    • • 步骤1：图入口——输入裁剪
      • 步骤2：node_1 执行
      • 步骤3：node_2 执行
      • 步骤4：node_3 执行
      • 步骤5：图出口——输出裁剪
    • 10.7 本章小结
  • 第11章 预定义状态类型
  • • 11.1 MessagesState：对话消息状态
    • • 11.1.1 MessagesState 的定义
      • 11.1.2 为什么使用 MessagesState
      • 11.1.3 扩展 MessagesState
    • 11.2 MessagesState 使用案例
    • • 11.2.1 执行流程分析
      • 11.2.2 多轮对话扩展
    • 11.3 AgentState：LangChain Agent 状态
    • • 11.3.1 AgentState 的定义
      • 11.3.2 何时使用 AgentState
    • 11.4 自定义预定义状态扩展
    • 11.5 本章小结
  • 第12章 基础控制流：顺序执行
  • • 12.1 add_edge：基础边的使用
    • • 12.1.1 基本用法
      • 12.1.2 add_edge 的本质
    • 12.2 add_sequence：快速构建顺序节点
    • • 12.2.1 add_sequence 的用法
      • 12.2.2 add_sequence 完整示例
    • 12.3 关于 END 边的省略问题
    • • 12.3.1 END 不是真实节点
      • 12.3.2 可以省略 END 边的情况
      • 12.3.3 为什么建议显式添加 END 边
    • 12.4 START 入口点的必要性
    • • 12.4.1 为什么 START 是必须的
      • 12.4.2 START 的灵活性
    • 12.5 顺序执行完整案例
    • 12.6 本章小结
  • 第13章 基础控制流：分支与并行
  • • 13.1 静态分支 vs 动态分支
    • 13.2 并行节点：同时触发多个节点
    • • 13.2.1 基本并行
      • 13.2.2 并行的注意事项
    • 13.3 add_conditional_edges：条件边 API
    • • 13.3.1 API 签名
      • 13.3.2 路由函数的返回值
    • 13.4 不使用 path_map 的条件路由
    • 13.5 使用 path_map 的语义化路由
    • 13.6 条件入口点：从 START 开始分支
    • 13.7 多目标分支：同时跳转到多个节点
    • • 13.7.1 多目标路由示例
      • 13.7.2 扇入（Fan-in）：等待所有并行分支完成
    • 13.8 动态扇出：Send API
    • • 13.8.1 Send 的构造
      • 13.8.2 动态扇出示例：为每个主题生成内容
      • 13.8.3 MapReduce 模式
    • 13.9 动态跳转：Command(goto=…)
    • • 13.9.1 Command 简介
      • 13.9.2 Command 实现条件分支
      • 13.9.3 add_conditional_edges vs Command(goto=…)
    • 13.10 分支与并行总结
    • 13.11 本章小结
  • 总结与进阶展望
  • • 知识回顾
    • • 1. 环境与定位
      • 2. 底层原理
      • 3. 核心三要素
      • 4. API 风格
      • 5. 第一个程序
      • 6. 可视化
      • 7. 状态管理
      • 8. Reducer 机制
      • 9. 多 Schema
      • 10. 预定义状态
      • 11. 控制流
    • 你现在能做什么

第1章 开发环境配置

工欲善其事，必先利其器。在开始学习 LangGraph 之前，我们需要先搭建一套完整、稳定的开发环境。本章将从零开始，一步步带你完成所有环境配置工作。

1.1 Miniconda 安装与配置

Conda 是一个开源的包管理和环境管理工具，它可以帮助我们轻松创建隔离的 Python 环境，避免不同项目之间的依赖冲突。Miniconda 是 Conda 的精简版本，只包含最基本的组件，体积小、安装快，是学习和开发的推荐选择。

1.1.1 下载 Miniconda

首先，我们需要从官方网站下载 Miniconda 安装包：

官方下载地址：https://docs.anaconda.com/miniconda/

根据你的操作系统选择对应的安装包：