📑目录
- [一、LangGraph 状态管理:持久化](#一、LangGraph 状态管理:持久化)
- [1.1 什么是持久化能力?](#1.1 什么是持久化能力?)
- [1.2 线程级持久化](#1.2 线程级持久化)
- [1.2.1 线程级持久化运行机制](#1.2.1 线程级持久化运行机制)
- [1.2.2 线程级持久化操作方式](#1.2.2 线程级持久化操作方式)
- [1.3 跨会话持久化:长期记忆与 Store](#1.3 跨会话持久化:长期记忆与 Store)
- [1.3.1 基于 InMemoryStore 的长期记忆](#1.3.1 基于 InMemoryStore 的长期记忆)
- [1.3.2 基于 PostgresStore 的长期记忆](#1.3.2 基于 PostgresStore 的长期记忆)
- [1.4 持久化实现的三大应用能力](#1.4 持久化实现的三大应用能力)
- [1.4.1 记忆](#1.4.1 记忆)
- [1.4.2 人机交互](#1.4.2 人机交互)
- [1.4.3 时间旅行](#1.4.3 时间旅行)
- [1.5 持久化总结](#1.5 持久化总结)
- [二、LangGraph 运行控制:上下文、流式与子图](#二、LangGraph 运行控制:上下文、流式与子图)
- [2.1 运行时上下文 (Runtime Context)](#2.1 运行时上下文 (Runtime Context))
- [2.1.1 上下文的分类](#2.1.1 上下文的分类)
- [2.1.2 配置与访问上下文](#2.1.2 配置与访问上下文)
- [2.1.3 在工具 (Tools) 中访问上下文](#2.1.3 在工具 (Tools) 中访问上下文)
- [2.2 流式传输 (Streaming)](#2.2 流式传输 (Streaming))
- [2.2.1 五种流模式 (Stream Modes)](#2.2.1 五种流模式 (Stream Modes))
- [2.2.2 流式传输自定义数据 (Custom Stream)](#2.2.2 流式传输自定义数据 (Custom Stream))
- [2.2.3 流式传输 LLM Tokens (messages 模式)](#2.2.3 流式传输 LLM Tokens (messages 模式))
- [2.3 子图 (Subgraphs)](#2.3 子图 (Subgraphs))
- [2.3.1 使用子图的方式一:节点内调用(不同状态模式)](#2.3.1 使用子图的方式一:节点内调用(不同状态模式))
- [2.3.2 使用子图的方式二:作为节点添加(共享状态模式)](#2.3.2 使用子图的方式二:作为节点添加(共享状态模式))
- [2.3.3 子图与持久化 (Checkpoint)](#2.3.3 子图与持久化 (Checkpoint))
- [2.3.4 子图与中断(Interrupt)的交互陷阱](#2.3.4 子图与中断(Interrupt)的交互陷阱)
- [2.1 运行时上下文 (Runtime Context)](#2.1 运行时上下文 (Runtime Context))
在前面的文章中,我们已经掌握了如何通过 StateGraph 编排各种复杂的工作流模式。然而,要真正将 AI Agent 落地到企业级生产环境,光有"骨架"是不够的。
当服务崩溃时,如何保住对话状态?当图结构过于庞大时,如何优雅地拆分?当大模型回复较慢时,如何实现丝滑的打字机效果?这就要求我们必须掌握 LangGraph 的底层基建能力。
一、LangGraph 状态管理:持久化
1.1 什么是持久化能力?
简单来说,持久化(Persistence)是指将 AI 应用运行过程中的状态(如对话历史、中间结果、工具调用记录等)保存到外部存储中,确保程序重启或中断后能恢复之前的现场。
默认情况下,基于 HTTP 请求的大模型(LLM)应用是无状态(Stateless)的。每一次请求或进程重启,如果没有外部机制的干预,系统将丢失所有的上下文信息。在复杂的 Agent 或 RAG(检索增强生成)工作流中,这种无状态性会导致严重的问题:
-
重复计算与成本浪费:当工作流中断(如服务端重启、网络超时)后重试,系统可能会重新执行昂贵的工具调用(如重新调用搜索引擎或数据库)。
-
上下文断裂:多轮对话中,如果丢失了之前的历史记录或工具执行结果,模型将无法进行连贯的推理,导致答非所问。
-
无法支持异步审批(Human-in-the-loop):当工作流需要挂起等待人工审核时,如果没有持久化,挂起期间系统状态将无法保留。
架构对比:无持久化 vs 持久化
以带有"工具调用"的智能助手为例,对比系统在崩溃重启前后的表现:
❌ 无持久化(Stateless)
Turn 1:用户输入:"今天的天气怎么样?"
Action:节点调用 Search 工具,得到结果 {"weather": "晴天, 25度"},返回给用户。
Crash:服务进程发生重启(或开启新会话)。
Turn 2:用户输入:"那我需要带伞吗?"
Action:由于丢失了 Turn 1 的上下文(即天气信息),LLM 无法基于已有事实推理,只能再次调用 Search 工具判断天气,导致不必要的 Token 和 API 开销。
✅ 有持久化(Stateful / Checkpointed)Turn 1:用户输入天气问题,工作流调用工具得到结果。
Save:系统将当前完整的 State(包含用户输入、LLM 输出、工具调用记录)自动保存为快照(Checkpoint)。
Crash:服务进程重启。
Turn 2:用户输入:"那我需要带伞吗?"
Resume:LangGraph 通过 Thread ID 加载之前的快照,恢复完整的图状态。LLM 读取到上下文中的天气信息,直接输出:"今天是晴天,不需要带伞",无需再次调用工具
在 LangGraph 中,持久化能力具体包含两个独立维度的能力: 线程级 与 跨会话级 。
- 线程级持久化 (Thread-level Persistence)
-
定义 :能够自动保存工作流执行过程中的
状态快照 (State Snapshot),维持单次会话的完整上下文。 -
概念澄清:这里的"线程"与操作系统中的进程/线程概念完全独立,它特指"单次聊天会话"。系统通过不同的线程 ID 来隔离不同的对话。
-
状态快照:它并非单一的 State,而是包含了所有必要的上下文信息,比如:已经调用过哪些工具、用户的输入、聊天历史、下一步要执行的节点等元数据。
- 跨会话持久化 (Cross-session Persistence)
-
定义:通过长期存储 (Store) 保存用户信息、偏好设置等长期数据,实现不同对话之间的持久化信息共享。
-
典型场景:例如,将用户基本情况(如"有高血压病史")存储在 Store 中。无论用户在何时何地、新开几个会话窗口,Agent 都能读取该信息并基于此生成个性化的结果。
1.2 线程级持久化
1.2.1 线程级持久化运行机制
机制概述
在执行复杂工作流时,系统可能会面临崩溃或重启导致的意外中断。线程级持久化(Thread-level Persistence)的核心机制是:在流程执行过程中,自动捕获并保存每一个步骤的 状态快照(State Snapshot)。
该快照不仅包含基础的对话历史,还完整记录了上下文信息,如:已调用的工具、中间结果、当前节点位置以及下一步要执行的路由。这种机制构成了 LangGraph 容错与断点续传的基础。
核心执行流程
结合持久化机制,工作流的执行路径包含以下三种情况:
- 正常执行路径
-
启动:工作流启动,初始化上下文(加载用户输入和当前线程内的历史状态)。
-
执行与保存:节点按既定规则依次执行(如步骤 1 -> 步骤 2 -> 步骤 3)。每执行完一个节点,系统都会自动触发 Checkpointer,将当前状态序列化为快照并持久化存储。
-
终止:所有节点执行完毕,工作流正常退出,最新状态快照被完整保留。
- 异常恢复路径
-
中断:工作流执行到某一步骤时,发生服务崩溃或进程重启,导致当前内存中的状态丢失。
-
恢复:系统重启后,通过 thread_id 定位到该会话最近一次成功保存的检查点。读取该快照,恢复上下文,并从中断的节点继续往下执行,避免从头重试造成的 Token 浪费。
- **检查点回滚路径 **
-
触发:在某些业务场景下(例如人工审核不通过、或调试流程),需要撤销最近的执行结果。
-
回滚:系统允许从底层的持久化存储中,选择一个历史时间点的快照(例如回滚到状态 1 或状态 2)。
-
重演:以该快照为基础,重新执行后续节点。这赋予了系统类似于"时间旅行"的能力,极大地方便了调试和业务逻辑修正。
📌 该机制确保了 AI 应用具备以下工程特性:
- 状态不丢失:即使发生硬件故障或服务重启,也能从上次停止的地方恢复,而不是从头开始。
- 支持长耗时任务:对于需要多轮交互(如对话助手)或等待外部 API 回调的耗时流程,持久化是必不可少的底层支撑。
- 历史回溯:允许开发者或高级用户将系统状态回滚到任意一个已保存的"检查点",进行状态重演或分支测试。
核心概念
LangGraph 的线程级持久化机制通过两个核心抽象组件来实现:【线程 (Threads)】 和 【检查点 (Checkpoints)】。
Threads (线程)
在 LangGraph 中,Thread 代表一个独立的工作流执行会话(Session)。它相当于某个特定任务的完整执行生命周期或某次多轮对话的上下文容器。
Thread 的关键技术特性:
-
强隔离性:每个 Thread 都是完全独立且隔离的。不同 Thread 之间的状态(State)互不干扰,确保多用户并发或同一用户多任务并发时的数据安全。
-
持久化单元:Thread 是 LangGraph 进行状态持久化的基础单位。
-
唯一标识符:系统通过全局唯一的 thread_id 来识别和路由不同的会话。
示例:在同一个 thread_id 的会话中,助手能够持续记住用户之前透露的身份信息(如姓名、年龄、爱好),因为底层一直在读取同一个 Thread 的历史上下文。

Checkpoints (检查点)
Checkpoint 是 Thread 在特定时刻的【状态快照 (State Snapshot)】。它精确记录了工作流在每一个执行节点前后的完整状态。在一个 Thread 的生命周期内,每次用户输入或系统回复结束时,都会自动生成并保存一个 Checkpoint。
核心数据结构:StateSnapshot
每个 Checkpoint 都包含一个 StateSnapshot 对象,其核心字段结构如下(简化版伪代码):
python
StateSnapshot(
# 1. 当前状态值(如对话消息列表、业务数据)
values={'messages': [HumanMessage(...), AIMessage(...)]},
# 2. 接下来要执行的节点(用于断点恢复)
next=('generate_response',),
# 3. 配置信息(关联的 thread_id 和 checkpoint_id)
config={'configurable': {'thread_id': '123', 'checkpoint_id': 'abc'}},
# 4. 元数据(步骤号 step、来源 source、写入信息等)
metadata={'step': 2, 'source': 'loop', 'writes': {...}},
# 5. 父检查点(形成链表,用于追溯历史)
parent_config={'configurable': {'thread_id': '123', 'checkpoint_id': 'def...'}},
# 6. 创建时间
created_at='...'
)
(注:实际运行输出的 StateSnapshot 对象会包含大量 LLM 调用的元数据(如 Token 消耗量、模型版本等),开发者主要关注 values 和 next 字段。)
Checkpoint 的核心能力:版本历史与可恢复点
由于 StateSnapshot 中记录了 parent_config,一个 Thread 下的所有 Checkpoints 实际上构成了一个单向链表。这意味着:
-
一个 Thread 包含多个 Checkpoints,形成完整的执行历史。
-
开发者可以从任意的 Checkpoint 节点追溯和访问状态。
-
回滚(Time Travel):如果发生异常或业务需要,可以直接将状态恢复到指定的历史 Checkpoint 重新执行。
Threads 和 Checkpoint 的关系如下:

1.2.2 线程级持久化操作方式
要让 LangGraph 具备线程级持久化能力,核心在于编译图时注入 checkpointer,并在运行时指定唯一的 thread_id。
步骤一:配置 Checkpointer 存储后端
LangGraph 允许在不同的环境中使用不同的持久化后端。编译图时,将实例化的 Saver 传给 checkpointer 参数。
- 内存存储
状态保存在 Python 进程内存中。程序重启后数据丢失,适合快速验证。
python
from langgraph.checkpoint.memory import InMemorySaver
# 定义存储方式
checkpointer = InMemorySaver()
# 编译图时注入
agent = agent_builder.compile(checkpointer=checkpointer)
- 关系型数据库存储
对于生产环境,需要使用如 PostgreSQL 或 SQLite 等具备事务支持的持久化数据库。LangGraph 官方提供了对应的包(如 langgraph-checkpoint-postgres)。
以 PostgreSQL 为例,推荐使用 PostgresSaver:
python
import psycopg
from langgraph.checkpoint.postgres import PostgresSaver
# 1. 配置数据库连接 URI
DB_URI = "postgresql://postgres:123@127.0.0.1:5432/postgres"
# 2. 建立连接并使用 PostgresSaver
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
# 首次使用需调用 setup() 初始化数据库表结构
checkpointer.setup()
# 编译图
agent = agent_builder.compile(checkpointer=checkpointer)
(注:首次运行需执行 checkpointer.setup(),它会在库中自动创建 checkpoints、checkpoint_blobs 等核心表。)
步骤二:基于 Thread ID 运行与状态隔离
在调用图时,必须在 config 中传入 thread_id。
-
如果 ID 不存在:创建新 Thread,从初始状态开始。
-
如果 ID 已存在:自动加载该 Thread 最新的 Checkpoint,延续上下文。
python
from langchain.messages import HumanMessage
# 配置 thread_id="1"
config = {"configurable": {"thread_id": "1"}}
# 第一次调用(此时数据库中无记录,全新开始)
# 提问:今天西安的天气如何?
result1 = agent.invoke(
{"messages": [HumanMessage(content="今天西安的天气如何?")]},
config
)
# 此时,PostgreSQL 中已自动保存了多个 Checkpoints(用户输入前、LLM调用后、工具调用后等)。
# ==========================================
# 假设此时服务发生崩溃重启,或者用户第二天再次打开应用
# ==========================================
# 第二次调用(使用相同的 thread_id="1")
# 提问:我们刚才聊到哪了?
result2 = agent.invoke(
{"messages": [HumanMessage(content="我们刚才聊到哪了?")]},
config
)
# LangGraph 会从 PostgreSQL 加载 thread_id="1" 的历史状态。
# 模型能成功回答出之前关于"西安天气"的上下文,无需重新调用天气工具。
状态检查与管理 API (State Management)
LangGraph 提供了一系列内置方法,让开发者可以像操作 Git 一样操作工作流的状态。
- 获取当前状态快照 (get_state)
通过该方法可以获取指定 Thread 的最新状态对象 StateSnapshot,包含当前值、下一步执行的节点、配置和元数据等。
python
# 获取当前状态
snapshot = agent.get_state(config)
print(snapshot.values) # 当前的状态数据(如 messages 列表)
print(snapshot.next) # 下一步要执行的节点,如果是空元组 () 则表示已结束
- 获取历史记录 (get_state_history)
返回指定 Thread 的所有历史 StateSnapshot 列表。列表按时间倒序排列,第一个元素是最新快照。
python
# 获取历史记录
history = list(agent.get_state_history(config))
for state in history:
print(f"Checkpoint ID: {state.config['configurable']['checkpoint_id']}")
print(f"当前消息数: {len(state.values['messages'])}")
print(f"下一节点: {state.next}")
- 状态重放 (Replay)
应用场景:如果某次执行结果不理想,或者发生了业务逻辑错误,开发者可以"时间旅行"回退到某个特定的 checkpoint_id,重新执行后续步骤。
python
# 假设我们通过 history 找到了一个调用 LLM 前的状态(例如此时只有 2 条消息)
to_replay = history[2]
# 直接使用该历史快照的 config 重新执行
# 注意:这里传入 None 作为新输入,直接重放该检查点之后的路由
result_replay = agent.invoke(None, config=to_replay.config)
# 这会生成新的分支,并且历史记录中会追加新的重放轨迹。
- 更新状态与重放 (Update State & Replay)
应用场景:在人工介入(Human-in-the-loop)场景或流程调试时,我们需要强行修改某个历史节点的运行状态(例如:修正用户的输入、纠正模型的幻觉)。此时可以使用 update_state 方法,它会基于指定的 checkpoint 产生一个新的分支。
python
from langchain_core.messages import HumanMessage
from langgraph.types import Overwrite
# 假设第一次执行"今天西安的天气如何?"后,获取了历史记录 history
# 我们找到第一次调用 LLM 前的检查点(此时只有 1 条消息,next 是 llm_call)
selected_state = history[-2]
# 根据该检查点的 config,更新状态
# 注意:这里使用 Overwrite 是为了绕过 state 默认的 reducer(如追加),强制覆盖原有的消息列表
new_config = agent.update_state(
selected_state.config,
{"messages": Overwrite([HumanMessage(content="今天北京的天气如何?")])}
)
print(f"更新前配置: {selected_state.config}")
print(f"更新后配置: {new_config}")
# 基于更新后的 config 重新执行(此时传入 None 表示沿用历史状态继续往下走)
result2 = agent.invoke(None, config=new_config)
for message in result2['messages']:
message.pretty_print()
执行结果关键日志截取:
text
第一次执行历史:
checkpoint_id: 1f0cf6c8-743c... 消息数: 4 下一节点: ()
checkpoint_id: 1f0cf6c8-4244... 消息数: 3 下一节点: ('llm_call',)
...
更新前配置: {'configurable': {'thread_id': '1', 'checkpoint_id': '1f0cf6c8-1b1c...'}}
更新后配置: {'configurable': {'thread_id': '1', 'checkpoint_id': '1f0cf6c8-7444...'}} # 生成了新的 Checkpoint
================================ Human Message =================================
今天北京的天气如何?
================================== Ai Message ==================================
Tool Calls:
tavily_search (call_FFuFDwThpNTBHoijgvNmwtMr)
Args:
query: 北京天气
================================= Tool Message =================================
(省略工具调用详细日志...)
================================== Ai Message ==================================
今天北京的天气情况如下:
- 当前气温:-4℃
- 湿度:23%
- 风速:25.2 km/h
- 天气状况:晴朗
- 最高气温:预计为16℃
执行结果解析:
- 生成新分支:从控制台输出可以看出,update_state 生成了一个全新的 checkpoint_id(如 1f0cf6c8-7444...),它与原分支分离。
- 意图被成功篡改:重新执行后,系统打印出了 Human Message: 今天北京的天气如何?。原本的"西安"被成功覆盖为"北京"。
- 下游逻辑正常流转:由于输入变了,LLM 的决策也随之改变,系统自动调用了 tavily_search 工具去搜索"北京天气",并最终返回了北京的气温、湿度和风速信息(注:这证明了状态更新成功触发了新一轮的工具调用)。
1.3 跨会话持久化:长期记忆与 Store
痛点:Checkpoint 的局限性
在上一节中,Checkpoint(检查点) 机制完美解决了单次会话内的记忆问题(基于相同的 thread_id)。但在实际业务中,往往存在跨会话的需求:
星期一,用户开启了对话 A 询问推荐餐厅。
星期二,用户开启了对话 B,此时 thread_id 发生了变化。由于不同的 thread_id 是绝对隔离的,AI 将完全忘记用户昨天说过"我爱吃汉堡",导致每次都要"重新认识"。
现实世界的业务需求:
如智能客服系统,需要识别 VIP 客户并优先服务、避免重复询问相同问题、基于历史投诉记录优化服务。仅依赖 checkpointer 无法跨线程共享状态,我们需要一种能识别"同一个用户"的机制。
架构演变:引入 Store
为了解决跨会话记忆,LangGraph 引入了 Store(长期存储) 概念。
-
Checkpoint:保存的是状态变化历史(时间线),按 thread_id 隔离,解决单次会话的连贯性。
-
Store:保存的是结构化知识(数据库),按 user_id(或自定义 Namespace)隔离,解决跨会话、跨线程的共享数据(如用户画像、偏好标签等)。

AI 记忆能力的范式转变:
-
无状态 AI(石器时代):每次对话都是陌生人。 -
Checkpoint(工业革命):单次对话有记忆,但明天就忘记。 -
Checkpoint + Store(智能时代):终身记忆,持续学习。从关注单次交互转向关注用户生命周期。
1.3.1 基于 InMemoryStore 的长期记忆
要使用 Store,需要在编译图时同时传入 checkpointer 和 store 实例,并为每次请求指定 user_id。
- Store 的基本用法
Store 本身是通过 Namespace(命名空间) 来区分数据的。推荐使用元组 (user_id, 数据类型) 来划分层级,避免使用易混淆的扁平字符串。

python
from langgraph.store.memory import InMemoryStore
import uuid
store = InMemoryStore()
# 定义命名空间:(用户ID, 记忆类型)
user_id = "user_123"
namespace = (user_id, "preferences")
# 存入记忆:需要唯一的 memory_id
memory_id = str(uuid.uuid4())
memory_value = {"favorite_food": "汉堡", "allergy": "花粉"}
# store.put() 将内存保存到存储中的命名空间
store.put(namespace, memory_id, memory_value)
# store.search() 读取记忆:搜索该命名空间下的所有记忆
all_memories = store.search(namespace)
for mem in all_memories:
print(mem.dict())
运行结果
text
{
'namespace': [
'user_123', 'preferences'
],
'key': 'db826e33-c68c-4669-a79a-3579bff02ff1',
'value': {
'favorite_food': '汉堡',
'allergy': '花粉'
},
'created_at': '2025-12-03T08:16:14.134568+00:00',
'updated_at': '2025-12-03T08:16:14.134576+00:00',
'score': None
}
- 在 LangGraph 节点中使用 Store
我们需要在图的流程中,加入"提取用户信息存入 Store"和"从 Store 检索信息注入 Prompt"的逻辑。

相比于一般的图流程,新增信息提取节点:利用 LLM 的结构化输出(Structured Output),从用户的最新对话中提取姓名、偏好等信息。(注入 Store 参数:任何节点函数都可以通过在参数中声明 store: BaseStore 和 config: RunnableConfig 来访问全局存储。)
python
import uuid
from typing import Optional
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.runnables import RunnableConfig
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.store.base import BaseStore
from langgraph.store.memory import InMemoryStore
from pydantic import BaseModel, Field
# ... (省略模型初始化和 State 定义,假设使用 MessagesState) ...
# 1. 定义结构化提取模型
class Person(BaseModel):
name: Optional[str] = Field(default=None, description="这个人的名字")
favourite_food: Optional[list[str]] = Field(default=None, description="最喜欢的食物列表")
model_with_structured = model.with_structured_output(Person)
# 2. 提取用户信息节点
def get_person_by_llm(state: MessagesState, config: RunnableConfig, *, store: BaseStore):
"""通过 LLM 提取用户信息并存入 Store"""
# 提取最近3条消息中的信息
people_info = model_with_structured.invoke(
[SystemMessage(content="你是一个提取信息的专家,只提取当前用户的相关信息,如果不知道属性值返回null。")]
+ state["messages"][-3:]
)
user_id = config["configurable"]["user_id"]
# 存入基本信息 (生产环境建议先 search 判断是否存在,存在则更新,避免重复 put)
namespace_info = (user_id, "info")
store.put(namespace_info, str(uuid.uuid4()), {"name": people_info.name})
# 存入偏好信息
namespace_pref = (user_id, "preferences")
store.put(namespace_pref, str(uuid.uuid4()), {"favourite_food": people_info.favourite_food})
return {"llm_calls": state.get("llm_calls", 0) + 1}
# 3. 更新模型调用节点(注入记忆)
def llm_call(state: MessagesState, config: RunnableConfig, *, store: BaseStore):
user_id = config["configurable"]["user_id"]
# 从 Store 查询用户信息
info_result = store.search((user_id, "info"))
pref_result = store.search((user_id, "preferences"))
# 将记忆注入 System Prompt
system_msg = f"你是一个乐于助人的助手,支持工具调用。\n查询 LLM 前可参考以下信息:\n"
if info_result:
system_msg += f"1. 用户基本情况:{info_result[0].value}\n"
if pref_result:
system_msg += f"2. 用户偏好情况:{pref_result[0].value}\n"
# 调用大模型... (省略具体工具调用逻辑)
# return {"messages": [model_with_tools.invoke([SystemMessage(content=system_msg)] + state["messages"])]}
运行验证
python
checkpointer = InMemorySaver()
store = InMemoryStore()
agent = agent_builder.compile(checkpointer=checkpointer, store=store)
# 第一次聊天:用户透露了信息 (thread_id="1")
config1 = {"configurable": {"thread_id": "1", "user_id": "user_123"}}
agent.invoke({"messages": [HumanMessage(content="我叫李华,我最爱吃汉堡。我的朋友叫小明,他爱吃披萨")]}, config1)
# 几天后,再次进行对话 (thread_id="2",但是同一个 user_id)
config2 = {"configurable": {"thread_id": "2", "user_id": "user_123"}}
result2 = agent.invoke({"messages": [HumanMessage(content="给我推荐下餐厅")]}, config2)
# 运行结果证明:虽然换了会话(thread_id不同),但 AI 成功回忆起偏好,触发了搜索"推荐汉堡餐厅"的工具调用。
- 进阶特性:语义搜索
Store 的强大之处在于支持语义搜索(Semantic Search),而不仅仅是精确匹配。我们可以用自然语言来查询相关记忆。(需要在初始化 Store 时配置嵌入模型(Embedding Model))
python
from langchain_openai import OpenAIEmbeddings # 或其他嵌入模型
store = InMemoryStore(
index={
"embed": init_embeddings("openai:text-embedding-3-small"), # 嵌入模型
"dims": 1536, # 嵌入向量的维度
"fields": ["$"] # 对 value 中的所有字段进行嵌入
}
)
# 在节点中进行语义搜索
# 找出最相关的 2 个记忆
info_result = store.search((user_id,), query="用户基本信息", limit=2)
(注:如果我们让AI助⼿能记住用户的更多信息(比如不喜欢的东西、上次聊到的话题记录等)。在新的对话,语义搜索可以把历史记录中的相关记忆找出来,帮助AI助⼿进行更加准确的回复。)
1.3.2 基于 PostgresStore 的长期记忆
InMemoryStore 仅适用于测试,生产环境同样需要将 Store 持久化到数据库(如 PostgreSQL)。
python
from langgraph.store.postgres import PostgresStore
DB_URI = "postgresql://postgres:bit@192.168.100.233:5432/postgres"
with (
PostgresSaver.from_conn_string(DB_URI) as checkpointer,
PostgresStore.from_conn_string(DB_URI) as store,
):
# 首次使用需初始化表结构
checkpointer.setup()
store.setup()
# 编译图
agent = agent_builder.compile(checkpointer=checkpointer, store=store)
# ... 后续调用 ...

(说明:可以看到 store 表中,prefix(命名空间)记录了 user_id 和 info/preferences,value 以 JSONB 格式存储了提取的键值对。)
1.4 持久化实现的三大应用能力
1.4.1 记忆
在 AI Agent 领域,记忆(Memory) 是指系统能够记住历史交互信息,并据此调整后续行为的能力。
需要明确区分底层架构与应用能力:
-
底层持久化能力:线程级持久化(Checkpoint)与跨会话持久化(Store)。
-
应用层记忆能力:
- 短期记忆:通过 线程级持久化 实现,维持单次会话的上下文。
- 长期记忆:通过 跨会话持久化 实现,保存用户画像或应用级别的长期数据。

管理短期记忆
在长对话场景中,受限于 LLM 的上下文窗口,必须对短期记忆进行管理。LangGraph 提供了以下几种机制:
- 修剪消息 (Trimming)
使用 LangChain 的 trim_messages 工具,根据 Token 数量截断历史记录。
python
from langchain_core.messages.utils import trim_messages
def call_model(state: MessagesState):
# 只保留最近的 128 个 token,从 human 消息开始截断
messages = trim_messages(
state["messages"],
strategy="last",
token_counter=model,
max_tokens=128,
start_on="human",
end_on=("human", "tool"),
)
response = model.invoke(messages)
return {"messages": [response]}
- 删除消息 (Deletion)
通过返回 RemoveMessage 对象,可以从图状态中物理删除特定消息。
python
from langchain_core.messages import RemoveMessage
from langgraph.graph.message import REMOVE_ALL_MESSAGES
def call_model(state: MessagesState):
messages = state["messages"]
if len(messages) > 6:
# 删除最早的6条消息
return {"messages": [RemoveMessage(id=m.id) for m in messages[:6]]}
# 或者直接清空所有消息(慎用)
# return {"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES)]}
return {"messages": [model.invoke(messages)]}
- 总结消息 (Summarization)
为了避免直接删除导致关键信息丢失,最佳实践是:让 LLM 将旧的对话历史总结为一段摘要,并用摘要替换掉原始消息。
python
# 扩展 State,增加 summary 字段
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)
# 返回新摘要,并删除旧的历史消息(保留最后一条)
return {
"summary": response.content,
"messages": [RemoveMessage(id=m.id) for m in state["messages"][:-1]]
}
📌 扩展:LangMem 是⼀个由 LangChain 维护的库。它提供了可与任何存储系统⼀起使⽤的功能原语,也提供了与LangGraph存储层的本机集成。例如上述我们⼿动完成的汇总消息功能,在LangMem中专⻔提供了记忆管理库(如:SummarizationNode),简化了总结消息的过程。
1.4.2 人机交互
中断 (Interrupts)
人机交互允许在 AI 自动执行的流程中插入"暂停键",等待人类输入后再继续。LangGraph 通过基于持久化实现的 中断(Interrupt) 能力来完成这一操作。
当一个节点调用 interrupt() 时:
-
图会抛出一个特殊的异常,中断当前执行。
-
系统利用 Checkpointer 自动保存当前完整的图状态。
-
外部系统(如 UI 界面)获取到中断信息,等待人类操作。
-
人类操作完成后,通过传入 Command(resume=...) 恢复执行。

基础用法
python
from langgraph.types import interrupt, Command
def hello_node(state: State):
# 主动触发中断,向外传递提示信息
human_response = interrupt("暂停,是否继续?")
if human_response == "yes":
return {"output": "继续执行!"}
return {"output": "已取消"}
# ... 编译图时必须传入 checkpointer ...
# graph = builder.compile(checkpointer=InMemorySaver())
# 1. 首次调用,触发中断
first_run = graph.invoke({"input": "hi"}, config)
# 返回结果:{'input': 'hi', '__interrupt__': [Interrupt(value='暂停,是否继续?', id='4ae0b600ed582ace5f23105b46afb780')]}
# 2. 人类决策后,恢复执行
# resume表⽰传回AI的响应值
# 必须使⽤ thread_id 运⾏Graph,相当于告诉系统读哪个存档。
second_run = graph.invoke(Command(resume="no"), config)
中断的黄金法则
使用中断时,必须遵守以下四条原则,否则会导致系统异常:
-
只传可序列化的数据:由于中断状态需要存入数据库,传递的参数必须能被 JSON 序列化。绝不能传函数、类实例或数据库连接等复杂对象。
-
绝不要包裹在 try/except Exception 中:interrupt() 内部是通过抛出特殊异常来实现挂起的。如果你的代码写成了 try: interrupt(...) except Exception:,会吞掉这个特殊异常,导致中断失效。
-
保证中断前的代码是幂等的:当恢复执行时,LangGraph 会从该节点的第一行代码重新跑一遍。如果在 interrupt() 之前有副作用操作(如写入数据库、发送邮件),这些操作会被重复执行。必须将其改为幂等操作(如 upsert),或移到 interrupt() 之后。
-
中断顺序必须固定:如果一个节点内有多个 interrupt(),LangGraph 会根据索引顺序(resume 列表)来匹配返回值。如果业务逻辑导致中断顺序变化(如条件分支),会导致取值错乱。
典型应用场景实战
- 场景一:审批与拒绝 (在执行高危操作前拦截,并根据审批结果动态路由)
python
from langgraph.types import Command, interrupt
def approval_node(state: State) -> Command[Literal["proceed", "cancel"]]:
# 触发审批中断
decision = interrupt({
"question": "批准此操作?",
"details": state["action_details"],
})
# 根据 resume 传入的布尔值进行动态路由到对应节点
return Command(goto="proceed" if decision else "cancel")
# 中间过程...
#用决策恢复执行:True路由到proceed,False路由到cancel
resumed = graph.invoke(Command(resume=True),config=config)
- 场景二:查看与编辑状态 (允许人类在流程中修改 AI 生成的内容,并将修改后的内容写回状态)
python
def review_node(state: State):
# 将 AI 生成的内容暴露给人类
updated_text = interrupt({
"instruction": "查看并编辑此内容",
"content": state["generated_text"],
})
# 将人类的返回值直接覆盖原状态
return {"generated_text": updated_text}
# 中间过程 ...
final_state = graph.invoke(Command(resume="审稿后的改进稿"),config=config)
- 场景三:工具中断 (中断逻辑可以内置于工具函数内部。这使得工具具有"智能感知审批"的能力,可以被任何图复用)
python
from langchain.tools import tool
@tool
def send_email(to: str, subject: str, body: str):
"""发送邮件"""
# 工具内部发起中断
response = interrupt({
"action": "发送邮件",
"to": to, "subject": subject, "body": body,
"message": "同意发送这封邮件吗?"
})
if response.get("action") == "同意":
# 执行真实发送逻辑...
return "邮件发送成功"
return "用户取消了发送"
# 中间过程 ...
#用批准和可选编辑的参数恢复
resumed = graph.invoke(
# Command(resume={"action":"同意","subject":"病假"}),
Command(resume={"action":"不同意"}),config=config
)
- 场景四:验证输入 (结合 while True 循环,强制要求人类输入合法的数据)
python
def get_age_node(state: State):
prompt = "你多大了?"
while True:
answer = interrupt(prompt)
if isinstance(answer, int) and answer > 0:
return {"age": answer}
# 验证失败,更新提示语,再次进入循环触发中断
prompt = f"'{answer}' 不是一个有效的年龄。请输入正数。"
# 中间过程 ...
#提供无效数据:节点重新提示
retry = graph.invoke(Command (resume="三+"), config=config)
print(retry["__interrupt__"])
#->[Interrupt(value="三十'不是一个有效的年龄...",...)]
#提供有效数据:循环退出,状态更新
final = graph.invoke(Command(resume=30), config=config)
print(final["age"]) # -> 30
1.4.3 时间旅行
由于 AI 工作流存在非确定性,且复杂任务难以一次性成功。时间旅行允许开发者利用持久化快照,重放过去的执行状态、修改中间变量,从而探索不同的分支路径。

核心应用场景:
-
分析推理过程:查看 AI 是在哪一步"想歪了"。
-
定位和修复错误:精确找到错误节点,修改状态后重新执行,不影响原始记录。
-
探索替代方案:尝试不同的输入或中间状态,比较不同路径的结果。
时间旅行四步法
- 初始执行并生成快照
python
config = {"configurable": {"thread_id": "1"}}
# 正常执行一次完整工作流
result = graph.invoke({"topic": "写一个关于猫的笑话"}, config)
- 查看历史检查点
python
# 获取按时间倒序排列的所有状态快照
states = list(graph.get_state_history(config))
for state in states:
print(f"检查点 ID: {state.config['configurable']['checkpoint_id']}")
print(f"下一步执行节点: {state.next}")
print(f"当前状态: {state.values}")
- 修改状态(可选)
python
# 选择倒数第二个检查点(例如:生成主题之后,写笑话之前)
selected_state = states[1]
# 修改状态数据。注意:这会生成一个新的 checkpoint_id,不影响原历史
new_config = graph.update_state(
selected_state.config,
values={"topic": "写一个关于程序员的冷笑话"} # 修改主题
)
- 从检查点恢复执行
python
# 传入 None 作为输入,因为状态已经存在
# LangGraph 会从 new_config 指定的检查点继续往下执行
new_result = graph.invoke(None, new_config)
print(new_result["joke"]) # 输出修改主题后的新笑话
1.5 持久化总结
LangGraph 的持久化是一套开箱即用的底层基础设施。其核心优势在于:
- 框架原生自动处理:无需手动编写序列化逻辑,节点执行前后自动保存快照。
- 多级存储后端支持 :开发期可使用
InMemorySaver/InMemoryStore,生产环境可无缝切换至PostgresSaver/PostgresStore等关系型或键值数据库。
基于上述底层技术,LangGraph 向上提供了以下核心应用能力与对应的 API 接口:
| 核心能力 | 底层依赖 | 核心 API / 实现方式 | 功能说明 |
|---|---|---|---|
| 状态查询 | Checkpointer |
graph.get_state(config) graph.get_state_history(config) |
获取当前线程的最新状态,或按时间倒序获取完整的历史快照链路(用于排查和调试)。 |
| 时间旅行与重放 | Checkpointer |
graph.invoke(None, config) (指定历史 checkpoint_id) |
从历史的某个特定检查点重新执行,用于探索不同分支或修复错误,不影响原始轨迹。 |
| 状态编辑 | Checkpointer |
graph.update_state(config, values) |
允许在流程中强行覆盖或修改当前状态。修改会严格遵循自定义的 Reducer 规则(如覆盖或追加)。 |
| 人机交互 (HITL) | Checkpointer |
interrupt() Command(resume=...) |
在特定节点暂停工作流,持久化状态后交由外部系统处理,收到指令后再恢复执行。 |
| 短期记忆 | Checkpointer |
基于 thread_id 自动维护 |
记住单次会话内的对话历史与中间结果,实现多轮对话的连贯性。 |
| 长期记忆 | Store |
store.put(...) store.search(...) |
跨越不同的 thread_id(会话),根据 user_id 等命名空间存取用户画像与长期偏好。 |
二、LangGraph 运行控制:上下文、流式与子图
除了工作流模式和持久化,LangGraph 还提供了一系列支撑复杂工程落地的底层 API,包括运行时上下文管理、多模式流式输出以及模块化的子图(Subgraphs)设计。
2.1 运行时上下文 (Runtime Context)
在复杂的 AI 系统中,节点的执行往往依赖许多外部信息(如当前用户的身份、数据库连接、API 密钥等)。如果将这些信息全部塞进全局的 State 中,会导致状态污染和传递混乱。LangGraph 通过引入运行时上下文 (Runtime Context) 来解决这一问题。
2.1.1 上下文的分类
在 LangGraph 中,数据根据"可变性"和"生命周期"可分为三种不同的上下文层级:
| 上下文类型 | 可变性 | 生命周期 | 访问方式 | 典型数据 |
|---|---|---|---|---|
| 静态运行时上下文 | 静态 | 单次运行/线程 | context 参数传入 |
用户 ID、数据库连接、API 密钥 |
| 动态运行时上下文 | 动态 | 单次运行/线程 | 图状态对象 (State) |
当前对话历史、中间计算结果 |
| 动态跨会话上下文 | 动态 | 跨会话持久化 | 存储 (Store) |
用户偏好、长期历史记录 |
2.1.2 配置与访问上下文
使用上下文分为三步:定义数据结构(通常用 dataclass 或 TypedDict)、在创建图时挂载、在节点中通过 Runtime 注入。
python
from dataclasses import dataclass
from langgraph.graph import StateGraph, START, END
from langgraph.runtime import Runtime
from typing_extensions import TypedDict
from langchain_core.messages import AnyMessage
# 1. 定义上下文结构
@dataclass
class AppContext:
user_id: str
language: str = "en"
# 2. 定义状态结构
class AppState(TypedDict):
messages: list[AnyMessage]
user_name: str
# 3. 在节点中注入并访问上下文
def greet_user(state: AppState, runtime: Runtime[AppContext]):
# 访问静态上下文
user_id = runtime.context.user_id
lang = runtime.context.language
# 访问动态状态
user_name = state.get("user_name", "Guest")
greeting = "Hello" if lang == "en" else "你好"
return {"messages": [f"{greeting}, {user_name}! (User ID: {user_id})"]}
# 4. 构建图并挂载 context_schema
builder = StateGraph(AppState, context_schema=AppContext)
builder.add_node("greet", greet_user)
builder.add_edge(START, "greet")
builder.add_edge("greet", END)
graph = builder.compile()
# 5. 运行时传入 context
result = graph.invoke(
{"user_name": "张三"},
context={"user_id": "123", "language": "zh"}
)
2.1.3 在工具 (Tools) 中访问上下文
在 LangChain/LangGraph 中,工具(Tool)可以通过 ToolRuntime 参数访问图状态、上下文和存储。
python
from langchain.tools import tool, ToolRuntime
@tool
def get_user_info(runtime: ToolRuntime) -> str:
"""获取当前用户信息的工具"""
user_id = runtime.context.user_id # 访问静态上下文
user_state = runtime.state["user_name"] # 访问动态状态
return f"User {user_id}, state: {user_state}"
带上下文的完整 Agent 示例:
假设我们需要构建一个搜索工具,该工具需要读取用户的 user_id 来记录调用日志。
python
from dataclasses import dataclass
from langchain.chat_models import init_chat_model
from langchain.tools import tool, ToolRuntime
from langchain_core.messages import SystemMessage, HumanMessage, AnyMessage
from langgraph.prebuilt import ToolNode, tools_condition
from langgraph.graph import StateGraph, START, END
from typing_extensions import TypedDict, Annotated
import operator
class MessagesState(TypedDict):
messages: Annotated[list[AnyMessage], operator.add]
user_name: str
@dataclass
class Context:
user_id: str
@tool
def search(runtime: ToolRuntime[Context]) -> str:
"""调用搜索工具"""
user_id = runtime.context.user_id
user_name = runtime.state.get("user_name", "未知")
print(f"日志记录: user_id: {user_id}, user_name: {user_name} 调用查询工具")
return "查询天气: 晴天, 15-20度"
# 绑定工具
model_with_tools = init_chat_model("gpt-4o-mini").bind_tools([search])
def llm_call(state: dict):
return {
"messages": [
model_with_tools.invoke(
[SystemMessage(content="你是一个支持工具搜索的助手")] + state["messages"]
)
]
}
# 构建图
builder = StateGraph(MessagesState, context_schema=Context)
builder.add_node("llm_call", llm_call)
builder.add_node("tool_node", ToolNode([search]))
builder.add_edge(START, "llm_call")
builder.add_conditional_edges(
"llm_call", tools_condition, {"tools": "tool_node", "__end__": END}
)
builder.add_edge("tool_node", "llm_call")
graph = builder.compile()
# 运行
for chunk in graph.stream(
{"messages": [HumanMessage(content="今天西安的天气如何?")], "user_name": "小明"},
context={"user_id": "123"}
):
pass # 处理流式输出
2.2 流式传输 (Streaming)
在 LLM 应用中,流式传输能显著提升用户体验。如果说 LangChain 的流式传输主要聚焦于「LLM 生成的文本内容(Token)」,那么 LangGraph 的流式传输则实现了「升维」------它不仅能输出文本,还能将整个图运行的实时状态、节点更新进度以及自定义数据反馈给前端。
这种机制对于构建复杂的 Agent 界面至关重要:前端不再只能傻等最终结果,而是能实时感知到"AI 现在正在调用哪个工具"、"当前执行到了哪一个节点",从而渲染出更高级的交互监控面板。LangGraph 为此提供了多种不同的流模式。
2.2.1 五种流模式 (Stream Modes)
在使用 stream 或 astream 时,可以通过传入列表组合多种模式,常用的核心模式如下:
模式 (stream_mode) |
说明 | 适用场景 |
|---|---|---|
values |
流式输出完整状态 | 需要知道每一步执行后的完整 State |
updates |
流式输出状态变化 | 只关注每个节点更新了哪些字段 |
messages |
流式输出 LLM 的 Token | 实时呈现打字机效果 |
custom |
流式输出自定义数据 | 自定义进度条、日志上报、中间状态 |
debug |
输出所有调试信息 | 开发排查阶段 |
基础用法对比 (values vs updates):
python
from langgraph.graph import StateGraph, START
class State(dict):
topic: str
joke: str
def refine_topic(state: State):
return {"topic": state["topic"] + "和猫"}
def generate_joke(state: State):
return {"joke": f"这是一个关于{state['topic']}的笑话"}
graph = (
StateGraph(State)
.add_node(refine_topic)
.add_node(generate_joke)
.add_edge(START, "refine_topic")
.add_edge("refine_topic", "generate_joke")
.compile()
)
for chunk in graph.stream(
{"topic": "XXX"},
stream_mode="XXX"
):
print(chunk)
stream_mode="updates",运行结果:
text
# {'refine_topic': {'topic': '冰激凌和猫'}}
# {'generate_joke': {'joke': '这是一个关于冰激凌和猫的笑话'}}
stream_mode="values",运行结果:
text
# {'topic': '冰激凌'}
# {'topic': '冰激凌和猫'}
# {'topic': '冰激凌和猫', 'joke': '这是一个关于冰激凌和猫的笑话'}
2.2.2 流式传输自定义数据 (Custom Stream)
当需要将节点内部的计算进度(如搜索工具的循环次数)反馈给前端时,可以使用 get_stream_writer() 发送自定义数据。调⽤.stream() 或.astream() 时设置 stream_mode="custom" 以获取流中的自定义数据。还可以组合多种模式(如 ["updates","custom"]),但⾄少必须有⼀个是 "custom" 。
python
from langgraph.config import get_stream_writer
@tool
def search(runtime: ToolRuntime[Context]) -> str:
writer = get_stream_writer()
# 发送自定义信号(如:开始)
writer({"type": "search_tool", "status": "start", "user_id": runtime.context.user_id})
# 模拟处理
import time
time.sleep(2)
# 发送自定义信号(如:结束)
writer({"type": "search_tool", "status": "end", "result": "晴天"})
return "查询天气: 晴天"
# 调用时指定 stream_mode="custom"
for chunk in graph.stream(
{"messages": [HumanMessage(content="今天杭州的天气如何?")]},
stream_mode=["custom"]
):
print(chunk)
运行输出
text
('custom', {'type': 'llm_call', 'status':'start', 'message':'开始调用LLM',content':'今天杭州的天气如何?'})
('custom', {'type': 'llm_call', 'status': 'end', 'message': '调⽤LLM完成'})
('custom', {'type': 'search_tool', 'status': 'start', 'user_id': '123', 'user_name': '⼩明'})
...
2.2.3 流式传输 LLM Tokens (messages 模式)
messages 模式可以直接从图的任何部分(包括节点、工具等)逐 Token 流式输出 LLM 生成的内容。 输出格式为(message_chunk, metadata) 元组。
基础用法 :直接打印 token_chunk.content。
按 Tags 过滤 :如果同一次运行有多个模型(例如同时生成笑话和诗歌),可以通过给模型添加 tags 来过滤流。
python
# 初始化带标签的模型
joke_model = ChatOpenAI(model="gpt-4o-mini", model_kwargs={"tags": ["joke"]})
poem_model = ChatOpenAI(model="gpt-4o-mini", model_kwargs={"tags": ["poem"]})
# ... 节点内部分别调用这两个模型 ...
# 流式输出并过滤
for token_chunk, metadata in graph.stream({"topic": "猫"}, stream_mode="messages"):
tags = metadata.get("tags", [])
if "joke" in tags:
print(token_chunk.content, end="", flush=True) # 只输出笑话相关的 Tokens
按节点名称过滤:
python
for token_chunk, metadata in graph.stream(..., stream_mode="messages"):
node_name = metadata.get("langgraph_node", "")
if node_name == "summarize":
print(f"📄 [摘要] {token_chunk.content}", end="")
2.3 子图 (Subgraphs)
子图(Subgraphs)是 LangGraph 实现模块化开发的核心机制。它允许你将一个完整的图作为另一个图的节点使用。这不仅能提高代码复用率,还能让不同团队独立开发复杂流程。
2.3.1 使用子图的方式一:节点内调用(不同状态模式)
这种方式是在主图的一个节点函数内部,手动调用 subgraph.invoke()。特点:主图和子图的状态结构可以完全不同。
python
# 1. 定义子图(拥有独立的 SubState)
class SubState(TypedDict):
sub_1: str
sub_2: str
def sub_node_1(state: SubState): return {"sub_1": "sub_1"}
def sub_node_2(state: SubState): return {"sub_2": state["sub_1"] + "_processed"}
sub_builder = StateGraph(SubState)
sub_builder.add_node(sub_node_1)
sub_builder.add_node(sub_node_2)
sub_builder.add_edge(START, "sub_node_1")
sub_builder.add_edge("sub_node_1", "sub_node_2")
subgraph = sub_builder.compile()
# 2. 在主图节点中调用
class ParentState(TypedDict):
parent: str
def node_2(state: ParentState):
# 将主图状态转换为子图状态传入
response = subgraph.invoke({"sub_1": state["parent"]})
# 将子图结果传回主图
return {"parent": response["sub_2"]}
builder = StateGraph(ParentState)
builder.add_node("node_2", node_2)
# ...
False
for chunk in graph.stream({"parent": "parent"},
print(chunk)
注意: 要在流式输出中包含⼦图的输出,可以在⽗图的 .stream() ⽅法中设置 subgraphs=True,默认是 False。
2.3.2 使用子图的方式二:作为节点添加(共享状态模式)
直接将编译好的子图通过 add_node 作为主图的一个节点。特点:子图和主图必须共享部分状态键。
python
class SubState(TypedDict):
parent: str # 与主图共享的状态
sub: str # 子图私有状态
# ... 定义子图内部逻辑并 compile() ...
builder = StateGraph(ParentState)
# 直接将子图作为主图的一个节点
builder.add_node("subgraph_node", subgraph)
2.3.3 子图与持久化 (Checkpoint)
如果包含子图,只需在主图编译时传入 checkpointer,LangGraph 会自动将检查点能力传播到所有的子图中,无需额外配置。
python
checkpointer = InMemorySaver()
graph = builder.compile(checkpointer=checkpointer)
2.3.4 子图与中断(Interrupt)的交互陷阱
在子图中使用 interrupt() 是极其容易踩坑的地方。由于节点恢复时会从头重新执行,子图的调用方式不同,会导致不同的重复执行行为。
场景一:子图作为节点被直接添加
当子图发生中断后恢复时,子图中触发中断的节点会被重新执行一次。
text
# 打印结果(符合预期):
sub_node_1
sub_node_2 # 第一次执行
sub_node_2 # 恢复后,重新执行中断的节点
{'foo': 'bar'}
场景二:节点内部通过 invoke 调用子图
这种情况下,父图将从调用子图并触发中断的节点的开头恢复执行,子图也将从调用中断的节点的开头恢复**。
text
# 打印结果(注意重复执行):
node_1
sub_node_1
sub_node_2 # 子图第一次中断
node_1 # ❗ 主图节点重新执行
sub_node_2 # ❗ 子图节点重新执行
{'foo': 'bar'}
⚠️ 架构设计建议 :
由于中断恢复会导致执行路径的重复,务必确保在触发
interrupt()之前的代码是幂等的 (例如:使用upsert而不是insert,或者将非幂等操作放在interrupt()之后)。这也是前面章节中反复强调的"中断黄金法则"。