一、前言：LangChain 生态定位与 LangGraph 选型指南

1.1 LangChain 三层生态架构（DeepAgents-LangChain-LangGraph）

在 LangChain 官方生态中，三层框架呈自上而下封装关系，类比建筑工程：

• DeepAgents（毛坯房）：开箱即用的成品 Agent 框架，内置长对话自动压缩、虚拟文件系统、子代理自动生成，快速落地标准化智能体，适合零基础快速开发；
• LangChain（预制建材）：封装基础 Chain、Agent 抽象，基于线性链式执行，快速实现简单串行任务，需要中度自定义 Agent 场景优先选用；
• LangGraph（水泥钢筋 / 底层基建）：底层状态图编排运行时，V1.x 主打版本稳定性，无上层封装、全流程可控，面向复杂循环、分支、长会话、多智能体定制化开发。

三者选型官方标准：

框架	适用场景	核心能力
DeepAgents	快速上线标准化自主 Agent	开箱即用、内置优化能力
LangChain	常规串行链式任务、轻度自定义 Agent	预制工具、提示词封装
LangGraph	确定性 + Agent 混合工作流、深度定制、长会话、多 Agent	持久化、HITL 人机交互、细粒度流程管控

1.2 LangGraph VS LangChain 核心差异

LangChain 基于线性链式结构（Chain）：Prompt→LLM1→输出→LLM2，只支持单向顺序执行，无法天然实现循环、多分支；LangGraph 基于有向状态图（DAG）：依托 State/Node/Edge 三大组件，天然支持循环迭代、条件分支，是构建 ReAct、多轮反思、工具循环调用 Agent 的最优方案。

注意：LangGraph V1.0 官方示例存在少量语法、运行 BUG，课程代码以 V1.0 为主，部分 API 向下兼容低版本。

1.3 环境部署（Python3.11）

1. 新建虚拟环境，通过requirements.txt批量安装依赖：

pip install -r requirements.txt

1. 可视化依赖异常处理：若pygraphviz/graphviz安装报错，在 requirements 注释pygraphviz一行跳过安装。

二、通识篇：LangGraph 三大核心基础组件（State/Node/Edge）

LangGraph 所有工作流本质：State 存储全局上下文，Node 执行业务逻辑，Edge 管控节点流转，三者构成StateGraph状态图。

2.1 State（全局状态：工作流共享内存）

State 是全图共享数据结构，定义全图字段与数据合并规则，两种定义方式：TypedDict（推荐，轻量化）、Pydantic（带数据校验，性能略低）。

2.1.1 基础状态定义

from typing import List, Annotated
from typing_extensions import TypedDict
from langchain_core.messages import AnyMessage
import operator

# 定义图状态Schema
class AgentState(TypedDict):
    messages: Annotated[List[AnyMessage], operator.add] # reducer：追加消息，不覆盖
    extra_num: int # 默认reducer：新值直接覆盖旧值

• Reducer 归约器核心规则：
  1. 无Annotated修饰：字段默认覆盖更新（新值替换旧值）；
  2. Annotated[类型, operator.add]：列表类字段追加合并（聊天消息必备，保留历史对话）；
  3. 支持自定义 Reducer 函数，灵活控制状态合并逻辑。

2.1.2 多 Schema 特性：输入 / 输出分离

LangGraph 支持单独指定图输入 Schema、输出 Schema，用于隔离内部中间字段与对外入参、出参，适合复杂工程解耦。

2.2 Node（节点：最小执行单元）

节点是 Python 同步 / 异步函数，入参固定：(state: State, config: dict | None)，config 用于运行时配置（thread_id、自定义参数），返回状态更新字典。

特殊内置节点

• START：图起始节点，用户输入的入口；
• END：终止节点，流转到 END 代表流程结束；

节点添加 API

from langgraph.graph import StateGraph, START, END

# 实例化图构建器
graph_builder = StateGraph(AgentState)

# 自定义LLM处理节点
def llm_node(state: AgentState):
    # 读取状态消息、执行LLM调用
    new_msg = ... # LLM生成消息
    return {"messages": [new_msg]}

# 注册节点
graph_builder.add_node("llm_handle", llm_node)

2.3 Edge（边：流程调度器）

两类边控制节点跳转，是实现分支、循环的关键：

1. Normal Edge（普通边）：固定节点流转 add_edge(A,B)，A 执行完成固定跳转 B；
2. Conditional Edge（条件边）：基于当前 State 动态决策下一跳节点，add_conditional_edges(源节点,判断函数,路由映射字典)。

# 普通边：起始→llm节点
graph_builder.add_edge(START, "llm_handle")

# 条件边示例：根据消息内容决定结束或继续
def route_func(state):
    if len(state["messages"]) >5:
        return "end_flag"
    return "llm_handle"
graph_builder.add_conditional_edges("llm_handle", route_func, {"end_flag":END, "llm_handle":"llm_handle"})

2.4 图编译（compile 必做步骤）

节点、边配置完成后必须调用.compile()编译，做语法校验、初始化运行时、绑定检查点：

# 编译生成可运行图实例
graph = graph_builder.compile()
# 调用执行
res = graph.invoke({"messages": [("human","你好")], "extra_num":1})

三、进阶篇：LangGraph V1.x 九大高级核心特性

3.1 Send 机制：Map-Reduce 并行分支

Send 用于动态扇出并行执行，解决运行时才确定子任务数量、多节点并行运算场景（Map-Reduce 架构）：

1. Map 阶段：单个节点生成多个子任务，返回[Send(子节点名, 独立子任务状态)]；
2. 并行执行：LangGraph 自动并行启动多个子节点，每个 Send 携带独立 State；
3. Reduce 阶段：汇总所有并行结果，合并至全局主状态。

典型场景：多主题生成笑话（map 生成单主题→并行生成笑话→reduce 筛选最优笑话）。

3.2 Command：节点内一体化路由 + 状态更新

Command 是增强版条件边，在单个 Node 返回值中同时完成两件事：

1. 更新全局状态（update 字段）；
2. 动态指定下一跳节点（goto 字段），替代单独编写条件边逻辑。

from langgraph.types import Command
def cmd_node(state):
    # 更新状态+指定跳转
    return Command(
        update={"extra_num": state["extra_num"]+1},
        goto="llm_handle"
    )

额外搭配resume参数，专门用于Interrupt人机交互恢复场景。

3.3 Persistence 持久化 + Checkpoint 检查点 + Thread 线程

3.3.1 Checkpoint（状态快照）

编译图时挂载检查点器（MemorySaver/Redis/MongoDB/SQLite），每轮节点执行完成自动全量保存 State 快照，实现：会话断点续跑、历史状态回溯、服务宕机恢复。

3.3.2 Thread（会话 ID）

thread_id是单会话唯一标识，通过 config 配置绑定：{"configurable":{"thread_id":"uuid_001"}}，同一个 thread_id 复用历史会话状态，实现多轮对话记忆。

from langgraph.checkpoint.memory import MemorySaver
checkpointer = MemorySaver()
# 编译绑定内存检查点
graph = graph_builder.compile(checkpointer=checkpointer)
# 携带thread_id调用
config = {"configurable":{"thread_id":"chat_001"}}
graph.invoke(inputs, config=config)

3.3.3 两种持久化方案

1. 线程级持久化：单会话内上下文保存（常规聊天机器人）；
2. 跨线程持久化：全局用户配置、基础信息跨不同会话复用，搭配 Redis/MongoDB 生产落地。

3.4 Interrupt 中断 & Human-in-the-Loop (HITL 人机在环)

Interrupt = 节点内动态暂停 + 等待人工输入，依赖检查点持久化保存现场，人工输入后恢复执行，是 Agent 落地生产必备能力。

使用场景

1. 工具调用前人工审批（风控、财务、法律场景校验调用参数）；
2. AI 生成内容人工审核修改；
3. Agent 缺信息主动询问用户补充。

from langgraph.types import interrupt
def human_review_node(state):
    # 暂停，向客户端抛出待审核内容
    user_feedback = interrupt({"draft":state["messages"][-1].content})
    # 用户输入后，从interrupt处继续执行
    return {"messages": [("human", user_feedback)]}

恢复方式：使用Command(resume=用户输入内容)再次 invoke 同 thread_id 的图。

实战落地：FastAPI+React 前后端项目，前端弹窗接收用户反馈，后端调用 resume 恢复 Agent（hitl_demo 项目）。

3.5 Subgraph 子图：模块化封装、多智能体基础

子图 =一个完整编译后的 Graph 作为父图的单个 Node，实现复杂逻辑模块化拆分，是多 Agent 系统核心实现方式：

1. 同 Schema 子图：父子图共用状态字段，直接 add_node 挂载子图实例；
2. 不同 Schema 子图：自定义包装函数做状态映射，函数内部调用子图执行。

关键：子图自动继承父图编译时绑定的 Checkpoint，无需单独配置持久化。

3.6 ToolNode 工具节点：标准化 LLM 工具调用

LangGraph 内置ToolNode封装工具执行逻辑，搭配 LangChain 标准 Tool，一站式实现：

• LLM 输出工具调用参数→ToolNode 解析并执行函数→结果回写状态 messages；
• 内置异常捕获：无效工具名、参数错误、第三方接口异常，支持自定义异常重试策略。

高级工具控制能力

1. 运行时注入参数：通过InjectedArg注解，LLM 不可传入，由代码 / 配置自动注入（用户 ID、密钥）；
2. 动态工具筛选：海量工具场景通过 RAG 检索，运行时动态给 LLM 注入可用工具，减少 token 消耗；
3. 工具内修改状态：工具函数返回 Command (update={...}) 直接修改全局 State。

3.7 循环 Graph 与递归限制

循环依靠条件边自环实现（A 节点→条件边→A/END），通过recursion_limit参数控制最大循环步数，防止死循环：

# 编译指定最大递归步数10
graph = graph_builder.compile(checkpointer=checkpointer, recursion_limit=10)

• 达到上限默认抛异常；可自定义逻辑：触达上限时直接返回当前状态，不报错退出。

3.8 Configuration 运行时动态配置

编译时标记可配置参数，运行时通过 config 字典动态修改：LLM 模型切换、系统 Prompt 变更、工具参数调整，同一套图架构实例化多套不同配置的 Agent。

3.9 Graph 可视化

通过内置 API 渲染 Graph 结构图，快速排查分支 / 循环逻辑异常，支持导出图片；注意：V1.x 部分复杂并行 Send 渲染存在小偏差属于正常现象。

四、深入篇：工程落地三大重点（持久化管理 / 工具管控 / 多智能体）

4.1 会话历史优化（长文本防溢出）

长对话场景消息无限堆积会触发上下文超限、LLM 计费暴涨，三种优化方案：

1. RemoveMessage：精准删除指定历史消息；
2. 消息摘要：定期启动摘要节点，压缩早期聊天记录为简短文本存入状态；
3. 消息截断：保留最新 N 轮消息，丢弃久远历史。

4.2 生产级工具调用全生命周期管控

1. 节点重试：LLM 调用、接口工具配置自定义重试次数、间隔，应对网络波动；
2. 异常兜底：工具失败后路由至异常处理节点，自动重试或告知用户；
3. 配置透传：用户 ID、租户信息通过 config 向下透传至所有工具，安全隔离参数，禁止 LLM 可控。

4.3 Multi-Agent 多智能体系统实现

基于子图 + Command 交接实现多 Agent 协作，两种主流架构：

1. 任务交接架构：AgentA 完成任务后通过 Command (goto="AgentB") 把状态转交 AgentB；
2. 管理者调度架构：Supervisor 总管节点根据任务内容动态路由至不同专业 Agent（搜索 Agent、数据分析 Agent、写作 Agent）；
3. 多轮 + HITL 融合：任意 Agent 节点触发 Interrupt 暂停，用户反馈后由调度逻辑交还对应 Agent 继续处理。

五、踩坑总结（LangGraph V1.x 特有问题）

1. 官方示例 BUG：官网 / GitHub 示例代码存在语法错误、API 废弃，开发以课程修正版代码为准，部分场景降级低版本 LangGraph；
2. Reducer 误用：聊天消息字段忘记配置operator.add，导致每次回复覆盖全量历史；
3. Interrupt 必须配 Checkpoint：无检查点器时 Interrupt 无法保存会话、无法恢复执行；
4. 子图持久化：仅需父图挂载 Checkpoint，子图自动复用，无需重复配置。

六、结语 & 拓展学习路线

1. 入门：手写最简对话 Graph→掌握 State/Node/Edge 基础语法；
2. 进阶：Checkpoint+HITL 实现可续聊机器人、Send 实现 Map-Reduce 并行；
3. 工程：Redis/MongoDB 持久化、多 Agent 调度、前后端联调 HITL 项目；
4. 生产：旅游 Agent / 知识库 RAG 智能体落地、海量工具动态检索优化。

Note:对AI 技术感兴趣的小伙伴，可以关注下方，私信我发送"AI资料"，可获取AI相关资料和源码。