第 00 章导读 · 开始之前
在写第一行代码之前,先花 10 分钟读完这一章,后面会顺利十倍。本章回答三个问题:这份教程怎么读?你需要会什么?教程内容依据哪些官方一手资料?
0.1 这份教程怎么读
这是一份面向零基础读者的 LangGraph 教程。编写时遵循三条原则:
- 先打比方,再讲概念:每个抽象概念都先给一个生活化类比,再给官方定义,最后给代码。
- 每一段代码都能跑:所有代码基于 LangGraph 1.x(写作时最新版本 1.2.11)。前几章刻意设计成不联网、不需要任何 API Key 也能运行,先把框架本身学明白,再接大模型。
- 每段代码逐行解释:不给"读者自己体会"的机会,每一行干什么、为什么这么写、换种写法行不行,都会说清楚。
会一点 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 官方发布的一手资料。这里如实说明资料的构成,方便你以后自行溯源:
- 官方 GitHub 仓库:github.com/langchain-ai/langgraph(约 4.2 万 star),官方定位原文是 "Low-level orchestration framework for building, managing and deploying long-running, stateful agents"(构建、管理、部署长时间运行的有状态智能体的低层编排框架)。
- 官方文档:docs.langchain.com/oss/python/langgraph/,共 40+ 页,涵盖 Graph API、持久化、中断、流式、子图、记忆等全部主题。本教程第 3~16 章的概念与代码均出自此处对应页面。
- 官方博客发布文章:LangGraph 发布文(2024-01),解释了设计动机——LCEL 链是有向无环图(DAG)、无法引入循环,而 Agent 本质是"在 for 循环里跑 LLM",所以需要一张能转圈的图。
- 关于"官方论文"的说明:LangChain 团队没有为 LangGraph 发表过官方 arXiv 论文或技术报告(已检索确认;学术引用惯例是引用其 GitHub 仓库与官方文档)。网上能搜到的 LangGraph 相关论文均为第三方研究。因此本教程以官方 GitHub + 官方文档 + 官方博客这三类一手资料为准。
- 官方免费课程:LangChain Academy《Introduction to LangGraph》。
📅 版本时间线(自查于 2026-09)
| 时间 | 事件 |
|---|---|
| 2024-01 | LangGraph 首次发布(官方博客宣布),主打"有循环的状态机" |
| 2025-10-22 | LangGraph 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 万次 |
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."
用本教程的图来说:
LangGraph 两者都能画,这就是它"编排框架"定位的含义。
1.5 什么时候不需要它
工具没有高低,只有合不合适。以下情形不必上 LangGraph:
- 一次性问答、翻译、总结:直接调一次模型 API 即可,画图是杀鸡用牛刀。
- 固定步骤且永不分支的流水线:三步五步直线流程,一个普通 Python 函数串起来更简单。
- 只想快速要个能用的 Agent、不想控制细节:可以用 LangChain 的
create_agent高层 API(本教程 7.6 节会讲),底层同样是 LangGraph。
需要多步骤 + 分支/循环 + 可靠性(断点恢复、人工审批、流式输出、持久记忆)时,LangGraph 就是为此而造的。
1.6 官方生态全家桶
搜资料时你会反复见到这几个名字,官方文档对它们的定位如下:
| 产品 | 是什么 | 和本教程的关系 |
|---|---|---|
| LangGraph | 编排运行时:把流程画成图并执行,提供持久化、中断、流式等基础设施 | 本教程主角 |
| LangChain | Agent 框架:提供模型接入、工具定义、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 向)
- 确认装了 Python 3.10 或更高版本(官方要求 Python ≥ 3.10)。按 Win+R,输入 cmd 回车,在黑窗口里输入:如果提示"不是内部或外部命令",去 python.org 下载安装,安装时务必勾选 "Add Python to PATH",然后重新打开一个 cmd 窗口再试。cmd
python --version :: 期望输出类似:Python 3.11.8(只要 ≥ 3.10 就行)
- 建一个项目文件夹(可选但推荐,避免装包污染全局)。在 cmd 里执行:cmd
mkdir C:\lg_demo cd C:\lg_demo python -m venv venv :: 创建虚拟环境(一个干净的包安装沙箱) venv\Scripts\activate :: 激活它,成功后命令行前面会出现 (venv)
- macOS / Linux 用户的对应写法:
python3 -m venv venv && source venv/bin/activate。
2.2 安装 langgraph
激活虚拟环境后(或者你选择不建虚拟环境也可以),执行官方 README 给出的安装命令:
pip install -U langgraph :: 也可以用 uv(更快的现代包管理器):uv add langgraph
装完后验证一下:
pip show langgraph :: 关注 Version 一行,应当是 1.x.x(本教程写作时最新为 1.2.11)
pip install -U langchain(用于接入各家大模型)。2.3 第一个图:完整代码
在 C:\lg_demo 文件夹里新建一个文件 first_graph.py,粘贴以下全部内容(这段代码改编自官方 Overview 页的示例,为了方便观察加了打印语句):
# -*- 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)运行:
python first_graph.py
>>> 节点 say_hello 干活了!它拿到的白板是: {'message': '大家好'}
最终白板: {'message': '大家好,我是节点,我处理过了!'}🎉 恭喜!你已经跑通了第一个 LangGraph 程序。它虽然没接大模型,但骨架和真实生产级 Agent 一模一样:状态 → 节点 → 边 → 编译 → 调用。后面十几章学的一切,都是往这副骨架上加东西。
2.4 逐行拆解每一句
| 代码 | 人话解释 |
|---|---|
from langgraph.graph import StateGraph, START, END | StateGraph 是搭图的主类;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": "大家好"}) | 启动图。参数就是白板的初始内容(一个普通字典)。返回值是最终白板。 |
读白板 → 干活 → 汇报改动→ 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 心智模型:便利贴墙
把整张图想象成一间办公室的便利贴墙:
- State(状态)=墙上那块大白板。所有格子对全办公室可见,谁都能读、都能改。
- Node(节点)=一位员工。他上班时先读白板,埋头干活,下班前在白板上贴上自己的成果(只贴自己负责的格子)。他不直接把东西递给下一位同事——传递全靠白板。这是初学者最容易误解的一点:节点之间不传参数!唯一的沟通方式是 State。
- Edge(边)=墙上的箭头指引。固定箭头(普通边)写死"做完这步去那步";智能箭头(条件边)由值班经理看过白板后临时指路。
- invoke=老板喊一声"开工!",从 START 进箭头开始,沿着箭头走,走到 END 收工。
3.2 State:全图共享的白板
State 是一个普通的 Python 类型定义(TypedDict / dataclass / Pydantic 皆可),它回答一个问题:"整个流程过程中,我们需要记住哪些东西?"
设计 State 就是在回答"我需要哪些格子"。比如做"文章生成器":
from typing_extensions import TypedDict
class ArticleState(TypedDict):
topic: str # 主题:用户一进来就定死
outline: str # 大纲:第一个节点生成
draft: str # 初稿:第二个节点生成
reviews: list[str] # 审稿意见:可能有多个审稿节点都往里写3.3 Node:干活的函数
节点是普通的同步或异步 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% 的坑):
- 只返回要改动的格子,返回字典如
{"draft": "……"},不要把整个 state 原样返回后再乱改。 - 不要修改传入的 state 再返回它——正确姿势是返回"新的值",让 LangGraph 负责合并。
- 节点应尽量"幂等"(同一个节点跑两次不产生坏后果)。因为启用了存档(第 9 章)后,恢复执行会从节点开头重跑,有副作用的操作(发邮件、写数据库)要设计成可重试。
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。
3.5 compile 编译与 invoke 调用
compile() 做三件事:①结构检查(孤立节点、非法连线等);②把你的 Python 函数包装成标准可执行单元;③接收运行时配件——存档器 checkpointer、断点、缓存都在这里传入(后面章节会看到)。编译后的 graph 是一个标准 Runnable,拥有 invoke(同步调用)、stream(流式调用)、ainvoke(异步调用)等统一方法。
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(超步):
- 图按"超步"一拍一拍地走,就像时钟滴答滴答。
- 同一拍被点到的所有节点,并行执行(比如 START 同时射出三条边 → 三个节点在同一拍同时干活)。
- 一拍内所有节点干完 → 它们的"汇报"统一合并到白板 → 进入下一拍。
- 走到 END 且没有节点可执行 → 图停止。
所以并行不需要你写任何多线程代码——只要一个节点有多条出边(或入口多条出边),LangGraph 自动并行。并行节点同时改白板同一格怎么办?这正是第 4 章 Reducer 要解决的问题(答案:Annotated + 合并函数)。
3.7 动手练习:三步流程图
不看答案,自己写一个:节点 1 生成主题 → 节点 2 生成口号 → 节点 3 汇总输出。写完再对答案:
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': '主题《冰淇淋》口号:冰淇淋万岁!'}add_node(make_topic) 为什么不用起名?(答:默认用函数名)③ 如果 combine 返回 {"final": ...},白板上 topic 会丢吗?(答:不会,返回值只更新提到的格子)第 04 章State 深入:Reducer 是灵魂
Reducer(归约器)是 LangGraph 最容易被新手忽略、又最能解释一切"灵异现象"的知识点。学完本章,你就明白为什么消息列表会自动追加、为什么并行节点会报错、为什么有人要清空一个列表却清不掉。
4.1 默认行为:直接覆盖
先说结论:State 里每个格子(key)都配有一个"合并规则",叫 Reducer。你什么都不写时,规则是"后写的覆盖先写的"。
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 给格子挂一个合并函数:
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,比如:
def merge_dicts(left: dict, right: dict) -> dict:
return {**left, **right} # 后写的键覆盖,其余保留
class State(TypedDict):
scores: Annotated[dict, merge_dicts] # 多个节点各写一部分评分,自动合并InvalidUpdateError(invalid concurrent graph update,并发更新非法)。解法只有一个:给共享格子加 Reducer。这个报错详见第 17 章错误表。4.3 add_messages 与 MessagesState
做对话应用时,messages(消息列表)是最常用的格子,官方专门提供了内置 Reducer add_messages:
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 比普通列表拼接聪明两点(官方文档说明):
- 按 ID 更新:新消息的 ID 与已有消息相同时,替换那条消息而不是追加(这让"修改某条历史消息"成为可能,Human-in-the-loop 依赖它)。
- 自动转换:传入
{"role": "user", "content": "hi"}这样的字典会自动转成消息对象;读取时用点语法,如state["messages"][-1].content。
因为"带消息列表的 State"太常用了,官方预置了 MessagesState——它就是一个已经写好 messages: Annotated[list[AnyMessage], add_messages] 的现成 State 类,你直接继承它再加自己的格子即可:
from langgraph.graph import MessagesState
class State(MessagesState): # 自带 messages 格子(含 add_messages reducer)
documents: list[str] # 按需追加自己的格子4.4 Pydantic 版 State(带校验)
TypedDict 只是"说明书",运行时不校验数据。若希望自动校验每个字段(类型错就报错、缺省值、字段约束),官方文档给出的选项是用 Pydantic 的 BaseModel:
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 # 默认值4.5 Overwrite:强制清空
一个反直觉的场景:格子挂了"合并"Reducer 后,返回空列表不会清空它——["a","b"] + [] 还是 ["a","b"]!那想清空怎么办?官方提供了专门的 Overwrite 类型,它的意思是"绕过 Reducer,直接替换":
from langgraph.types import Overwrite
def clear_errors(state: State):
return {"errors": Overwrite([])} # 强制把 errors 清成 [],而不是 [] 拼接上去4.6 输入 / 输出 / 私有 Schema
进阶技巧:State 里的某些格子只想让"中间节点"用,不想暴露给调用者(输入输出)。官方支持给图分别指定输入 Schema、输出 Schema,中间的完整 State 对外不可见:
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 对外不可见stream_mode="updates" 或指定 output_keys。第 05 章条件边:让图学会拐弯
普通边是"死脑筋",条件边是"活脑筋"——干完一步后,由一个函数看一眼白板,决定接下来去哪。这是 LangGraph 表达"if/else"和"循环"的核心机制。
5.1 条件边基本写法
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 节配合"编排者-执行者"模式一起讲。
return {"foo": ...}。想"边改状态边决定去向",用第 14 章的 Command。5.3 实战:智能客服路由
完整可运行的例子(依旧不需要 API Key——用关键词模拟"大模型分类",真实场景把 fake_classify 换成 LLM 调用即可,第 8.3 节会给出真实版):
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——一个函数通吃各家模型,换厂商只改一个字符串:
pip install -U langchain langchain-openai :: 用 Anthropic Claude 则装 langchain-anthropic;用 DeepSeek 装 langchain-deepseek :: 国产模型大多提供 OpenAI 兼容接口,用 langchain-openai 也能接(见下方 openai_api_base 写法)
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 泄露):
setx ANTHROPIC_API_KEY "sk-ant-xxxx" setx OPENAI_API_KEY "sk-xxxx" :: 设置完要【重开】cmd / VSCode 窗口才生效
export ANTHROPIC_API_KEY="sk-ant-xxxx" # 写进 ~/.bashrc 或 ~/.zshrc 永久生效
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,两者指向同一批类。
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)就是你给它的"外挂技能"。流程分三步:
- 用
@tool定义工具:一个普通函数 + 必须写 docstring(模型靠它理解这个工具干嘛用、什么时候用!):pythonfrom 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 - 把工具"绑"到模型上:告诉模型"你有哪些菜可以点":python
tools = [add, multiply, divide] llm_with_tools = llm.bind_tools(tools) # 返回一个"知道这些工具"的模型副本
- 看模型怎么"点菜"并替它执行:模型不会真的执行工具!它只是在回复里带上 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
第 07 章实战:从零手写 ReAct Agent
这是本教程的"毕业项目":把前面学的 State、Node、Edge、条件边、消息列表全部用上,手写一个能调用计算器工具的真 Agent。代码改编自官方 Quickstart 的计算器 Agent,逐段拆解。
7.1 Agent 的本质:一个循环
官方《Workflows and Agents》定义:Agent = LLM + 工具,在反馈循环里运行。画成图只有两个节点、一条回边:
模型看消息,要么回答要么点菜 →有菜→ tools
执行工具,结果回消息列表 →回到 llm_call(循环!) 没菜?→ END
那个"有菜没菜"的岔路口,就是我们第 5 章学的条件边。所谓 Agent,就是一张会转圈的图——这正是第 1 章说的"链条不能转圈,所以需要 LangGraph"。
7.2 完整代码(可复制运行)
新建 agent.py,这是完整程序(基于官方 Quickstart,把状态加上 llm_calls 计数器以方便观察):
# -*- 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:
from langgraph.errors import GraphRecursionError
try:
graph.invoke(inputs, config={"recursion_limit": 25}) # 注意:顶层 key,不进 configurable
except GraphRecursionError:
print("转了 25 拍还没收敛,强制叫停")官方推荐的"主动式"做法:把剩余步数放进 State,让条件边自己提前收手(比被动等报错优雅):
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 确认):
pip install -U langchain # create_agent 在 langchain 1.0 里
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 调用,前一步的输出是后一步的输入;中间可以插质量检查(不达标就重做)。适合能拆分、且每步效果可验证的任务,官方举例:先写笑话 → 检查笑点是否合格 → 不合格就改进 → 最后润色。
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 节的超步机制会自动让它们并行:
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")Annotated[list, operator.add],各节点返回 {"results": ["我这部分的结果"]} 自动拼接。8.3 模式三:路由(Routing)
思路:先用一次 LLM 给输入分类,再按类别分流到各自的专用流程。5.3 节的关键词版升级为真 LLM 版——官方推荐用结构化输出让分类结果强制成枚举:
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 动态开一份"子白板"给目标节点:
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(汇总)"["a","b"] 时,多个分支共享同一块白板;返回 Send("a", {...}) 时,每个分支拿到自己定制的输入(还能互不相同),汇总仍靠 Reducer 写回共享格子。子任务需要"独立输入"时用 Send——这是官方文档的说法:边数量未知、各分支需要不同 state 时。顺带认识官方预制件 ToolNode:一个现成的工具执行节点(第 7 章手写的 tool_node 官方版),自动处理并行工具执行、错误处理、状态注入,还能让工具直接读取图状态与运行上下文:
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_node8.5 模式五:评估者-优化者(Evaluator-Optimizer)
思路:一个 LLM 干活,另一个 LLM 挑刺,循环直到达标。适合有明确评价标准、需要反复打磨的任务(翻译、文案、代码优化)。图上就是一个带"质检回边"的循环:
@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)存起来。于是:
- 多轮对话记忆:下次接着上次的存档继续玩,模型自然记得之前聊过什么。
- 断点续跑 / 容错:进程崩了?读档,从最近一拍接着跑。
- 人工介入:执行到一半喊停(第 10 章),存档待命,随时继续。
- 时间旅行:读任意一个历史存档,改个决定重新走(第 15 章)。
启用方式——编译时传入,调用时带上 thread_id,就这么多:
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、互不干扰——每个用户的会话、每张工单的处理流程,各自一条线程:
thread_id="user-张三-chat":张三的聊天,永远连着他自己上文的记忆。thread_id="user-李四-chat":李四的聊天,跟张三的完全隔离。- 同一个 thread_id 再次 invoke:LangGraph 自动从该线程最近一次快照恢复白板,你的新输入追加进历史——这就是多轮记忆的全部原理。
9.3 实战:有记忆的聊天机器人
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 章说的"节点之间靠白板通信"加上"白板会自动存档接力"。
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 章判断"中断"就靠它 | — |
两个重要细节(官方文档原文归纳):
- 存档频率:每个 super-step 结束存一张完整快照;同时每个节点执行中的写入也逐条持久化(pending writes)——所以节点中途崩溃,恢复时已完成的写入不用重跑。
- checkpoint_ns(命名空间):父图是
"";子图是"节点名:uuid";嵌套子图用|串联。同一个 thread_id 下,父图和各子图各有各的存档链。
9.5 get_state 与状态历史
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-sqlite | SqliteSaver / AsyncSqliteSaver | 本地单机,存成 .db 文件 |
langgraph-checkpoint-postgres | PostgresSaver / AsyncPostgresSaver | 生产推荐 |
langgraph-checkpoint-mongodb / -redis | MongoDBSaver / RedisSaver 等 | 已有相应基础设施时 |
pip install langgraph-checkpoint-postgres
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": ...}}get_state 默认看不到子图内部,需要时用 get_state(config, subgraphs=True)。进阶:durability 持久化档位
存档多勤快、多较真,是可以调的(官方 checkpointers 文档)。stream / invoke 时传 durability 参数,三档:
| 档位 | 行为 | 取舍 |
|---|---|---|
"exit" | 只在图结束时存一次(成功 / 出错 / 中断) | 性能最好;进程中途崩溃,中间进度丢失 |
"async" | 每拍后台异步存(默认) | 性能与安全的平衡;极小概率丢最后一张 |
"sync" | 每拍同步存完才进下一拍 | 最可靠;有性能开销 |
graph.stream({"input": "test"}, durability="sync") # 关键业务可调高一档第 10 章Human-in-the-loop 人工介入
真 Agent 不能"放手就跑":删除数据库、发送邮件这类高危动作,必须人来点头。LangGraph 的 interrupt() 让图在任意位置"喊暂停",等人批复后再"续播"——而且可以等几秒,也可以等三天。
10.1 interrupt():喊一声"暂停"
类比:游戏打到 Boss 关卡前弹出确认框"确定要卖掉传说装备吗?"——游戏(图)原地挂起、进度已存档,你合上笔记本睡一觉,明天点"确定",游戏从完全相同的位置继续。
官方文档的定义要点:interrupt 是动态的——它可以放在代码任意位置、可以按业务条件触发(对比"静态断点"只能编译时固定在某个节点前后)。运行流程五步:
- 图跑到
interrupt(...)这行 → 立刻挂起; - 当前白板已由 checkpointer 存档;
- 问题文本作为"中断信息"返回给你的调用代码;
- 图无限期等待(进程甚至可以退出,存档在数据库里);
- 你带着人的答复调用
Command(resume=答复)→ 答复成为interrupt()的返回值,图继续往下跑。
from langgraph.types import interrupt
def approval_node(state: State):
# 挂起,把问题抛给调用方;恢复时,resume 值从这里"接上"
approved = interrupt("Do you approve this action?")
return {"approved": approved}10.2 最小可运行示例
完整跑一遍"暂停 → 等人 → 恢复"(不需要真模型,专注机制本身):
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) 组合,就是经典的审批分支:
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) → 走 cancel10.4 在工具内部中断
更实用的位置是工具内部——模型自主决定调用高危工具时,人自然被拉进审批流程。官方文档示例(发邮件前审批):
@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):
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 | 任务开始/结束(含结果与错误) | 监控 |
debug | checkpoints + tasks + 额外元数据 | 信息最全的排查模式 |
后三种需要编译时配 checkpointer。v1 老写法(网上旧教程常见)不再赘述,知道"旧版裸 dict / 元组,新版统一 StreamPart"即可平滑看懂旧代码。
11.2 LLM 逐字输出(打字机效果)
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(),想发什么发什么:
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 多模式组合
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 只带最近的消息
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 删除):
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)]}策略 C:摘要压缩(summarize)
官方推荐的中长期方案:把历史交给 LLM 压成一段 summary 存进 State(给 State 加 summary: str 格子),删掉旧消息只留最近两条;下轮把摘要作为上下文带上。骨架:
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"):
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 模型,检索就自动升级为按含义搜("我饿了"能搜到"我爱吃披萨"):
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"(按语义匹配上的)第 13 章子图 Subgraphs
图大了会乱。子图让你把一张图当成另一个图的一个"节点"来用——像函数封装代码一样封装流程。官方列出的三大场景:多智能体系统、跨图复用节点组、团队分工(只约定输入输出接口,互不关心内部实现)。
13.1 什么时候需要子图
- 多智能体:每个 Agent 本身就是一张图(第 7 章那种循环图),主图负责它们之间的调度。
- 复用:"检索子流程"在客服系统和知识库系统里都要用——做成子图到处插。
- 隔离:每个 Agent 想有自己的私有消息历史,不跟主图的 messages 混在一起——用子图 + 独立 State 实现。
13.2 两种添加方式
选哪种只看一件事:父图和子图的 State 字段共不共享。
方式 A:字段不同 → 包一层转换函数
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:字段相同 → 编译好的子图直接当节点
builder = StateGraph(State) # 父图
builder.add_node("node_1", subgraph) # ← 直接把编译后的子图传进去!
builder.add_edge(START, "node_1")子图会自动读写父图的共享通道(比如共享的 messages)。子图 State 也可以有父图没有的私有格子,互不打扰。第 7.6 节的 create_agent 返回的就是编译好的图,直接 add_node 就能作为子图嵌入你的大图。
subgraph_builder.compile(checkpointer=True)(per-thread 模式)。13.3 用子图搭多智能体
最简形态:主图(监督者)+ 若干专家子图。
决定派给哪个专家 →条件边→ researcher 子图 / writer 子图 / coder 子图 → 回到 supervisor …→ END
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
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 节的审批分支也是它。
14.3 跳到父图与注意事项
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(图从改写点继续跑,产生新分支):
# ① 遍历存档链,找到"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 之后的位置,带着改过的白板继续执行,走出新分支三个要点(官方文档):
update_state不改历史,而是新建一张快照挂在原位置后面——原时间线完好保留在get_state_history里(metadata["source"] == "update"的就是改写产生的分叉)。- 更新走正常 Reducer:带合并规则的格子是累加不是覆盖,别惊讶。
- Replay(重放):不 update、直接拿历史 checkpoint 的 config 去 invoke,就是"原样重演"那之后的节点。但注意官方说明:LLM 调用、API 请求和 interrupt 在重放时总会真实重新触发(它们不是录像回放,是真调用、真花钱)。
适用场景:Agent 第 3 步检索用了错误的关键词 → 回到第 3 步前改写查询 → 只重跑后半程,前两步不用再来一遍。
第 16 章Functional API 函数式写法
LangGraph 其实有两种写法:本教程主讲的 Graph API(画图),和官方提供的 Functional API(写普通函数 + 两个装饰器)。它俩共享同一套持久化、中断、流式基础设施。
16.1 @task 与 @entrypoint
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 把图画出来
# 方式一:导出 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 节的调试用法)。
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. 节点之间到底怎么传数据?能把一个节点的返回值直接给下一个节点吗?
2. 我的列表每次都被覆盖,只剩最后一条?
Annotated[list[str], operator.add] 或消息用 add_messages(第 4 章)。3. 并行节点同时写一个格子,报 InvalidUpdateError?
INVALID_CONCURRENT_GRAPH_UPDATE)。解法唯一:加 Reducer。即使今天不并行,以后随手加条边就会炸——凡是会被多节点写的格子,一律配 Reducer。4. invoke 报错说图必须先 compile?
StateGraph 对象只是"图纸",builder.compile() 之后才是可执行对象。检查是不是把 builder 直接 invoke 了。5. Agent 循环转个不停,最后 GraphRecursionError?
6. 配了 checkpointer 后 invoke 报错要求 thread_id?
{"configurable": {"thread_id": "xxx"}}。7. State 里该存什么、不该存什么?
8. 想清空一个挂了 Reducer 的列表,返回 [] 没效果?
旧 + [] 还是旧值。用 {"格子": Overwrite([])} 绕过 Reducer(4.5 节)。删除消息则要用 RemoveMessage(12.2 节)。9. interrupt 之后程序继续跑完了,没等我就执行了?
Command(resume=...)。10. interrupt 恢复后,中断前的代码又执行了一遍?
11. 节点里 try/except 一包,interrupt 就失效?
except Exception: 也会吞掉它。12. 模型下一轮报错,说找不到 tool_call 对应的消息?
tool_call_id,或带了 tool_calls 的 AI 消息没跟上 ToolMessage。逐条核对 7.3 节;删消息时保持配对完整(12.2 节)。13. 想让多个 LLM 同时跑,怎么写并行?
@task,最后统一 .result()(8.2 节)。不用碰 threading。14. 子任务数量运行时才知道,边没法提前画?
[Send("节点名", 各自输入), ...],动态开出任意多分支。15. 子图里的 token / 事件看不到了?
subgraphs=True,再按 chunk["ns"] 区分来源(11.4 节)。16. InMemorySaver 重启后记忆全丢,正常吗?
17. checkpoint 越积越多,数据库变大?
18. 一个 graph 对象能同时服务多个用户吗?
19. Command(resume=...) 之外,能把 Command(update=...) 当输入传吗?
resume 是唯一该作为 invoke 输入的 Command 形式;传 update 会让图从最近存档恢复、表现成"卡住"。继续对话请传普通字典输入。20. 旧教程的 create_react_agent / MemorySaver / MessageGraph 是什么?
create_react_agent 已弃用 → 用 LangChain 1.0 的 create_agent(7.6 节);MemorySaver = InMemorySaver 的旧名;MessageGraph 已淘汰 → 用 StateGraph(MessagesState)。1.0 承诺 2.0 前不破坏兼容,看到旧写法按此对照即可。21. Python 版本要求?异步节点有什么坑?
get_stream_writer(),要在签名里声明 writer: StreamWriter 参数(11.3 节)。22. graph.invoke 慢,怎么提速?
cache=InMemoryCache() + 节点 cache_policy(官方节点缓存,输出带 cached 标记);③ 检查是否在串行节点里塞了本可拆分的独立调用;④ 持久化模式选 durability="async" 平衡性能与安全。23. 每个节点都该拆多细?
24. 学习 LangGraph 必须先学 LangChain 吗?
第 19 章学习路线图与资源
你已经走完了从"什么是图"到"多智能体+时间旅行"的全部主干。接下来去哪、按什么顺序,官方资源都列在这里。
19.1 学完本教程后去哪
- 把第 7 章的 Agent 改造成你自己的:换工具(查数据库/调内部 API/读文件)、换 State、加 checkpointer——这是最快的内化方式。
- 做一个完整的 HITL 应用:参考第 10 章给高危工具加审批,配 SQLite 存档,跑通"暂停-重启进程-恢复"全流程。
- 上一个真实模式:从第 8 章五模式里挑一个贴你业务的,或用子图拼一个监督者多智能体(13.3)。
- 补官方课程:LangChain Academy 免费课《Introduction to LangGraph》(含配套代码仓),跟本教程互补——它是视频+实操,本教程是逐行拆解。
- 进阶专题:部署(官方有 LangGraph Platform / 自托管 Server,持久化自动托管)、Deep Agents(官方高层封装:规划+子 Agent+文件系统)、LangSmith 评估。
19.2 官方学习资源
| 资源 | 地址 | 说明 |
|---|---|---|
| 官方文档(Python) | docs.langchain.com/oss/python/langgraph | 本教程主要依据;有 llms.txt 全站索引 |
| GitHub 仓库 | github.com/langchain-ai/langgraph | README、示例、Releases、Issues(报错先搜这里) |
| API 参考 | reference.langchain.com/python/langgraph | 全部类与函数签名 |
| 免费视频课 | academy.langchain.com | LangChain Academy 官方入门课 |
| 官方论坛 | forum.langchain.com | 提问与版本公告(如 1.0 alpha 公告) |
| 案例集 | langchain.com/built-with-langgraph | Klarna、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 速查表
# ---- 构建 ----
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):
- GitHub:github.com/langchain-ai/langgraph(MIT 协议)
- 官方文档总览:docs.langchain.com/oss/python/langgraph/overview
- Graph API:…/graph-api · Quickstart:…/quickstart
- 持久化:…/persistence · Checkpointers:…/checkpointers
- 中断:…/interrupts · 流式:…/streaming · 记忆:…/add-memory
- 子图:…/use-subgraphs · 设计思维:…/thinking-in-langgraph · 模式:…/workflows-agents
- 发布博客(2024-01):langchain.com/blog/langgraph
- 1.0 发布公告(2025-10-22):langchain.com / 论坛公告 forum.langchain.com
注:LangChain 团队未发布过 LangGraph 官方 arXiv 论文;学术引用请引用其 GitHub 仓库与官方文档。