LangGraph 超详细保姆级教程

第 00 章导读 · 开始之前

在写第一行代码之前,先花 10 分钟读完这一章,后面会顺利十倍。本章回答三个问题:这份教程怎么读?你需要会什么?教程内容依据哪些官方一手资料?

0.1 这份教程怎么读

这是一份面向零基础读者的 LangGraph 教程。编写时遵循三条原则:

📖 推荐阅读路线 完全零基础:按顺序从第 0 章读到第 11 章,动手敲完每一章的代码。
会一点 Python、用过 LLM API:可先读第 1 章,然后直接跳第 3、4 章(核心概念),第 7 章(实战 Agent),其余章节按需查。
只想查 API 用法:直接看附录 A.2「核心 API 速查表」和第 18 章 FAQ。

0.2 你需要会什么

前置知识需要到什么程度不会怎么办
Python 基础会函数定义、字典、列表、import、装饰器(不要求精通,见到的都会解释)任意 Python 入门教程学 2 小时即可跟上本教程
命令行会在 Windows 的 CMD / PowerShell 里敲 pip install xxx第 2 章会给逐条命令,直接复制粘贴
大模型 API不要求。第 1~5 章完全不涉及,第 6 章起会从零讲起—
图论 / 算法完全不要求。这里的"图"只是"流程图"的意思—

0.3 官方一手资料与版本历史

本教程的全部技术内容都核对自 LangChain 官方发布的一手资料。这里如实说明资料的构成,方便你以后自行溯源:

📅 版本时间线(自查于 2026-09)

时间事件
2024-01LangGraph 首次发布(官方博客宣布),主打"有循环的状态机"
2025-10-22LangGraph 1.0 正式发布(与 LangChain 1.0 同日),承诺 2.0 之前不引入破坏性变更;核心图 API 与 0.6.x 保持一致;create_react_agent 弃用、演进为 LangChain 1.0 的 create_agent
2026-07(写作时)最新稳定版 langgraph 1.2.11;1.2 引入了事件流式传输(event streaming)、错误处理器等增强;每日下载约 185 万次
💡 本教程 API 口径全部代码按 LangGraph 1.x 的写法给出。如果你在网上看到旧教程用了 MemorySaver、StateGraph(MessageGraph)、create_react_agent 等写法,对应关系会在正文相应位置说明(例如 9.6 节、7.6 节)。

第 01 章LangGraph 是什么

先建立大局观:它解决什么问题、和 LangChain 什么关系、什么时候该用、什么时候不该用。本章没有任何代码。

1.1 一句话定义

LangGraph 是一个用来搭建"会自己干活的 AI 助手(Agent)"的 Python 框架。
它把你的业务流程画成一张流程图:图上有若干节点(每个节点干一件事),节点之间用边连接(决定干完这步接下来去哪),所有节点共享一块白板(State,状态)用于传递信息。它最拿手的是让流程"转圈"——干一步、看一眼结果、不合适就退回去重来。

官方 GitHub 上的自我介绍原文是:"a low-level orchestration framework for building, managing and deploying long-running, stateful agents"——低层意味着它不替你隐藏细节,给你的是积木而不是整机,你拥有对每一步的完全控制权;编排(orchestration)意味着它管的是"谁在什么时候干活"这件事;有状态(stateful)意味着整个流程从头到尾共享并记住一份不断更新的数据。

它由 LangChain 公司开发,MIT 协议开源,官方列出的生产用户包括 Klarna、Uber、J.P. Morgan、Replit、Elastic 等公司。

1.2 零基础类比:先打个比方

类比一:工厂流水线 vs 侦探破案

普通的程序像流水线:原料从这头进,经过 A → B → C 三道工序,成品从那头出。永远直线,永远一个方向。

但很多 AI 任务像侦探破案:先看现场(收集信息)→ 形成一个猜测(推理)→ 去验证猜测(查证)→ 发现猜错了?退回来,换个方向再猜(回到推理)→ 直到证据链完整(收工)。中间会"绕圈",而且绕几圈事先不知道,取决于每次查证的结果。

传统的链式框架写不了"绕圈";LangGraph 就是为绕圈而生的。官方博客发布文章里的原话是:链(LCEL)是有向无环图(DAG),无法引入循环;而 Agent 的本质就是 "running an LLM in a for-loop"(把大模型放进 for 循环里反复调用)。

类比二:一张公司组织里的"工单流转图"

想象一个客服部门处理投诉:

收到投诉→ 分诊台:什么类型? → 退款退款专员 → 物流物流专员 → 都不会人工客服

这里每个"专员"就是一个节点,箭头就是边,分诊台根据工单内容决定去向——这就是条件边;全部门共用一份工单档案(客户是谁、说过什么、处理到哪一步)——这就是State 状态。看懂这张图,你就看懂了 LangGraph 的全部骨架。

1.3 为什么需要它:链条不能转圈

在 LangGraph 出现之前,大家主要用两种方式写 LLM 应用,各有死穴:

方式长处死穴
链式调用(LangChain LCEL 等)简单直观:提示词 → 模型 → 输出,一条线串起来只能直线(DAG)。模型第一步检索效果差,没法"回头重新检索"
老的 AgentExecutor(自动循环)能循环,模型自主决定调什么工具太"放权"。所有决策都交给模型,想"强制先查数据库再回答"这类生产级控制做不到
LangGraph既能转圈,又完全可控:循环你说了算,每一步可插入确定性代码、人工审批、条件分支需要自己画图,概念比"一行调 API"多一点(本教程就是来消灭这个门槛的)

官方把这类"既有循环处理模糊输入、又有人为引导控制"的系统称为状态机(state machines)——LangGraph 就是用图来定义状态机的工具。

1.4 Workflow 与 Agent 的区别(官方定义)

官方文档对这两个词给出了明确区分,后面所有章节都会反复用到这两个词:

Workflow 工作流路径预先写死的系统——代码里明确规定了第一步干什么、第二步干什么,LLM 只是其中某些环节的"工人"。适合可预测、能拆成固定步骤的任务。

Agent 智能体自己决定路径的系统——LLM 在循环里自主决定"接下来调哪个工具、还要不要继续"。适合问题和解法都不可预测的开放任务。官方原话:"Agents are dynamic and define their own processes and tool usage."

用本教程的图来说:

Workflow= 路径写死的图(人画好了所有箭头)
Agent= LLM → 工具 → LLM → 工具 …的循环图(LLM 决定转几圈)

LangGraph 两者都能画,这就是它"编排框架"定位的含义。

1.5 什么时候不需要它

工具没有高低,只有合不合适。以下情形不必上 LangGraph:

需要多步骤 + 分支/循环 + 可靠性(断点恢复、人工审批、流式输出、持久记忆)时,LangGraph 就是为此而造的。

1.6 官方生态全家桶

搜资料时你会反复见到这几个名字,官方文档对它们的定位如下:

产品是什么和本教程的关系
LangGraph编排运行时:把流程画成图并执行,提供持久化、中断、流式等基础设施本教程主角
LangChainAgent 框架:提供模型接入、工具定义、create_agent 等高层抽象第 6 章起会借它的 init_chat_model、消息类型、@tool
LangSmith商业化平台:追踪调试(可视化每一步)、评估、Prompt 管理第 17 章简介,可选,不用注册也能学完本教程
Deep Agents基于 LangGraph 的更高层"全副武装"Agent 封装(自带规划、子 Agent、文件系统工具)进阶方向,见第 19 章
LangGraph Studio官方可视化调试器:在网页里看图结构、单步执行、点节点看状态第 17 章简介

记住一句话即可:LangChain 管"零件",LangGraph 管"组装和运转",LangSmith 管"监工"。它们可以分开用,LangGraph 不依赖 LangChain 也能跑(第 2 章你就会看到)。

第 02 章5 分钟跑通第一个程序

本章目标:不看懂没关系,先把一个 LangGraph 程序在你电脑上跑起来。全程不需要 API Key、不需要联网调用大模型。

2.1 准备环境(Windows 向)

  1. 确认装了 Python 3.10 或更高版本(官方要求 Python ≥ 3.10)。按 Win+R,输入 cmd 回车,在黑窗口里输入:
    cmd
    python --version
    :: 期望输出类似:Python 3.11.8(只要 ≥ 3.10 就行)
    如果提示"不是内部或外部命令",去 python.org 下载安装,安装时务必勾选 "Add Python to PATH",然后重新打开一个 cmd 窗口再试。
  2. 建一个项目文件夹(可选但推荐,避免装包污染全局)。在 cmd 里执行:
    cmd
    mkdir C:\lg_demo
    cd C:\lg_demo
    python -m venv venv          :: 创建虚拟环境(一个干净的包安装沙箱)
    venv\Scripts\activate        :: 激活它,成功后命令行前面会出现 (venv)
  3. macOS / Linux 用户的对应写法:python3 -m venv venv && source venv/bin/activate。

2.2 安装 langgraph

激活虚拟环境后(或者你选择不建虚拟环境也可以),执行官方 README 给出的安装命令:

bash
pip install -U langgraph
:: 也可以用 uv(更快的现代包管理器):uv add langgraph

装完后验证一下:

bash
pip show langgraph
:: 关注 Version 一行,应当是 1.x.x(本教程写作时最新为 1.2.11)
💡 只有 langgraph 就够了吗?是的——第 2~5 章只需要 langgraph 这一个包。LangGraph 核心不依赖 LangChain,你可以把任意普通 Python 函数放进节点里。从第 6 章开始才需要 pip install -U langchain(用于接入各家大模型)。

2.3 第一个图:完整代码

在 C:\lg_demo 文件夹里新建一个文件 first_graph.py,粘贴以下全部内容(这段代码改编自官方 Overview 页的示例,为了方便观察加了打印语句):

python · first_graph.py
# -*- coding: utf-8 -*-
# first_graph.py —— 你的第一个 LangGraph 程序

# 第 1 步:从 langgraph 包里导入需要的东西
from langgraph.graph import StateGraph, START, END
from typing_extensions import TypedDict

# 第 2 步:定义"状态"(State)——整张图共享的一块白板
class State(TypedDict):
    message: str        # 白板上有一个格子,叫 message,类型是字符串

# 第 3 步:定义"节点"(Node)——就是普通的 Python 函数
def say_hello(state: State):
    print(">>> 节点 say_hello 干活了!它拿到的白板是:", state)
    return {"message": state["message"] + ",我是节点,我处理过了!"}

# 第 4 步:把图搭起来
builder = StateGraph(State)          # 造一个"空白流程图",告诉它白板格式是 State
builder.add_node("hello", say_hello) # 往图上放一个节点,名叫 hello,由 say_hello 函数干活
builder.add_edge(START, "hello")     # 画一条边:流程从起点 START 出发,先到 hello
builder.add_edge("hello", END)       # 再画一条边:hello 干完活,流程结束(END)

# 第 5 步:编译并运行
graph = builder.compile()            # 图必须"编译"一次才能用
result = graph.invoke({"message": "大家好"})   # 递给图一个初始白板,启动!
print("最终白板:", result)

运行:

bash
python first_graph.py
输出 · 你应当看到
>>> 节点 say_hello 干活了!它拿到的白板是: {'message': '大家好'}
最终白板: {'message': '大家好,我是节点,我处理过了!'}

🎉 恭喜!你已经跑通了第一个 LangGraph 程序。它虽然没接大模型,但骨架和真实生产级 Agent 一模一样:状态 → 节点 → 边 → 编译 → 调用。后面十几章学的一切,都是往这副骨架上加东西。

2.4 逐行拆解每一句

代码人话解释
from langgraph.graph import StateGraph, START, ENDStateGraph 是搭图的主类;START 是图的虚拟入口(不是真节点),END 是虚拟出口。三者都从 langgraph.graph 导入。
class State(TypedDict)TypedDict 是 Python 的"带类型说明的字典"。它运行时不强制校验,只是给人和 IDE 看的说明书:"白板上应该有哪些格子、各是什么类型"。你也可以用 dataclass 或 Pydantic(见 4.4 节)。
def say_hello(state: State):节点就是一个普通函数。约定:接收整个 state,返回一个字典。返回的字典表示"我要更新白板上的哪些格子",不必返回全部格子。
return {"message": ...}只汇报自己改动的部分。LangGraph 会自动把它合并回白板(怎么合并由 Reducer 决定,第 4 章专讲)。
builder = StateGraph(State)创建图构建器,参数是 State 类——告诉 LangGraph 白板长什么样。
builder.add_node("hello", say_hello)注册节点。第一个参数是节点名(图里的唯一 ID,画边时用它指代),第二个参数是干活的函数。小技巧:如果节点名就是函数名,可以只写 builder.add_node(say_hello)。
builder.add_edge(START, "hello")普通边:固定顺序。"流程从入口到 hello"。
graph = builder.compile()编译:做结构检查(比如发现节点没连线会提醒你),生成可执行对象。不编译就调用会直接报错。
graph.invoke({"message": "大家好"})启动图。参数就是白板的初始内容(一个普通字典)。返回值是最终白板。
📖 一图记住本章
invoke 初始白板→ START→ 节点 say_hello
读白板 → 干活 → 汇报改动
→ END · 返回最终白板

2.5 常见报错排查表

报错(关键词)原因解决
ModuleNotFoundError: No module named 'langgraph'装到了别的 Python 环境,或忘了激活虚拟环境确认命令行前面有 (venv) 再 pip install -U langgraph
ValueError: ... must be compiled before use 类似提示没调用 compile() 就 invoke 了 builder补上 graph = builder.compile()
中文输出乱码(Windows cmd)cmd 默认编码 GBK先执行 chcp 65001 再运行脚本,或改用 Windows Terminal / VSCode 终端
TypeError: 'str' object is not callable 等add_node 传了字符串而不是函数,或把函数名写错检查 add_node("名字", 函数对象) 两个参数
节点好像没执行忘了 add_edge(START, "节点名")——没有任何边指向它,图不知道从它开始编译时 LangGraph 会对孤立节点告警,注意看警告信息

第 03 章三大积木:State / Node / Edge

官方文档说,LangGraph 用图来建模 Agent 工作流,包含三个核心组件:State(共享数据结构,应用当前快照)、Node(编码逻辑的函数)、Edge(决定下一个执行哪个 Node)。官方一句话总结:"nodes do the work, edges tell what to do next"——节点干活,边告诉你接下来干嘛。

3.1 心智模型:便利贴墙

把整张图想象成一间办公室的便利贴墙:

3.2 State:全图共享的白板

State 是一个普通的 Python 类型定义(TypedDict / dataclass / Pydantic 皆可),它回答一个问题:"整个流程过程中,我们需要记住哪些东西?"

设计 State 就是在回答"我需要哪些格子"。比如做"文章生成器":

python
from typing_extensions import TypedDict

class ArticleState(TypedDict):
    topic: str          # 主题:用户一进来就定死
    outline: str        # 大纲:第一个节点生成
    draft: str          # 初稿:第二个节点生成
    reviews: list[str]  # 审稿意见:可能有多个审稿节点都往里写
💡 什么该放进 State?官方《Thinking in LangGraph》的建议:跨步骤要用、或重新获取成本高的数据才放进 State;能随时推导出来的不要放。并且"存原始数据,不要存格式化文本"——原始数据各节点可以按需加工,格式化文本换个节点就没法用了。详见 12 章前的最佳实践小结和第 18 章 FAQ#7。

3.3 Node:干活的函数

节点是普通的同步或异步 Python 函数,官方文档规定它可以接收三类参数(后两个可选):

python
from dataclasses import dataclass
from langgraph.runtime import Runtime

# 参数一(必有):state —— 当前整块白板
def plain_node(state: State):
    return state                      # 原样返回 = 什么都不改(合法但无意义)

# 参数二(可选):config —— 运行配置,含 thread_id(第 9 章会用到)
# 参数三(可选):runtime —— 运行时对象,含 context / store / stream_writer
@dataclass
class Context:                        # 自定义"上下文"类型(比如当前用户是谁)
    user_id: str

def node_with_runtime(state: State, runtime: Runtime[Context]):
    print("当前用户:", runtime.context.user_id)
    return {"results": f"Hello, {state['input']}!"}

三条节点铁律(现在记住,能少踩 90% 的坑):

  1. 只返回要改动的格子,返回字典如 {"draft": "……"},不要把整个 state 原样返回后再乱改。
  2. 不要修改传入的 state 再返回它——正确姿势是返回"新的值",让 LangGraph 负责合并。
  3. 节点应尽量"幂等"(同一个节点跑两次不产生坏后果)。因为启用了存档(第 9 章)后,恢复执行会从节点开头重跑,有副作用的操作(发邮件、写数据库)要设计成可重试。
📖 你可能想问"节点函数会被转成 RunnableLambda",自动获得批量调用、异步支持与追踪能力——这是官方文档的原文,意思是你的普通函数被 LangGraph 包了一层增强,你不用管,知道有这回事就行。

3.4 Edge:决定下一步走哪

边有四种,先记前两种,后两种是它们的入口变体:

边的种类写法含义
入口边add_edge(START, "a")开工先去节点 a
普通边add_edge("a", "b")a 干完固定去 b
条件边add_conditional_edges("a", 路由函数)a 干完后,由路由函数看白板决定去哪(第 5 章专讲)
条件入口add_conditional_edges(START, 路由函数)开工就去哪都由路由函数决定

还有两个特殊"地点":START(开工)与 END(收工)。走向 END 用普通边或条件边都可以:add_edge("a", END) 或路由函数返回 END。

⚠️ 官方警告:一个节点只能用一种"指路方式"如果一个节点既连了静态普通边、又连了条件边或用 Command 指路,LangGraph 无法判断听谁的,会产生混乱。选定一种路由风格后就保持一致。

3.5 compile 编译与 invoke 调用

compile() 做三件事:①结构检查(孤立节点、非法连线等);②把你的 Python 函数包装成标准可执行单元;③接收运行时配件——存档器 checkpointer、断点、缓存都在这里传入(后面章节会看到)。编译后的 graph 是一个标准 Runnable,拥有 invoke(同步调用)、stream(流式调用)、ainvoke(异步调用)等统一方法。

python
graph = builder.compile()                 # 最简编译
graph = builder.compile(checkpointer=...) # 带存档编译(第 9 章)

result = graph.invoke({"message": "hi"})              # 跑一次,拿最终白板
for chunk in graph.stream({"message": "hi"}):         # 边跑边吐结果(第 11 章)
    print(chunk)

3.6 执行模型:super-step 超步

这一节是理解并行的钥匙。LangGraph 的执行算法来自 Google 的 Pregel 论文(官方 README 明确写明灵感来源),核心叫 super-step(超步):

  1. 图按"超步"一拍一拍地走,就像时钟滴答滴答。
  2. 同一拍被点到的所有节点,并行执行(比如 START 同时射出三条边 → 三个节点在同一拍同时干活)。
  3. 一拍内所有节点干完 → 它们的"汇报"统一合并到白板 → 进入下一拍。
  4. 走到 END 且没有节点可执行 → 图停止。

所以并行不需要你写任何多线程代码——只要一个节点有多条出边(或入口多条出边),LangGraph 自动并行。并行节点同时改白板同一格怎么办?这正是第 4 章 Reducer 要解决的问题(答案:Annotated + 合并函数)。

3.7 动手练习:三步流程图

不看答案,自己写一个:节点 1 生成主题 → 节点 2 生成口号 → 节点 3 汇总输出。写完再对答案:

python · practice3.py
from langgraph.graph import StateGraph, START, END
from typing_extensions import TypedDict

class State(TypedDict):
    topic: str
    slogan: str
    final: str

def make_topic(state: State):
    return {"topic": "冰淇淋"}                    # 只写自己负责的格子

def make_slogan(state: State):
    return {"slogan": state["topic"] + "万岁!"}  # 读别人的格子,写自己的格子

def combine(state: State):
    return {"final": f"主题《{state['topic']}》口号:{state['slogan']}"}

builder = StateGraph(State)
builder.add_node(make_topic)      # 节点名默认就是函数名 "make_topic"
builder.add_node(make_slogan)
builder.add_node(combine)
builder.add_edge(START, "make_topic")
builder.add_edge("make_topic", "make_slogan")
builder.add_edge("make_slogan", "combine")
builder.add_edge("combine", END)

print(builder.compile().invoke({"topic": "", "slogan": "", "final": ""}))
# {'topic': '冰淇淋', 'slogan': '冰淇淋万岁!', 'final': '主题《冰淇淋》口号:冰淇淋万岁!'}
💡 自查问题(能答上就继续往下学)① 节点之间怎么传数据?(答:通过共享 State,节点返回要改动的格子)② add_node(make_topic) 为什么不用起名?(答:默认用函数名)③ 如果 combine 返回 {"final": ...},白板上 topic 会丢吗?(答:不会,返回值只更新提到的格子)

第 04 章State 深入:Reducer 是灵魂

Reducer(归约器)是 LangGraph 最容易被新手忽略、又最能解释一切"灵异现象"的知识点。学完本章,你就明白为什么消息列表会自动追加、为什么并行节点会报错、为什么有人要清空一个列表却清不掉。

4.1 默认行为:直接覆盖

先说结论:State 里每个格子(key)都配有一个"合并规则",叫 Reducer。你什么都不写时,规则是"后写的覆盖先写的"。

python
from langgraph.graph import StateGraph, START, END
from typing_extensions import TypedDict

class State(TypedDict):
    foo: int           # 没有 Reducer → 覆盖
    bar: list[str]     # 没有 Reducer → 覆盖(哪怕它是列表!)

def node_a(state: State):
    return {"foo": 1, "bar": ["a"]}

builder = StateGraph(State)
builder.add_node(node_a)
builder.add_edge(START, "node_a")
builder.add_edge("node_a", END)
print(builder.compile().invoke({"foo": 0, "bar": []}))
# {'foo': 1, 'bar': ['a']}   ← bar 整个被替换成了 ['a'],不是追加

官方文档给出的心智公式是:新值 = reducer(旧值, 节点返回值)。默认 Reducer 就是"丢弃旧值、保留新值"。

4.2 Annotated reducer:合并

想让"多次写入累加起来"(典型场景:消息列表、日志、多人投票),就用 Annotated 给格子挂一个合并函数:

python
from operator import add
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    foo: int
    bar: Annotated[list[str], add]   # ← 给 bar 挂上"列表相加"规则(就是 list 拼接)

def node_a(state: State):
    return {"bar": ["a"]}

def node_b(state: State):
    return {"bar": ["b"]}

builder = StateGraph(State)
builder.add_node(node_a)
builder.add_node(node_b)
builder.add_edge(START, "node_a")
builder.add_edge("node_a", "node_b")   # a 干完接 b
builder.add_edge("node_b", END)
print(builder.compile().invoke({"foo": 0, "bar": []}))
# {'foo': 0, 'bar': ['a', 'b']}   ← ['a'] + ['b'] = ['a','b'],累加成功!

Annotated[list[str], add] 读作:"这个格子是字符串列表;多人写它时,用 add(即 旧 + 新)合并"。任何接收两个参数、返回合并结果的函数都能当 Reducer,比如:

python
def merge_dicts(left: dict, right: dict) -> dict:
    return {**left, **right}          # 后写的键覆盖,其余保留

class State(TypedDict):
    scores: Annotated[dict, merge_dicts]   # 多个节点各写一部分评分,自动合并
🚨 第 4 章最重要的坑:并行写无 Reducer 的格子 回忆 3.6 节:一个节点有多条出边时,目标节点同一拍并行执行。如果两个并行节点同时往没有 Reducer 的格子里写,LangGraph 无法裁决谁后谁先,会抛出 InvalidUpdateError(invalid concurrent graph update,并发更新非法)。解法只有一个:给共享格子加 Reducer。这个报错详见第 17 章错误表。

4.3 add_messages 与 MessagesState

做对话应用时,messages(消息列表)是最常用的格子,官方专门提供了内置 Reducer add_messages:

python
from typing import Annotated
from typing_extensions import TypedDict
from langchain.messages import AnyMessage
from langgraph.graph.message import add_messages

class GraphState(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]

add_messages 比普通列表拼接聪明两点(官方文档说明):

因为"带消息列表的 State"太常用了,官方预置了 MessagesState——它就是一个已经写好 messages: Annotated[list[AnyMessage], add_messages] 的现成 State 类,你直接继承它再加自己的格子即可:

python
from langgraph.graph import MessagesState

class State(MessagesState):      # 自带 messages 格子(含 add_messages reducer)
    documents: list[str]         # 按需追加自己的格子

4.4 Pydantic 版 State(带校验)

TypedDict 只是"说明书",运行时不校验数据。若希望自动校验每个字段(类型错就报错、缺省值、字段约束),官方文档给出的选项是用 Pydantic 的 BaseModel:

python
from pydantic import BaseModel, Field
from operator import add
from typing import Annotated

class State(BaseModel):
    topic: str = Field(..., min_length=1)          # 必填且非空
    reviews: Annotated[list[str], add] = []        # Reducer 照样能用(写在 Annotated 里)
    score: int = 0                                 # 默认值
📖 三种 Schema 怎么选(官方文档口径) TypedDict:主要推荐方式,轻量零依赖。dataclass:需要默认值、想要属性访问时。Pydantic BaseModel:需要递归数据校验时——代价是性能较差(每次更新都要做校验)。教程正文统一用 TypedDict,需要校验时换 Pydantic 即可,其余写法完全相同。

4.5 Overwrite:强制清空

一个反直觉的场景:格子挂了"合并"Reducer 后,返回空列表不会清空它——["a","b"] + [] 还是 ["a","b"]!那想清空怎么办?官方提供了专门的 Overwrite 类型,它的意思是"绕过 Reducer,直接替换":

python
from langgraph.types import Overwrite

def clear_errors(state: State):
    return {"errors": Overwrite([])}   # 强制把 errors 清成 [],而不是 [] 拼接上去

4.6 输入 / 输出 / 私有 Schema

进阶技巧:State 里的某些格子只想让"中间节点"用,不想暴露给调用者(输入输出)。官方支持给图分别指定输入 Schema、输出 Schema,中间的完整 State 对外不可见:

python · 官方文档示例
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END

class InputState(TypedDict):        # 调用者需要提供什么
    user_input: str

class OutputState(TypedDict):       # 调用者能拿到什么
    graph_output: str

class OverallState(TypedDict):      # 图内部真正使用的完整白板
    foo: str
    user_input: str
    graph_output: str

def node_1(state: InputState) -> OverallState:      # 参数类型声明"我只读 user_input"
    return {"foo": state["user_input"] + " name"}

def node_2(state: OverallState) -> dict:            # 内部节点:foo → bar(对外不可见)
    return {"bar": state["foo"] + " is"}

def node_3(state: OverallState) -> OutputState:     # 返回类型声明"我只产出 graph_output"
    return {"graph_output": state["bar"] + " Lance"}

builder = StateGraph(
    OverallState,
    input_schema=InputState,     # ← 对外的入口格式
    output_schema=OutputState,   # ← 对外的出口格式
)
builder.add_node("node_1", node_1)
builder.add_node("node_2", node_2)
builder.add_node("node_3", node_3)
builder.add_edge(START, "node_1")
builder.add_edge("node_1", "node_2")
builder.add_edge("node_2", "node_3")
builder.add_edge("node_3", END)

graph = builder.compile()
print(graph.invoke({"user_input": "My"}))   # {'graph_output': 'My name is Lance'}
# 注意:输入只有 user_input,输出只有 graph_output,中间的 foo / bar 对外不可见
💡 用在哪里?两个典型场景:① 第 13 章子图——子图与父图字段不同,靠输入/输出 Schema 做干净的"接口";② 团队协作——中间状态的格子(如检索原文、调试日志)不污染对外 API。另外官方提醒:私有格子不会被流式自动隐藏,需要时用 stream_mode="updates" 或指定 output_keys。

第 05 章条件边:让图学会拐弯

普通边是"死脑筋",条件边是"活脑筋"——干完一步后,由一个函数看一眼白板,决定接下来去哪。这是 LangGraph 表达"if/else"和"循环"的核心机制。

5.1 条件边基本写法

python
graph.add_conditional_edges("node_a", routing_function)          # 基础版
graph.add_conditional_edges("node_a", routing_function,
                            {True: "node_b", False: "node_c"})   # 带映射版

两个要素:① 从哪个节点出发;② 路由函数——一个接收 state、返回"目标节点名"(或可映射成节点名的值)的函数。映射字典版的好处:路由函数只需返回 True/False 或 "poem" 这类语义值,由字典翻译成真正的节点名,逻辑更清晰。

5.2 路由函数的三种返回

返回形式示例效果
节点名(单个)return "tool_node" / return END去一个地方
可映射的值return "poem"(配映射 {"poem": "llm_call_1"})经字典翻译后去对应节点
列表return ["a", "b", "c"]同时去多个节点 → 它们下一拍并行执行(3.6 节的超步并行)

还有第四种"返回 Send(...) 对象"的写法,功能更强(每个分支还能带不同的输入数据),放到第 8.4 节配合"编排者-执行者"模式一起讲。

⚠️ 路由函数 vs 节点函数路由函数只读白板、不写白板,返回值是"去向"而不是状态更新。它没有资格 return {"foo": ...}。想"边改状态边决定去向",用第 14 章的 Command。

5.3 实战:智能客服路由

完整可运行的例子(依旧不需要 API Key——用关键词模拟"大模型分类",真实场景把 fake_classify 换成 LLM 调用即可,第 8.3 节会给出真实版):

python · router_demo.py
from langgraph.graph import StateGraph, START, END
from typing_extensions import TypedDict, Literal

class State(TypedDict):
    question: str
    answer: str

# --- 三个"业务节点":退款、物流、通用 ---
def refund_node(state: State):
    return {"answer": f"【退款专员】已受理:{state['question']}"}

def logistics_node(state: State):
    return {"answer": f"【物流专员】查询中:{state['question']}"}

def general_node(state: State):
    return {"answer": f"【小助手】我试试回答:{state['question']}"}

# --- 路由函数:只读白板,返回节点名 ---
def route_question(state: State) -> Literal["refund", "logistics", "general"]:
    q = state["question"]
    if "退款" in q or "退货" in q:
        return "refund"
    if "快递" in q or "物流" in q:
        return "logistics"
    return "general"

builder = StateGraph(State)
builder.add_node("refund", refund_node)
builder.add_node("logistics", logistics_node)
builder.add_node("general", general_node)

builder.add_conditional_edges(START, route_question, {   # 开工就分流
    "refund": "refund",
    "logistics": "logistics",
    "general": "general",
})
for n in ["refund", "logistics", "general"]:
    builder.add_edge(n, END)

graph = builder.compile()
print(graph.invoke({"question": "我要退款!", "answer": ""})["answer"])
# 【退款专员】已受理:我要退款!
print(graph.invoke({"question": "快递到哪了", "answer": ""})["answer"])
# 【物流专员】查询中:快递到哪了

注意三个细节:① 函数签名里的返回类型注解 -> Literal[...] 不是必须的,但官方文档推荐写上,IDE 补全和图渲染(第 17 章)都会受益;② 入口条件边意味着本图没有唯一的 START 节点;③ 三个分支都汇到 END,互不干扰。

💡 练习把本例改成"先经过 classify 节点(把分类结果写进 State),再用条件边从 classify 出发"的结构,体会"入口路由"与"中途路由"的区别。真实 LLM 版分类写法见 8.3 节。

第 06 章接入真正的大模型

从本章开始接真模型。负责"跟各家模型说话"的是 LangChain 生态(LangGraph 本身不管这个),所以要先装 langchain。

6.1 init_chat_model 与 API Key

官方 Quickstart 现在统一推荐用 init_chat_model——一个函数通吃各家模型,换厂商只改一个字符串:

bash
pip install -U langchain langchain-openai
:: 用 Anthropic Claude 则装 langchain-anthropic;用 DeepSeek 装 langchain-deepseek
:: 国产模型大多提供 OpenAI 兼容接口,用 langchain-openai 也能接(见下方 openai_api_base 写法)
python
from langchain.chat_models import init_chat_model

# 方式一:官方 Quickstart 原版(Anthropic Claude)
llm = init_chat_model("anthropic:claude-sonnet-4-5", temperature=0)

# 方式二:OpenAI 系(GPT / 各种 OpenAI 兼容接口,如 DeepSeek、通义、月之暗面)
llm = init_chat_model(
    "openai:deepseek-chat",                  # "厂商:模型名"
    temperature=0,
    api_key="sk-...",                        # 或走环境变量
    base_url="https://api.deepseek.com",     # 兼容服务改这里
)

API Key 推荐环境变量而不是写死在代码里(避免不小心上传到 GitHub 泄露):

cmd(Windows,永久生效)
setx ANTHROPIC_API_KEY "sk-ant-xxxx"
setx OPENAI_API_KEY "sk-xxxx"
:: 设置完要【重开】cmd / VSCode 窗口才生效
bash(macOS / Linux)
export ANTHROPIC_API_KEY="sk-ant-xxxx"   # 写进 ~/.bashrc 或 ~/.zshrc 永久生效
python · 先验证模型通了没
print(llm.invoke("用一句话介绍你自己").content)

6.2 消息类型:Human / AI / System / Tool

对话在 LangChain 体系里是消息列表,四种基本角色(都在消息模块里,LangGraph 的 MessagesState 存的就是它们):

类型谁在说例子
SystemMessage导演(幕后指令,模型最听它的话)"你是一个严谨的数学助手"
HumanMessage用户"3 加 4 等于几?"
AIMessage模型"7"。特殊能力:可以携带 tool_calls(点菜)
ToolMessage工具的执行结果回传"计算结果:7"

备注:旧教程里这些类常从 langchain_core.messages 导入,LangChain 1.0 起官方推荐 langchain.messages,两者指向同一批类。

python
from langchain.messages import SystemMessage, HumanMessage

messages = [
    SystemMessage(content="你是一个简洁的数学助手。"),
    HumanMessage(content="3 加 4 等于几?"),
]
resp = llm.invoke(messages)
print(resp.content)          # 模型回复文本
# 上一节说过:state["messages"][-1].content —— 最后一条消息的文本,就这么读

6.3 bind_tools:让模型会"点菜"

大模型自己只会说话,不会算数、不会查库、不会发邮件。工具(Tool)就是你给它的"外挂技能"。流程分三步:

  1. 用 @tool 定义工具:一个普通函数 + 必须写 docstring(模型靠它理解这个工具干嘛用、什么时候用!):
    python
    from langchain.tools import tool
    
    @tool
    def add(a: float, b: float) -> float:
        """计算两个数字的和。当用户要求加法时使用。"""   # ← 这行 docstring 极其重要
        return a + b
    
    @tool
    def multiply(a: float, b: float) -> float:
        """计算两个数字的乘积。当用户要求乘法时使用。"""
        return a * b
    
    @tool
    def divide(a: float, b: float) -> float:
        """计算 a 除以 b。当用户要求除法时使用。"""
        if b == 0:
            raise ValueError("除数不能为零")       # 报错信息会回传给模型,它会自己调整
        return a / b
  2. 把工具"绑"到模型上:告诉模型"你有哪些菜可以点":
    python
    tools = [add, multiply, divide]
    llm_with_tools = llm.bind_tools(tools)   # 返回一个"知道这些工具"的模型副本
  3. 看模型怎么"点菜"并替它执行:模型不会真的执行工具!它只是在回复里带上 tool_calls(点了什么菜、参数是什么),真正执行的是你的代码:
    python
    resp = llm_with_tools.invoke([HumanMessage(content="帮我算 3 加 4")])
    print(resp.tool_calls)
    # [{'name': 'add', 'args': {'a': 3.0, 'b': 4.0}, 'id': 'call_xxx', ...}]
    #                              ↑ 模型把自然语言翻译成了函数调用参数!
    
    # 替它执行(现在手写,第 7 章会封装成 tool_node 节点):
    tool_map = {t.name: t for t in tools}
    result = tool_map["add"].invoke({"a": 3.0, "b": 4.0})
    print(result)   # 7.0
📖 一句话总结本章模型收到消息列表 → 要么直接回答 → 要么回一个 tool_calls 点菜单 → 你的代码执行工具、把结果包成 ToolMessage 追加回消息列表 → 再问模型 → 直到它不再点菜。这个"点菜-上菜-再问"的循环,就是下一章的主角。

第 07 章实战:从零手写 ReAct Agent

这是本教程的"毕业项目":把前面学的 State、Node、Edge、条件边、消息列表全部用上,手写一个能调用计算器工具的真 Agent。代码改编自官方 Quickstart 的计算器 Agent,逐段拆解。

7.1 Agent 的本质:一个循环

官方《Workflows and Agents》定义:Agent = LLM + 工具,在反馈循环里运行。画成图只有两个节点、一条回边:

START→ llm_call
模型看消息,要么回答要么点菜
→有菜→ tools
执行工具,结果回消息列表
→回到 llm_call(循环!) 没菜?→ END

那个"有菜没菜"的岔路口,就是我们第 5 章学的条件边。所谓 Agent,就是一张会转圈的图——这正是第 1 章说的"链条不能转圈,所以需要 LangGraph"。

7.2 完整代码(可复制运行)

新建 agent.py,这是完整程序(基于官方 Quickstart,把状态加上 llm_calls 计数器以方便观察):

python · agent.py
# -*- coding: utf-8 -*-
from langchain.tools import tool
from langchain.chat_models import init_chat_model
from langchain.messages import (
    AnyMessage, SystemMessage, ToolMessage, HumanMessage,
)
from langgraph.graph import StateGraph, START, END
from typing_extensions import TypedDict
from operator import add
from typing import Annotated

# ============ ① 工具与模型 ============
@tool
def add(a: float, b: float) -> float:
    """计算两个数字的和。当用户要求加法时使用。"""
    return a + b

@tool
def multiply(a: float, b: float) -> float:
    """计算两个数字的乘积。当用户要求乘法时使用。"""
    return a * b

@tool
def divide(a: float, b: float) -> float:
    """计算 a 除以 b。当用户要求除法时使用。"""
    if b == 0:
        raise ValueError("除数不能为零")
    return a / b

tools = [add, multiply, divide]
tool_map = {t.name: t for t in tools}
llm = init_chat_model("anthropic:claude-sonnet-4-5", temperature=0)
llm_with_tools = llm.bind_tools(tools)

# ============ ② 状态 ============
class MessagesState(TypedDict):
    messages: Annotated[list[AnyMessage], add]   # 追加式合并
    llm_calls: int                               # 记录模型被调用了几次

# ============ ③ 节点一:调模型 ============
def llm_call(state: MessagesState):
    messages = [
        SystemMessage(
            content="你是一个乐于助人的助手,负责对一组输入执行算术运算。"
        )
    ] + state["messages"]
    response = llm_with_tools.invoke(messages)
    return {
        "messages": [response],          # 把模型回复追加进消息列表
        "llm_calls": state["llm_calls"] + 1,
    }

# ============ ④ 节点二:执行工具 ============
def tool_node(state: MessagesState):
    last = state["messages"][-1]          # 最新一条 = 模型的点菜单
    results = []
    for tc in last.tool_calls:            # 可能一次点了多道菜
        result = tool_map[tc["name"]].invoke(tc["args"])
        results.append(ToolMessage(
            content=str(result),
            tool_call_id=tc["id"],        # ← 必须带上:告诉模型这是哪道菜的结果
        ))
    return {"messages": results}          # 追加进消息列表

# ============ ⑤ 条件边:还点菜吗? ============
def should_continue(state: MessagesState) -> str:
    last = state["messages"][-1]
    if last.tool_calls:                   # 模型又点了菜 → 去执行
        return "tool_node"
    return END                            # 没点菜 → 说明它给出最终答案了

# ============ ⑥ 组装 ============
builder = StateGraph(MessagesState)
builder.add_node("llm_call", llm_call)
builder.add_node("tool_node", tool_node)
builder.add_edge(START, "llm_call")
builder.add_conditional_edges("llm_call", should_continue, ["tool_node", END])
builder.add_edge("tool_node", "llm_call")     # ← 这条回边就是"循环"!
graph = builder.compile()

# ============ ⑦ 运行 ============
messages = [HumanMessage(content="先算 3 加 4,再把结果乘以 2,最后除以 7。")]
final = graph.invoke({"messages": messages, "llm_calls": 0})
print("模型一共被调用次数:", final["llm_calls"])
for m in final["messages"]:
    m.pretty_print()   # 漂亮地打印每条消息

7.3 逐段拆解每一块

代码块讲解
② MessagesState消息格子挂了 add(列表拼接)。官方 Quickstart 原版用的是 add_messages(更聪明:按 ID 去重更新、自动转消息对象),两者对 Agent 都可用;实战推荐 add_messages。
③ llm_call开头拼一条 SystemMessage 设定人设,然后把整个历史消息列表喂给模型。注意它返回 {"messages": [response]}——只返回新增的一条,拼接交给 Reducer。这就是"节点之间靠白板通信"的实战形态。
④ tool_node遍历 last.tool_calls(可能并行点好几道菜),逐个执行;每个结果必须带 tool_call_id,否则模型不知道哪句回答对应哪道菜,下一轮直接报错(高频坑,见 FAQ#12)。更省事的官方预制件是 ToolNode(自动处理并行工具、错误处理),见 8.4 节。
⑤ should_continue读最后一条消息:有 tool_calls 就去 tool_node,没有就 END。Agent"知道什么时候停"的全部秘密就这么一行 if。
⑥ 组装add_conditional_edges("llm_call", should_continue, ["tool_node", END]) 第三参数用列表形式声明"可能的去向"(便于图渲染);tool_node → llm_call 这条普通边画出循环。官方文档同时提醒:每个节点只用一种路由机制——llm_call 的去向全交给条件边,就不再给它连普通边。
⑦ 运行一次 invoke 内部,图会自动转好几圈(算 3+4 → 回看 → ×2 → 回看 → ÷7 → 回答),你只管拿最终结果。

7.4 运行结果走一遍

输出 · 大致长这样(措辞随模型略有差异)
模型一共被调用次数: 4
================================== Ai Message ==================================
Tool Calls:
  add (call_1)
 Call ID: call_1
  Args:
    a: 3.0
    b: 4.0
================================= Tool Message =================================
7.0
================================== Ai Message ==================================
Tool Calls:
  multiply (call_2)
 Call ID: call_2
  Args:
    a: 7.0
    b: 2.0
================================= Tool Message =================================
14.0
================================== Ai Message ==================================
Tool Calls:
  divide (call_3)
 Call ID: call_3
  Args:
    a: 14.0
    b: 7.0
================================= Tool Message =================================
2.0
================================== Ai Message ==================================
3 加 4 等于 7;乘以 2 得 14;再除以 7,最终答案是 2。

对照输出理解循环:模型第 1 次被调用点菜 add → 工具节点执行回传 → 第 2 次被调用看到结果又点菜 multiply → …… → 第 4 次被调用时所有中间结果都在消息列表里了,它不再点菜,条件边把你送到 END。Agent 的"自主性"就体现在:步骤顺序、要不要继续,全是模型每看一眼白板临时决定的。

7.5 recursion_limit:防止死循环

循环是把双刃剑:模型若一直点菜(或你的条件边写错永远回不到 END),图会转圈到天荒地老、烧光你的 API 余额。LangGraph 的保险丝是 recursion_limit(递归上限)——图最多执行多少个超步,1.0.6 版起默认 1000。超限抛 GraphRecursionError:

python
from langgraph.errors import GraphRecursionError
try:
    graph.invoke(inputs, config={"recursion_limit": 25})   # 注意:顶层 key,不进 configurable
except GraphRecursionError:
    print("转了 25 拍还没收敛,强制叫停")

官方推荐的"主动式"做法:把剩余步数放进 State,让条件边自己提前收手(比被动等报错优雅):

python · 官方文档示例
from langgraph.managed import RemainingSteps

class State(TypedDict):
    messages: Annotated[list, add]
    remaining_steps: RemainingSteps     # 托管值:LangGraph 自动填充剩余步数

def route_decision(state: State):
    if state["remaining_steps"] <= 2:   # 快到上限了 → 见好就收
        return END
    return "agent"

7.6 懒人版:一行 create_agent

上面手写的"模型-工具循环"是如此经典,官方把它封装成了一行 API。注意版本变化:LangGraph 1.0 起,老教程里的 langgraph.prebuilt.create_react_agent 已弃用,由 LangChain 1.0 的 create_agent 接替(迁移 issue #6062 确认):

bash
pip install -U langchain        # create_agent 在 langchain 1.0 里
python
from langchain.agents import create_agent

agent = create_agent(
    model="anthropic:claude-sonnet-4-5",   # 或直接传上面 init 的 llm
    tools=[add, multiply, divide],
    system_prompt="你是一个算术助手。",
)
result = agent.invoke(
    {"messages": [{"role": "user", "content": "3 加 4 再乘 2"}]}
)
print(result["messages"][-1].content)

它返回的就是一个编译好的 LangGraph 图——所以第 9 章的存档、第 10 章的人工审批、第 11 章的流式,全部原样适用于它;它也可以作为节点塞进更大的图(子图,第 13 章)。建议:先跟本教程手写一遍理解原理,日常开发用 create_agent 省事,两者要切换自如。

第 08 章五大工作流模式(官方推荐)

官方文档《Workflows and Agents》总结了五种最常用的 Workflow 模式。它们是搭任何复杂系统的"标准积木"——先用小例子吃透,再拼装成自己的系统。每种模式都给出图结构和关键代码。

8.1 模式一:提示链(Prompt Chaining)

思路:任务拆成固定几步,每步一次 LLM 调用,前一步的输出是后一步的输入;中间可以插质量检查(不达标就重做)。适合能拆分、且每步效果可验证的任务,官方举例:先写笑话 → 检查笑点是否合格 → 不合格就改进 → 最后润色。

START→ generate_joke 生成→ 检查笑点-Fail→ improve_joke 改进→ polish_joke 润色→ END
python · 官方示例骨架
workflow = StateGraph(State)
workflow.add_node("generate_joke", generate_joke)
workflow.add_node("improve_joke", improve_joke)
workflow.add_node("polish_joke", polish_joke)
workflow.add_edge(START, "generate_joke")
workflow.add_conditional_edges(                 # 生成后先"安检"
    "generate_joke", check_punchline,
    {"Fail": "improve_joke", "Pass": END},      # 不合格→改进;合格→直接结束
)
workflow.add_edge("improve_joke", "polish_joke")
workflow.add_edge("polish_joke", END)
chain = workflow.compile()

8.2 模式二:并行化(Parallelization)

思路:多路 LLM 同时开工,最后汇总。两种动机:①分而治之提速(同时翻译三个章节);②重复投票提可信度(同一问题问三次取多数)。图上怎么画并行?一个节点(或 START)连多条出边即可——3.6 节的超步机制会自动让它们并行:

python
parallel_builder.add_edge(START, "call_llm_1")   # 三条出边 = 三路同时开跑
parallel_builder.add_edge(START, "call_llm_2")
parallel_builder.add_edge(START, "call_llm_3")
parallel_builder.add_edge("call_llm_1", "aggregator")   # 都汇到汇总节点
parallel_builder.add_edge("call_llm_2", "aggregator")
parallel_builder.add_edge("call_llm_3", "aggregator")
🚨 并行必配 Reducer三个节点若往同一个结果格子里写,而该格子没有 Reducer,会直接报并发更新错误(4.2 节的坑)。标准写法:结果格子用 Annotated[list, operator.add],各节点返回 {"results": ["我这部分的结果"]} 自动拼接。

8.3 模式三:路由(Routing)

思路:先用一次 LLM 给输入分类,再按类别分流到各自的专用流程。5.3 节的关键词版升级为真 LLM 版——官方推荐用结构化输出让分类结果强制成枚举:

python · 官方示例骨架
from pydantic import BaseModel, Field
from typing import Literal

class Route(BaseModel):
    step: Literal["poem", "story", "joke"] = Field(
        ..., description="根据用户问题选择下一步类型"
    )                                  # 强制模型三选一

router = llm.with_structured_output(Route)

def llm_call_router(state: State):
    decision = router.invoke([HumanMessage(content=state["input"])])
    return {"decision": decision.step}          # 分类结果写进白板

def route_decision(state: State):
    return state["decision"]                    # 条件边读白板分发

router_builder.add_edge(START, "llm_call_router")
router_builder.add_conditional_edges(
    "llm_call_router", route_decision,
    {"llm_call_1": "llm_call_1", "llm_call_2": "llm_call_2", "llm_call_3": "llm_call_3"},
)

典型应用:客服系统(计费/退款/报修分线)、多租户 SaaS(按问题类型走不同 Agent)。

8.4 模式四:编排者-执行者(Orchestrator-Worker,含 Send API)

思路:一个"编排者"LLM 先拆任务(拆成几个事先不知道),把每个子任务派给一个"执行者"LLM,最后汇总。与 8.2 的区别:执行者数量运行时才知道——不能画死几条边,这时用官方的 Send API(map-reduce):条件边返回一串 Send 对象,每个 Send 动态开一份"子白板"给目标节点:

python · 官方示例骨架
from langgraph.types import Send

def assign_workers(state: State):
    # 编排者已把任务拆进 state["sections"](列表,长度运行时才知道)
    return [Send("llm_call", {"section": s}) for s in state["sections"]]
    #        ↑ 目标节点     ↑ 这个 worker 私有的输入(可各不相同!)

orchestrator_worker_builder.add_conditional_edges(
    "orchestrator", assign_workers, ["llm_call"]   # 声明可能的目标,便于渲染
)
# worker 的产出用 Annotated[list, operator.add] 自动汇进共享格子,再由
# "synthesizer" 节点汇总 —— 这就是"map(分发)- reduce(汇总)"
📖 Send vs 普通条件边返回列表返回 ["a","b"] 时,多个分支共享同一块白板;返回 Send("a", {...}) 时,每个分支拿到自己定制的输入(还能互不相同),汇总仍靠 Reducer 写回共享格子。子任务需要"独立输入"时用 Send——这是官方文档的说法:边数量未知、各分支需要不同 state 时。

顺带认识官方预制件 ToolNode:一个现成的工具执行节点(第 7 章手写的 tool_node 官方版),自动处理并行工具执行、错误处理、状态注入,还能让工具直接读取图状态与运行上下文:

python
from langchain.tools import tool
from langgraph.prebuilt import ToolNode

@tool
def get_user_info(runtime) -> str:                  # runtime 参数由 LangGraph 自动注入
    """查询当前用户信息。"""
    user_id = runtime.state["user_id"]              # 直接读图状态
    org_id = runtime.context.organization_id        # 直接读运行上下文
    return f"用户 {user_id} 属于组织 {org_id}"

builder.add_node("tools", ToolNode([get_user_info]))   # 一行顶第 7 章一整个 tool_node

8.5 模式五:评估者-优化者(Evaluator-Optimizer)

思路:一个 LLM 干活,另一个 LLM 挑刺,循环直到达标。适合有明确评价标准、需要反复打磨的任务(翻译、文案、代码优化)。图上就是一个带"质检回边"的循环:

python · 官方示例(Functional API 版最直观)
@entrypoint()
def optimizer_workflow(topic: str):
    feedback = None
    while True:
        joke = llm_call_generator(topic, feedback).result()   # 生成(参考上轮意见)
        feedback = llm_call_evaluator(joke).result()          # 评估(PASS / 意见)
        if feedback.grade == "funny":                          # 达标 → 收工
            break
    return joke

用 Graph API 表达同样的循环:generator → evaluator 普通边 + evaluator 条件边("Pass"→END, "Fail"→generator)。务必配合 recursion_limit(7.5 节),防止两个模型互相较劲到天荒地老。

8.6 怎么选:一张决策表

你的任务特征选哪种
能拆成固定几步,每步可验证提示链(8.1)
各部分互不依赖,想提速 / 想投票并行化(8.2)
输入类型多样,各有专用处理流程路由(8.3)
子任务数量与内容运行时才知道编排者-执行者 + Send(8.4)
有明确质量标准,需反复迭代评估者-优化者(8.5)
问题开放、步骤无法预定义别用 Workflow 了,用 Agent(第 7 章)

官方建议拿不准时用 LangSmith 把各模式的 trace 跑一遍对比效果(第 17 章)。真实系统往往是嵌套组合:比如 Agent 循环里的"工具"本身又是一个路由工作流。

第 09 章持久化:给图装上存档系统

从本章起学习 LangGraph 的"杀手锏"层能力。官方 README 说,配好 Checkpointer 后一张图自动获得五件事:多轮记忆、人工介入、时间旅行、容错恢复、可检查的中间状态。全部只加两行代码。

9.1 游戏存档式理解 Checkpointer

类比单机游戏:Checkpointer(检查点器)就是自动存档系统——图每走一拍(每个 super-step,见 3.6 节),就自动把整块白板拍一张"快照"(checkpoint)存起来。于是:

启用方式——编译时传入,调用时带上 thread_id,就这么多:

python
from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()                     # 内存版存档器(开发测试用)
graph = builder.compile(checkpointer=checkpointer) # ← 唯一的编译改动

result = graph.invoke(
    {"messages": [{"role": "user", "content": "你好,我叫小明"}]},
    {"configurable": {"thread_id": "thread-1"}},   # ← 唯一的调用改动
)

9.2 thread_id:每个对话一个存档槽

thread(线程)=一段独立对话的存档槽,thread_id 是槽位号。官方文档强调:配了 checkpointer 后调用必须带 thread_id,否则存档器不知道该读写哪个槽。它带来什么?同一个图对象、不同 thread_id、互不干扰——每个用户的会话、每张工单的处理流程,各自一条线程:

9.3 实战:有记忆的聊天机器人

python · chat_memory.py
from langchain.chat_models import init_chat_model
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.checkpoint.memory import InMemorySaver

llm = init_chat_model("openai:gpt-4o-mini", temperature=0)

def chatbot(state: MessagesState):
    # 不用自己拼历史!state["messages"] 里已经是从存档恢复的完整对话
    return {"messages": [llm.invoke(state["messages"])]}

builder = StateGraph(MessagesState)
builder.add_node("chatbot", chatbot)
builder.add_edge(START, "chatbot")
builder.add_edge("chatbot", END)

graph = builder.compile(checkpointer=InMemorySaver())
CFG = {"configurable": {"thread_id": "demo-1"}}

# 第 1 轮:告诉它名字
r1 = graph.invoke({"messages": [{"role": "user", "content": "你好,我叫小明"}]}, CFG)
print(r1["messages"][-1].content)

# 第 2 轮:同一个 thread_id —— 考考它记不记得
r2 = graph.invoke({"messages": [{"role": "user", "content": "我叫什么名字?"}]}, CFG)
print(r2["messages"][-1].content)     # → "你叫小明。"(记忆生效!)

# 换个 thread_id —— 全新存档槽,它就不知道了
r3 = graph.invoke(
    {"messages": [{"role": "user", "content": "我叫什么名字?"}]},
    {"configurable": {"thread_id": "demo-2"}},
)
print(r3["messages"][-1].content)     # → "抱歉,你还没告诉我你的名字。"

注意 chatbot 节点只做了"把当前消息列表喂给模型"一件事——历史管理全部由 checkpointer 在幕后完成,这就是第 3 章说的"节点之间靠白板通信"加上"白板会自动存档接力"。

⚠️ InMemorySaver 的记忆在内存里程序一退出就全没了!它只适合开发调试。生产要换数据库版存档器(9.6 节),代码一行不改,只换 checkpointer 对象。

9.4 Checkpoint 内部长什么样

官方文档:每个快照是一个 StateSnapshot 对象。看懂这张表,"存档"就再无神秘感:

字段含义例
values这一拍的完整白板{"messages": [...], "foo": 1}
next接下来要执行的节点。空元组 () =已到 END("node_b",)
config这张快照的"地址":thread_id + checkpoint_ns + checkpoint_id见下文 namespace 说明
metadata来源(source:input / loop / update)、本步写入(writes)、步数(step){"step": 2, ...}
created_at创建时间(ISO 8601)—
parent_config上一张快照的地址(首张为 None)——快照们由此串成一条"存档链"—
tasks本拍任务列表,含 id/name/error/interrupts——第 10 章判断"中断"就靠它—

两个重要细节(官方文档原文归纳):

9.5 get_state 与状态历史

python · 官方 API
config = {"configurable": {"thread_id": "1"}}

graph.get_state(config)          # 最新一张快照(StateSnapshot)
graph.get_state({**config, "configurable": {
    "thread_id": "1",
    "checkpoint_id": "1ef663ba-28fe-6528-8002-5a559208592c",
}})                              # 指定历史某一张

# 全部历史,按时间倒序(最新在前):
history = list(graph.get_state_history(config))
for snap in history:
    print(snap.metadata["step"], snap.next, list(snap.values.keys()))

# 三个实用筛选(官方文档示例的归纳):
next(s for s in history if s.next == ("node_b",))            # node_b 执行前的那张
next(s for s in history if s.metadata["step"] == 2)          # 按步数找
[s for s in history if s.metadata["source"] == "update"]     # update_state 产生的分叉

第 10、15 章会把 get_state 用于判断中断、把 get_state_history 用于时间旅行。

9.6 存储后端怎么选

所有存档器都实现同一个接口(BaseCheckpointSaver),即插即用。旧版教程里的 MemorySaver 就是 InMemorySaver 的旧名:

包类场景
langgraph-checkpoint(随主包装好)InMemorySaver开发 / 测试 / 本教程示例
langgraph-checkpoint-sqliteSqliteSaver / AsyncSqliteSaver本地单机,存成 .db 文件
langgraph-checkpoint-postgresPostgresSaver / AsyncPostgresSaver生产推荐
langgraph-checkpoint-mongodb / -redisMongoDBSaver / RedisSaver 等已有相应基础设施时
python · 换 Postgres 全过程
pip install langgraph-checkpoint-postgres
python
from langgraph.checkpoint.postgres import PostgresSaver

with PostgresSaver.from_conn_string(
    "postgresql://user:pass@localhost:5432/dbname"
) as checkpointer:
    checkpointer.setup()      # 首次使用:自动建表(迁移 schema),只需跑一次
    graph = builder.compile(checkpointer=checkpointer)
    # 之后一切照旧,调用仍传 {"configurable": {"thread_id": ...}}
💡 生产清单(官方故障排查页归纳)① thread_id 别超长(Postgres 列宽有限,建议 UUID 且 ≤255 字符);② 定期清理旧 checkpoint 或设保留策略(快照会无限增长);③ 子图的存档在各自的 checkpoint_ns 里,父图 get_state 默认看不到子图内部,需要时用 get_state(config, subgraphs=True)。

进阶:durability 持久化档位

存档多勤快、多较真,是可以调的(官方 checkpointers 文档)。stream / invoke 时传 durability 参数,三档:

档位行为取舍
"exit"只在图结束时存一次(成功 / 出错 / 中断)性能最好;进程中途崩溃,中间进度丢失
"async"每拍后台异步存(默认)性能与安全的平衡;极小概率丢最后一张
"sync"每拍同步存完才进下一拍最可靠;有性能开销
python
graph.stream({"input": "test"}, durability="sync")   # 关键业务可调高一档

第 10 章Human-in-the-loop 人工介入

真 Agent 不能"放手就跑":删除数据库、发送邮件这类高危动作,必须人来点头。LangGraph 的 interrupt() 让图在任意位置"喊暂停",等人批复后再"续播"——而且可以等几秒,也可以等三天。

10.1 interrupt():喊一声"暂停"

类比:游戏打到 Boss 关卡前弹出确认框"确定要卖掉传说装备吗?"——游戏(图)原地挂起、进度已存档,你合上笔记本睡一觉,明天点"确定",游戏从完全相同的位置继续。

官方文档的定义要点:interrupt 是动态的——它可以放在代码任意位置、可以按业务条件触发(对比"静态断点"只能编译时固定在某个节点前后)。运行流程五步:

  1. 图跑到 interrupt(...) 这行 → 立刻挂起;
  2. 当前白板已由 checkpointer 存档;
  3. 问题文本作为"中断信息"返回给你的调用代码;
  4. 图无限期等待(进程甚至可以退出,存档在数据库里);
  5. 你带着人的答复调用 Command(resume=答复) → 答复成为 interrupt() 的返回值,图继续往下跑。
python
from langgraph.types import interrupt

def approval_node(state: State):
    # 挂起,把问题抛给调用方;恢复时,resume 值从这里"接上"
    approved = interrupt("Do you approve this action?")
    return {"approved": approved}

10.2 最小可运行示例

完整跑一遍"暂停 → 等人 → 恢复"(不需要真模型,专注机制本身):

python · hitl_demo.py
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import interrupt, Command
from typing_extensions import TypedDict

class State(TypedDict):
    task: str
    approved: bool

def ask_approval(state: State) -> State:
    answer = interrupt(f"任务《{state['task']}》需要审批,同意吗?")
    return {"approved": answer}

def do_work(state: State) -> State:
    if not state["approved"]:
        print("(任务被否决,什么都不做)")
        return {}
    print(f"(执行任务:{state['task']})")
    return {}

builder = StateGraph(State)
builder.add_node("ask_approval", ask_approval)
builder.add_node("do_work", do_work)
builder.add_edge(START, "ask_approval")
builder.add_edge("ask_approval", "do_work")
builder.add_edge("do_work", END)
graph = builder.compile(checkpointer=InMemorySaver())   # ← interrupt 必须配存档器!

CFG = {"configurable": {"thread_id": "t1"}}

# 第一次运行:会在 ask_approval 处挂起
result = graph.invoke({"task": "删除三个月的日志", "approved": False}, CFG)
print("中断信息:", result["__interrupt__"][0].value)
# 中断信息: 任务《删除三个月的日志》需要审批,同意吗?

# ……此时进程哪怕退出也没事,存档在。三天后老板说同意:
resumed = graph.invoke(Command(resume=True), CFG)
print("最终状态:", resumed)
# 最终状态: {'task': '删除三个月的日志', 'approved': True}
# (执行任务:删除三个月的日志)   ← do_work 顺利跑完

三个关键点:① interrupt() 必须配 checkpointer(没存档就没法"续播"),这是硬性要求;② Command(resume=...) 是唯一允许作为 invoke 输入的 Command 形式(官方文档警告原文);③ 恢复必须用同一个 thread_id。

备注:本例用 invoke,中断信息从 result["__interrupt__"] 里取。官方新的事件流式接口 graph.stream_events(..., version="v3") 则通过 stream.interrupted 与 stream.interrupts 属性获取,适合边流式边处理中断的 Web 应用——机制完全相同。

10.3 审批工作流:批准或拒绝

把 interrupt 和第 14 章的 Command(goto) 组合,就是经典的审批分支:

python · 官方模式
from langgraph.types import Command, interrupt
from typing_extensions import Literal

def human_approval(state: State) -> Command[Literal["proceed", "cancel"]]:
    is_approved = interrupt({
        "question": "要执行这个操作吗?",
        "details": state["action_details"],   # 把需要审的内容一并抛出去
    })
    if is_approved:
        return Command(goto="proceed")
    return Command(goto="cancel")

# 恢复时:graph.invoke(Command(resume=True), cfg)  → 走 proceed
#         graph.invoke(Command(resume=False), cfg) → 走 cancel

10.4 在工具内部中断

更实用的位置是工具内部——模型自主决定调用高危工具时,人自然被拉进审批流程。官方文档示例(发邮件前审批):

python
@tool
def send_email(to: str, subject: str, body: str) -> str:
    """给指定收件人发送邮件。"""
    response = interrupt({
        "action": "send_email",
        "to": to, "subject": subject, "body": body,
        "message": "确认发送这封邮件吗?",
    })
    if response.get("action") == "approve":
        final_to = response.get("to", to)   # 恢复值还能"顺手改参":人可以把收件人改对了再放行
        # ... 真正发信 ...
        return f"已发送给 {final_to}"
    return "邮件已被用户取消"

10.5 四条铁律(必背)

官方文档明确警告了四个坑,每一条都来自真实翻车:

铁律为什么
❶ 不要用 try/except 包住 interrupt()interrupt 靠抛特殊异常实现挂起,裸 except: 会把它吞掉
❷ 不要改变 interrupt 的调用顺序恢复值按"第几次 interrupt"严格对号入座,条件性跳过会整体错位
❸ 载荷只放 JSON 可序列化类型字符串/数字/字典可以;函数、类实例不行(要被存进数据库)
❹ interrupt 之前的代码必须幂等恢复时节点从头重跑——interrupt 前发过的邮件会再发一遍!副作用要么放 interrupt 之后,要么拆成独立节点

顺带一条官方推荐:需要"反复问人直到答案合法"时,不要在节点里写 while True + interrupt() 循环(每次恢复都从头重放节点,代价指数上涨);正确姿势是每个节点只 interrupt 一次,把"答案不合法"的信息写进 State,用条件边让流程绕回这个节点再来一遍。

10.6 静态断点(了解即可)

老一代机制:编译时固定声明"某节点前/后必停",恢复用 invoke(None, config):

python
graph = builder.compile(
    interrupt_before=["node_a"],          # 跑到 node_a 之前必停
    interrupt_after=["node_b", "node_c"],
    checkpointer=checkpointer,
)
graph.invoke(inputs, config=config)   # 第一次:停在断点
graph.invoke(None, config=config)     # 传 None:从断点继续

官方文档原话:静态断点不推荐用于 HITL 工作流(不够灵活,无法按条件触发),请改用 interrupt()。它的现代用武之地是调试时"单步执行",配合 LangSmith Studio 在界面里点节点观察状态。

第 11 章Streaming 流式输出

Agent 一跑几十秒,用户盯着黑屏会以为死机了。Streaming 让过程"现场直播":每步更新、每个字、自定义进度都能实时推给你。

11.1 七种流模式总览

统一入口是 graph.stream(输入, stream_mode="…")。LangGraph 1.2 起官方推荐给 stream 传 version="v2"——每个事件变成统一格式的 StreamPart 字典:{"type": 模式名, "ns": 来源命名空间, "data": 载荷},按 chunk["type"] 分流处理即可。七种模式(官方文档表格)::

模式吐什么典型用途
values每拍之后的完整白板调试:看状态怎么一步步演变
updates每拍之后的增量(带节点名)进度条:"分类完成→检索完成…"
messages(消息片段, 元数据),LLM 逐 token打字机效果
custom节点/工具里手动发出的任意数据检索进度"已取 37/100 条"
checkpoints存档事件(格式同 get_state)审计每一步的状态快照
tasks任务开始/结束(含结果与错误)监控
debugcheckpoints + tasks + 额外元数据信息最全的排查模式

后三种需要编译时配 checkpointer。v1 老写法(网上旧教程常见)不再赘述,知道"旧版裸 dict / 元组,新版统一 StreamPart"即可平滑看懂旧代码。

11.2 LLM 逐字输出(打字机效果)

python
for chunk in graph.stream(
    {"topic": "ice cream"},
    stream_mode="messages",
    version="v2",
):
    if chunk["type"] == "messages":
        message_chunk, metadata = chunk["data"]
        if message_chunk.content:
            print(message_chunk.content, end="", flush=True)

两个官方技巧:① 即使节点里用的是阻塞的 model.invoke(),token 也会被流出来;② 图里有多个 LLM 时按需过滤——用 llm.with_config(tags=["joke"]) 给某个模型打标签(可与 bind_tools 链式使用),再检查 metadata["tags"] 或 metadata["langgraph_node"];不想让某个模型的输出进流,给它 "nostream" 标签。

11.3 自定义进度流

工具执行到一半想播报进度?在节点/工具里拿一个 get_stream_writer(),想发什么发什么:

python
from langgraph.config import get_stream_writer

@tool
def query_database(query: str) -> str:
    """查询数据库。"""
    writer = get_stream_writer()                       # 拿到"话筒"
    writer({"data": "Retrieved 0/100 records", "type": "progress"})
    # ...执行查询...
    writer({"data": "Retrieved 100/100 records", "type": "progress"})
    return "some-answer"

for chunk in graph.stream(inputs, stream_mode="custom", version="v2"):
    if chunk["type"] == "custom":
        print("进度:", chunk["data"]["data"])

官方提示:custom 流还能接任意非 LangChain 的模型 API——在节点里循环调自定义流式客户端、每个片段用 writer() 吐出,就能混进统一的流里。另一个坑:Python 3.11 以下的异步节点里拿不到 get_stream_writer(),改为在函数签名里声明 writer: StreamWriter 参数,LangGraph 自动注入。

11.4 多模式组合

python
for chunk in graph.stream(inputs, stream_mode=["updates", "custom"], version="v2"):
    if chunk["type"] == "updates":
        for node_name, state in chunk["data"].items():
            print(f"节点 `{node_name}` 更新: {state}")
    elif chunk["type"] == "custom":
        print("自定义:", chunk["data"])

子图的流默认不上浮。想看到子图内部事件,在父图 stream 时加 subgraphs=True,然后看 chunk["ns"]——根图是 (),子图事件带命名空间(如 ("node_name:任务id",))。

第 12 章记忆系统:短期与长期

第 9 章的存档解决"一段对话之内记得住";本章解决"换个对话还记得住"。官方把记忆分成两层,配套两套基础设施。

12.1 两种记忆:会话内 vs 跨会话

短期记忆(Short-term)长期记忆(Long-term)
作用范围单个 thread(一段对话)之内跨 thread(跨会话、跨对话)
实现机制Checkpointer(第 9 章)Store(本章)
编译参数compile(checkpointer=...)compile(store=...)
存的东西白板快照(消息历史等)按"命名空间+键"组织的键值数据
典型用途多轮对话连续性记住用户偏好、用户档案、共享知识

官方明确说:多数应用两个一起用——builder.compile(checkpointer=..., store=...)。

12.2 对话太长怎么办:裁剪 / 删除 / 摘要

消息一直追加,早晚会撑爆模型上下文窗口。官方文档给出四种策略:

策略 A:trim_messages 只带最近的消息

python · 官方示例
from langchain_core.messages.utils import trim_messages, count_tokens_approximately

def call_model(state: MessagesState):
    # 存档里的历史照旧全存,只是喂模型之前"从尾往前"裁到 128 token
    messages = trim_messages(
        state["messages"],
        strategy="last",
        token_counter=count_tokens_approximately,
        max_tokens=128,
        start_on="human",          # 裁完后必须以人类消息开头
        end_on=("human", "tool"),  # 裁完后必须以人类/工具消息收尾
    )
    return {"messages": [model.invoke(messages)]}

策略 B:RemoveMessage 删除消息

要求格子使用 add_messages Reducer(它支持按 ID 删除):

python
from langchain.messages import RemoveMessage
from langgraph.graph.message import REMOVE_ALL_MESSAGES

def delete_messages(state):
    msgs = state["messages"]
    if len(msgs) > 2:
        return {"messages": [RemoveMessage(id=m.id) for m in msgs[:2]]}
    # 删全部:
    # return {"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES)]}
⚠️ 删完要保证历史仍"合法"多数模型要求消息历史以 user 开头;带 tool_calls 的 AI 消息后面必须紧跟对应 ToolMessage,否则下一轮 API 直接报错。

策略 C:摘要压缩(summarize)

官方推荐的中长期方案:把历史交给 LLM 压成一段 summary 存进 State(给 State 加 summary: str 格子),删掉旧消息只留最近两条;下轮把摘要作为上下文带上。骨架:

python · 官方示例骨架
class State(MessagesState):
    summary: str                       # 多加一个"摘要"格子

def summarize_conversation(state: State):
    summary = state.get("summary", "")
    if summary:
        summary_message = (f"这是迄今为止的对话摘要:{summary}\n\n"
                           "请结合以上新消息扩展摘要:")
    else:
        summary_message = "请为上面的对话创建摘要:"
    messages = state["messages"] + [HumanMessage(content=summary_message)]
    response = model.invoke(messages)
    # 删除除最近两条外的全部消息
    delete_messages = [RemoveMessage(id=m.id) for m in state["messages"][:-2]]
    return {"summary": response.content, "messages": delete_messages}

策略 D:管理存档本身

graph.get_state(config) 看当前、list(graph.get_state_history(config)) 看历史、checkpointer.delete_thread(thread_id) 整线程删除——用户点"删除我的聊天记录"时用最后这个。

12.3 Store:跨会话长期记忆

Store 是编译时挂上的另一件基础设施,按 namespace(命名空间元组)+ key 存键值对。经典用法:"记住每个用户的偏好",namespace 用 (用户ID, "memories"):

python · 官方示例
import uuid
from dataclasses import dataclass
from langgraph.store.memory import InMemoryStore
from langgraph.runtime import Runtime

store = InMemoryStore()                     # 开发用;生产换 PostgresStore 等
builder = StateGraph(MessagesState, context_schema=Context)  # Context 见 3.3
# ... 加节点 ...
graph = builder.compile(store=store)        # ← 编译时挂上 store

async def call_model(state: MessagesState, runtime: Runtime[Context]):
    namespace = (runtime.context.user_id, "memories")   # 每个用户一个"抽屉"

    # 读:按语义搜索这个抽屉里最相关的 3 条
    memories = await runtime.store.asearch(
        namespace, query=state["messages"][-1].content, limit=3
    )
    info = "\n".join(d.value["data"] for d in memories)

    # 写:存一条新记忆(key 随便给个唯一值)
    await runtime.store.aput(
        namespace, str(uuid.uuid4()), {"data": "用户偏好深色模式"}
    )
    # 同步写法是 store.put(...) / store.search(...)
    ...

# 调用时通过 context 告诉图"现在是谁":
graph.invoke(
    {"messages": [{"role": "user", "content": "hi"}]},
    {"configurable": {"thread_id": "1"}},
    context=Context(user_id="1"),
)

生产环境把 InMemoryStore 换成 PostgresStore.from_conn_string(...)(同样先 setup() 建表),代码零改动。

12.4 语义搜索记忆

给 Store 配上 embedding 模型,检索就自动升级为按含义搜("我饿了"能搜到"我爱吃披萨"):

python · 官方示例
from langchain.embeddings import init_embeddings
from langgraph.store.memory import InMemoryStore

embeddings = init_embeddings("openai:text-embedding-3-small")
store = InMemoryStore(index={"embed": embeddings, "dims": 1536})

store.put(("user_123", "memories"), "1", {"text": "I love pizza"})
store.put(("user_123", "memories"), "2", {"text": "I am a plumber"})

hits = store.search(("user_123", "memories"), query="I'm hungry", limit=1)
print(hits[0].value["text"])    # → "I love pizza"(按语义匹配上的)
💡 一句话记住本章短期记忆靠 checkpointer(配 thread_id),长期记忆靠 store(配 namespace),都能换生产数据库,互不冲突,一起挂。

第 13 章子图 Subgraphs

图大了会乱。子图让你把一张图当成另一个图的一个"节点"来用——像函数封装代码一样封装流程。官方列出的三大场景:多智能体系统、跨图复用节点组、团队分工(只约定输入输出接口,互不关心内部实现)。

13.1 什么时候需要子图

13.2 两种添加方式

选哪种只看一件事:父图和子图的 State 字段共不共享。

方式 A:字段不同 → 包一层转换函数

python · 官方文档示例
from langgraph.graph.state import StateGraph, START
from typing_extensions import TypedDict

class SubgraphState(TypedDict):     # 子图自己的白板(父图不认识 bar)
    bar: str

def subgraph_node_1(state: SubgraphState):
    return {"bar": "hi! " + state["bar"]}

subgraph_builder = StateGraph(SubgraphState)
subgraph_builder.add_node(subgraph_node_1)
subgraph_builder.add_edge(START, "subgraph_node_1")
subgraph = subgraph_builder.compile()

class State(TypedDict):             # 父图的白板(只有 foo)
    foo: str

def call_subgraph(state: State):
    # 进:父字段 → 子字段;出:子字段 → 父字段(就像函数调用传参/收返回值)
    sub_out = subgraph.invoke({"bar": state["foo"]})
    return {"foo": sub_out["bar"]}

builder = StateGraph(State)
builder.add_node("node_1", call_subgraph)
builder.add_edge(START, "node_1")
graph = builder.compile()

方式 B:字段相同 → 编译好的子图直接当节点

python
builder = StateGraph(State)            # 父图
builder.add_node("node_1", subgraph)   # ← 直接把编译后的子图传进去!
builder.add_edge(START, "node_1")

子图会自动读写父图的共享通道(比如共享的 messages)。子图 State 也可以有父图没有的私有格子,互不打扰。第 7.6 节的 create_agent 返回的就是编译好的图,直接 add_node 就能作为子图嵌入你的大图。

📖 子图与存档父图编译时带了 checkpointer,会自动传给子图(默认 per-invocation 模式:每次调用全新,单次调用内支持中断/恢复)。要让子图跨调用在同一线程里累积状态,用 subgraph_builder.compile(checkpointer=True)(per-thread 模式)。

13.3 用子图搭多智能体

最简形态:主图(监督者)+ 若干专家子图。

START→ supervisor 监督者
决定派给哪个专家
→条件边→ researcher 子图 / writer 子图 / coder 子图 → 回到 supervisor …→ END
python · 骨架
builder = StateGraph(MessagesState)
builder.add_node("supervisor", supervisor_node)      # 普通节点:LLM 决定"下一步给谁"
builder.add_node("researcher", researcher_agent)     # 编译好的子图(7.6 节的 create_agent)
builder.add_node("writer", writer_agent)
builder.add_edge(START, "supervisor")
builder.add_conditional_edges(
    "supervisor",
    lambda s: s["next"],                             # 监督者把决定写进白板
    {"researcher": "researcher", "writer": "writer", "FINISH": END},
)
for expert in ["researcher", "writer"]:
    builder.add_edge(expert, "supervisor")           # 干完回监督者,形成循环
graph = builder.compile(checkpointer=InMemorySaver())

想让子图跳回父图的某个节点(更灵活的控制流),用第 14 章的 Command(goto="父图节点", graph=Command.PARENT)。

第 14 章Command:节点内精确控制

条件边在"节点外面"指路;Command 让节点自己在"节点里面"既汇报工作、又决定去向——一个返回值干两件事。

14.1 Command 是什么

Command 是节点的"加强版返回值",四个参数(官方文档): update(状态更新)、goto(去哪个节点)、graph(去哪张图,配 Command.PARENT 跳父图)、resume(第 10 章的恢复值,唯一能用作 invoke 输入的参数)。最常用的是前两个的组合:

14.2 边走边更新:update + goto

python
from langgraph.types import Command
from typing_extensions import Literal

def my_node(state: State) -> Command[Literal["my_other_node"]]:
    #       ↑ 类型注解声明可能的去向(官方要求写上,图渲染需要它)
    return Command(
        update={"foo": "bar"},      # ① 白板更新(等价于普通返回值)
        goto="my_other_node",       # ② 下一步去哪(等价于条件边)
    )

什么时候用它?官方《Thinking in LangGraph》的实战例子(邮件分类节点):LLM 分类完,同一时刻把分类结果写进白板、并把流程路由到对应专员——比"节点写状态 + 外面条件边读状态再路由"少绕一圈,逻辑内聚。第 10.3 节的审批分支也是它。

⚠️ 不要混用路由机制官方 Graph API 警告:一个节点用 Command(goto) 指路后,就别再给它连条件边或出向普通边——一种节点一种指路方式。

14.3 跳到父图与注意事项

python · 子图跳父图(多智能体交接)
def my_node(state: State) -> Command[Literal["other_subgraph"]]:
    return Command(
        update={"foo": "bar"},
        goto="other_subgraph",       # 目标是父图里的节点
        graph=Command.PARENT,        # ← 关键:去父图找,而不是本图
    )

官方提醒:如果父图与子图共享某个 key 且都往里写,父图必须为该 key 定义 Reducer(否则父图不知道怎么合并子图的写入)。再背一遍那句话:Command(resume=...) 是唯一作为 invoke 输入的 Command 形式;多轮对话继续请传普通字典,别传 Command(update=...)——那会让图从最近存档恢复,表现为"卡住不动"(官方故障排查页原话)。

第 15 章Time Travel 时间旅行

有了第 9 章的存档链,就能做一件很酷的事:回到过去任意一步,改个决定,走出一条新时间线。这就是官方说的 time travel——调试 Agent 决策的利器。

15.1 回到过去再改一次

三步曲:① 找到历史快照 → ② 从那一点"改写白板" → ③ 重新 invoke(图从改写点继续跑,产生新分支):

python · 官方 API 流程
# ① 遍历存档链,找到"node_b 即将执行"的那个历史节点
config = {"configurable": {"thread_id": "1"}}
history = list(graph.get_state_history(config))
past = next(s for s in history if s.next == ("node_b",))

# ② update_state:创建一个带新值的【新】checkpoint(不改原存档!)
#    as_node 声明"这个更新当作是 node_b 写的",从而影响下一步从哪继续
graph.update_state(
    past.config,
    {"foo": "改过的值"},
    as_node="node_b",
)

# ③ 用新 checkpoint 的 config 直接 invoke(输入传 None 表示"不新增输入")
graph.invoke(None, past.config)
# → 图从 node_b 之后的位置,带着改过的白板继续执行,走出新分支

三个要点(官方文档):

适用场景:Agent 第 3 步检索用了错误的关键词 → 回到第 3 步前改写查询 → 只重跑后半程,前两步不用再来一遍。

第 16 章Functional API 函数式写法

LangGraph 其实有两种写法:本教程主讲的 Graph API(画图),和官方提供的 Functional API(写普通函数 + 两个装饰器)。它俩共享同一套持久化、中断、流式基础设施。

16.1 @task 与 @entrypoint

python · 官方 Quickstart 风格
from langgraph.func import entrypoint, task
from langgraph.graph import add_messages

@task                       # task = "一个会被存档的步骤",返回 future
def call_llm(messages):
    return llm.invoke(messages)

@task
def call_tool(tool_call):
    tool_map = {t.name: t for t in tools}
    return tool_map[tool_call["name"]].invoke(tool_call["args"])

@entrypoint(checkpointer=InMemorySaver())   # entrypoint = "整个函数就是一张图";存档器在这里配
def agent(messages):
    llm_response = call_llm(messages).result()      # .result() = 等它做完拿结果
    while True:                                     # 普通 while 就是控制流!
        if not llm_response.tool_calls:
            break                                   # 不点菜了 → 收工
        futures = [call_tool(tc) for tc in llm_response.tool_calls]
        results = [f.result() for f in futures]     # 多个 future = 自动并行
        messages = add_messages(
            messages, [llm_response, *results]
        )
        llm_response = call_llm(messages).result()
    return add_messages(messages, llm_response)

# 调用(多轮记忆同样靠 thread_id):
agent.invoke(
    [{"role": "user", "content": "3 加 4 等于几"}],
    config={"configurable": {"thread_id": "1"}},
)

对照第 7 章:节点、边、条件边不见了,取而代之的是普通 Python 控制流(while / if / break)。@task 调用返回 future,先全部发出、再统一 .result() 就是并行(8.2/8.5 节的官方示例都是这么写的)。

16.2 Graph API 怎么选

官方有专门的《Choosing between Graph and Functional APIs》页,可归纳为:

Graph API(本教程主线)Functional API
写法声明式:画节点和边命令式:普通函数 + while/if
擅长复杂分支/并行/多智能体,结构一目了然;可可视化、可 Studio 调试顺序逻辑、动态控制流写起来最自然;上手快
基础设施完全一致:checkpointer、interrupt、流式、LangSmith 两边通用
混用可以:Functional 的 @entrypoint 函数能作为节点放进 Graph API 的图

学习建议不变:先学 Graph API(概念是整个生态的地基、社区资料最多),Functional 当作"同一件事的另一种语法糖"。两者转换对照:State ≈ 函数入参+闭包、Node ≈ @task、条件边 ≈ while/if、add_edge(START,...) ≈ 函数第一行。

第 17 章调试、可视化与错误处理

图写复杂后,"它在干嘛"会成为头号问题。本章三件武器:把图画出来、用 LangSmith 追踪、看懂错误码。

17.1 把图画出来

python
# 方式一:导出 Mermaid 文本,粘到 https://mermaid.live 看图(零依赖,推荐)
print(graph.get_graph().draw_mermaid())

# 方式二:直接生成 PNG(需要额外安装依赖包,报错就装它提示的包)
graph.get_graph().draw_mermaid_png(output_file_path="graph.png")

# 方式三:ASCII 字符画(应急)
graph.get_graph().draw_ascii()

条件边的映射字典(第 5 章)、Command 的类型注解 -> Command[Literal[...]](第 14 章)都会体现在图里——这就是官方要求写类型注解的原因之一。

17.2 LangSmith 追踪

LangSmith 是官方的可观测性平台(有免费额度,可选使用):注册拿 Key、设两个环境变量,之后零代码改动,每次运行自动上报:每个节点耗时、每次 LLM 调用的完整提示词与回复、白板的每次变化、错误堆栈,还能在网页里重放。配上 LangSmith Studio 更进一步:在网页里可视化图结构、单步执行、点任意节点查看当时的白板快照、设断点(第 10.6 节的调试用法)。

bash
setx LANGSMITH_TRACING true
setx LANGSMITH_API_KEY "lsv2_..."     # 在 smith.langchain.com 注册获取

不想注册也行:第 11 章的 stream_mode="debug" + 第 9 章的 get_state_history 能覆盖大部分排查需求。

17.3 常见错误码对照表

LangGraph 会抛带编号的专用错误,官方文档有专门的 errors 页面。收集最高频的几个:

错误含义怎么修
GRAPH_RECURSION_LIMIT超过 recursion_limit 步数上限检查循环条件能不能到 END;临时调大 config={"recursion_limit": N};根治用 RemainingSteps(7.5 节)
INVALID_CONCURRENT_GRAPH_UPDATE并行节点同时写无 Reducer 的同一格子给该格子加 Annotated[..., add](4.2 节)
INVALID_GRAPH_NODE_RETURN_VALUE节点返回的不是 dict / Command节点必须 return {"格子": 值} 或 Command
MISSING_CHECKPOINTER用了 interrupt/存档功能但没配 checkpointer编译时 compile(checkpointer=...),调用带 thread_id
INVALID_CHAT_HISTORY消息历史非法(如 tool_calls 后缺 ToolMessage)检查删除/裁剪逻辑,保住消息配对(12.2 节警告)

第 18 章24 个常见坑(FAQ)

全部来自官方文档的警告区块、故障排查页与高频社区问题。点开每一条看答案。

1. 节点之间到底怎么传数据?能把一个节点的返回值直接给下一个节点吗?
不能直接传。唯一通道是共享 State:节点 A 把结果写进白板格子,节点 B 从白板读。这是新手第一大误区——LangGraph 里没有"函数调函数",只有"大家读写同一块白板"。
2. 我的列表每次都被覆盖,只剩最后一条?
格子没挂 Reducer(默认覆盖)。给列表格子加 Annotated[list[str], operator.add] 或消息用 add_messages(第 4 章)。
3. 并行节点同时写一个格子,报 InvalidUpdateError?
并发更新没有 Reducer 裁决(错误码 INVALID_CONCURRENT_GRAPH_UPDATE)。解法唯一:加 Reducer。即使今天不并行,以后随手加条边就会炸——凡是会被多节点写的格子,一律配 Reducer。
4. invoke 报错说图必须先 compile?
StateGraph 对象只是"图纸",builder.compile() 之后才是可执行对象。检查是不是把 builder 直接 invoke 了。
5. Agent 循环转个不停,最后 GraphRecursionError?
三查:① 工具 docstring 是否清楚(模型不知道何时收手);② 条件边是否可能永远不返回 END;③ recursion_limit 是否太小。根治方案见 7.5 节 RemainingSteps。
6. 配了 checkpointer 后 invoke 报错要求 thread_id?
这是设计如此:配了存档器,每次调用必须说明"读写哪个存档槽"。补上 {"configurable": {"thread_id": "xxx"}}。
7. State 里该存什么、不该存什么?
官方原则:存原始数据,不存格式化文本;能随时推导的不存(用时算);跨步骤要用、重取成本高的必存。prompt 模板放在节点代码里,不进 State。
8. 想清空一个挂了 Reducer 的列表,返回 [] 没效果?
合并规则下 旧 + [] 还是旧值。用 {"格子": Overwrite([])} 绕过 Reducer(4.5 节)。删除消息则要用 RemoveMessage(12.2 节)。
9. interrupt 之后程序继续跑完了,没等我就执行了?
检查三点:编译是否配了 checkpointer;是否复用了同一个 thread_id;是不是误把恢复调用写成了普通 invoke(普通 invoke 带新输入会开新一轮,而不是续播)。恢复必须 Command(resume=...)。
10. interrupt 恢复后,中断前的代码又执行了一遍?
设计如此:恢复=节点从头重放。所以第 10 章铁律❹——interrupt 之前的副作用必须幂等,或挪到 interrupt 之后/独立节点。
11. 节点里 try/except 一包,interrupt 就失效?
interrupt 靠异常实现暂停,被你吞了。裸 except 是重灾区:except Exception: 也会吞掉它。
12. 模型下一轮报错,说找不到 tool_call 对应的消息?
ToolMessage 没带 tool_call_id,或带了 tool_calls 的 AI 消息没跟上 ToolMessage。逐条核对 7.3 节;删消息时保持配对完整(12.2 节)。
13. 想让多个 LLM 同时跑,怎么写并行?
Graph API:一个节点多条出边,目标节点自动同拍并行(3.6 节),记得配 Reducer。Functional API:连续发起多个 @task,最后统一 .result()(8.2 节)。不用碰 threading。
14. 子任务数量运行时才知道,边没法提前画?
用 Send API(8.4 节):条件边返回 [Send("节点名", 各自输入), ...],动态开出任意多分支。
15. 子图里的 token / 事件看不到了?
父图 stream 时加 subgraphs=True,再按 chunk["ns"] 区分来源(11.4 节)。
16. InMemorySaver 重启后记忆全丢,正常吗?
正常,它只存内存。开发用 SqliteSaver(本地文件),生产用 PostgresSaver(9.6 节)。另外凡配了 checkpointer,官方建议节点写成幂等(第 3 章铁律③):崩溃恢复会重放。
17. checkpoint 越积越多,数据库变大?
官方故障排查页建议:定期清理旧 checkpoint / 设保留策略(如定时删 N 天前的数据)。1.2+ 还有 DeltaChannel(append 类通道只存增量)可显著缩小体积。
18. 一个 graph 对象能同时服务多个用户吗?
能,这正是 thread_id 的意义:同一张图、每用户一条线程、互不干扰(9.2 节)。线程数量不限。
19. Command(resume=...) 之外,能把 Command(update=...) 当输入传吗?
不能。官方警告 resume 是唯一该作为 invoke 输入的 Command 形式;传 update 会让图从最近存档恢复、表现成"卡住"。继续对话请传普通字典输入。
20. 旧教程的 create_react_agent / MemorySaver / MessageGraph 是什么?
LangGraph 1.0 前的旧写法:create_react_agent 已弃用 → 用 LangChain 1.0 的 create_agent(7.6 节);MemorySaver = InMemorySaver 的旧名;MessageGraph 已淘汰 → 用 StateGraph(MessagesState)。1.0 承诺 2.0 前不破坏兼容,看到旧写法按此对照即可。
21. Python 版本要求?异步节点有什么坑?
官方要求 Python ≥ 3.10。3.11 以下 asyncio 不传播 context,导致:异步 LLM 调用要显式传 config;异步节点里用不了 get_stream_writer(),要在签名里声明 writer: StreamWriter 参数(11.3 节)。
22. graph.invoke 慢,怎么提速?
优先级:① 能并行的用并行(超步免费并行);② 贵而不变的节点编译时配 cache=InMemoryCache() + 节点 cache_policy(官方节点缓存,输出带 cached 标记);③ 检查是否在串行节点里塞了本可拆分的独立调用;④ 持久化模式选 durability="async" 平衡性能与安全。
23. 每个节点都该拆多细?
官方《Thinking in LangGraph》:checkpoint 在节点边界产生,节点越小、失败后重复的越少;外部服务调用独立成节点便于单独重试;节点多不会显著变慢(存档默认异步写)。按"韧性 + 可观测性"取舍,不必按数量。
24. 学习 LangGraph 必须先学 LangChain 吗?
不必须(第 2~5 章零 LangChain)。但第 6 章起会用到 LangChain 的模型接入、消息类型、@tool、create_agent——学到哪补哪即可,不必先通读 LangChain 文档。

第 19 章学习路线图与资源

你已经走完了从"什么是图"到"多智能体+时间旅行"的全部主干。接下来去哪、按什么顺序,官方资源都列在这里。

19.1 学完本教程后去哪

  1. 把第 7 章的 Agent 改造成你自己的:换工具(查数据库/调内部 API/读文件)、换 State、加 checkpointer——这是最快的内化方式。
  2. 做一个完整的 HITL 应用:参考第 10 章给高危工具加审批,配 SQLite 存档,跑通"暂停-重启进程-恢复"全流程。
  3. 上一个真实模式:从第 8 章五模式里挑一个贴你业务的,或用子图拼一个监督者多智能体(13.3)。
  4. 补官方课程:LangChain Academy 免费课《Introduction to LangGraph》(含配套代码仓),跟本教程互补——它是视频+实操,本教程是逐行拆解。
  5. 进阶专题:部署(官方有 LangGraph Platform / 自托管 Server,持久化自动托管)、Deep Agents(官方高层封装:规划+子 Agent+文件系统)、LangSmith 评估。

19.2 官方学习资源

资源地址说明
官方文档(Python)docs.langchain.com/oss/python/langgraph本教程主要依据;有 llms.txt 全站索引
GitHub 仓库github.com/langchain-ai/langgraphREADME、示例、Releases、Issues(报错先搜这里)
API 参考reference.langchain.com/python/langgraph全部类与函数签名
免费视频课academy.langchain.comLangChain Academy 官方入门课
官方论坛forum.langchain.com提问与版本公告(如 1.0 alpha 公告)
案例集langchain.com/built-with-langgraphKlarna、Uber 等真实生产案例
JS/TS 版本github.com/langchain-ai/langgraphjs前端/Node 全栈同款框架

附录速查表

A.1 术语速查表

术语人话解释
Graph 图整个流程的"地图":节点 + 边。这里没有数学,就是流程图
State 状态全图共享的一块白板,一张流程的唯一"事实来源"
Node 节点干活的普通 Python 函数:读白板 → 干活 → 返回要更新的格子
Edge 边节点间箭头。普通边=固定路线;条件边=函数看着白板指路
START / END虚拟入口/出口,不是真节点
Reducer每个格子的"合并规则":默认覆盖;Annotated[..., add] 表示累加
compile 编译把图纸变成可执行对象;checkpointer 等配件在这传入
invoke / stream运行图的两种方式:一次性拿结果 / 边跑边吐事件
super-step 超步图的一"拍";同一拍点到的节点并行执行(Pregel 模型)
Checkpointer自动存档器:每拍存一张白板快照;短期记忆的载体
thread / thread_id一段对话 = 一个存档槽;thread_id 是槽位号(主键)
Checkpoint 快照某一拍结束时白板的全量照片(StateSnapshot 对象)
Store跨线程的长期记忆库,按 namespace+key 存键值对
interrupt()节点内喊"暂停"等人工输入;配 Command(resume) 续播
Command节点的加强版返回值:update+goto+graph(+resume)
Send条件边返回的"动态分支"对象:每个分支可带不同输入(map-reduce)
Subgraph 子图把一张图当另一个图的节点用(模块化/多智能体)
recursion_limit最大超步数(默认 1000),防死循环的保险丝
Tool / tool_calls外挂技能 / 模型的"点菜单"(真正执行的是你的代码)
Time travel读历史存档 + update_state 改写 → 从过去分叉出新时间线

A.2 核心 API 速查表

python · 最常用 30 行
# ---- 构建 ----
from langgraph.graph import StateGraph, MessagesState, START, END
builder = StateGraph(State, input_schema=In, output_schema=Out, context_schema=Ctx)
builder.add_node("名", 函数)                        # 名可省略=函数名
builder.add_edge("a", "b")                          # 普通边
builder.add_edge(START, "a"); builder.add_edge("b", END)
builder.add_conditional_edges("a", 路由函数, {"值": "节点"})
graph = builder.compile(checkpointer=InMemorySaver(), store=InMemoryStore())

# ---- 运行 ----
graph.invoke(输入dict, {"configurable": {"thread_id": "1"}})          # 一次性
graph.stream(输入, stream_mode="updates", version="v2")               # 流式
graph.invoke(Command(resume=人的答复), config)                        # 中断后续播

# ---- 状态 ----
graph.get_state(config)                     # 最新快照
list(graph.get_state_history(config))       # 全部历史(倒序)
graph.update_state(config, {"k": v}, as_node="节点")   # 时间旅行改写

# ---- 中断 ----
from langgraph.types import interrupt, Command, Send, Overwrite
answer = interrupt("问题?")                  # 节点内挂起

# ---- 节点返回(写在节点函数体内,按需四选一)----
def node_return_demo(state):
    return {"k": v}                                       # 更新白板
    return Command(update={"k": v}, goto="下一站")        # 更新 + 路由
    return Command(goto="父图节点", graph=Command.PARENT) # 子图跳父图
    return [Send("节点", {"各自": 输入}) for x in 列表]   # 动态并行(Send)

# ---- 配置 ----
graph.invoke(inputs, config={"recursion_limit": 25})   # 顶层 key,不进 configurable
graph.invoke(inputs, context=Context(user_id="1"))     # 上下文(3.3 节)

# ---- 消息 ----
from langchain.messages import RemoveMessage
return {"messages": [RemoveMessage(id=m.id) for m in 旧消息]}   # 删消息

A.3 官方链接汇总

本教程依据的一手资料(写作时核对于 2026-09,LangGraph 1.2.11):

注:LangChain 团队未发布过 LangGraph 官方 arXiv 论文;学术引用请引用其 GitHub 仓库与官方文档。