LangGraph StateGraph 实战:节点、边与状态合并机制
本文深入解析 LangGraph 的核心组件 StateGraph。通过从简单的计数器到带记忆的多轮对话 Agent 案例,讲解图、节点、边的基本概念,重点剖析 Reducer 在状态合并中的作用,特别是 add_messages 如何实现消息追加而非覆盖。同时对比 StateGraph 与 Functional AP
前言
在之前的文章中,我们梳理了 AI Agent 开发的四层架构:从底层的 langchain-core 积木,到运行时 LangGraph,再到上层的 create_agent 薄壳和 Deep Agents SDK 套件。很多开发者在使用 create_deep_agent 时觉得方便,但一旦遇到复杂逻辑或需要定制状态行为时,往往无从下手。
这一篇我们直接进入运行时层(Runtime),亲手拆解 LangGraph 最核心的类——StateGraph。不搞虚的,直接看代码。我们要搞清楚三个核心概念:图(Graph)、节点(Node)、边(Edge),以及一个容易被忽视但至关重要的机制:状态是如何被「合并」的(Reducer)。
理解了这些,你才算真正掌握了 Agent 的流水线控制能力。
一、什么是 StateGraph:图、节点、边、状态 Schema
先建立一个直观的心智模型。如果把 Agent 比作一个工厂,langchain-core 提供了零件(如消息对象、工具接口、模型调用),而 StateGraph 就是那条自动化流水线。
在这条流水线上,有四个基本要素:
- 图(Graph):整个工作流程的定义。它规定了先做什么、后做什么,以及在不同条件下走向哪里。
- 节点(Node):流水线上的工位。每个节点是一个函数,它接收当前的状态,执行具体任务(比如调用大模型、查询数据库),然后返回它想要修改的状态部分。节点不关心全局状态,只负责自己那一亩三分地。
- 边(Edge):连接工位的传送带。普通边是固定的路径(A 做完给 B);条件边则根据运行时的结果决定下一步去向(比如工具调用后,根据是否有工具结果决定是继续调用工具还是结束)。
- 状态 Schema(State Schema):流水线上流动的「工件」的标准格式。通常用 Python 的
TypedDict定义,明确状态里有哪些字段,每个字段是什么类型。
StateGraph 依赖底层的积木,同时又被上层的 create_agent 所封装。它是承上启下的关键。
二、先跑一个最简状态图:键值状态
新手最容易犯的错误是一上来就处理复杂的消息列表。我们先从一个最简单的例子开始:一个只做加法的计数器。
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
class CounterState(TypedDict):
"""状态 Schema:用 TypedDict 声明状态长什么样。"""
count: int
def increment(state: CounterState) -> dict:
"""节点函数:入参是当前状态,返回「我要改动的键」。"""
return {"count": state["count"] + 1}
# 1. 初始化图,传入状态 Schema
graph = StateGraph(CounterState)
# 2. 添加节点
graph.add_node("increment", increment)
# 3. 添加边:起点 -> 节点 -> 终点
graph.add_edge(START, "increment")
group.add_edge("increment", END)
# 4. 编译成可执行的应用
app = graph.compile()
# 5. 执行
print(app.invoke({"count": 0}))
# 输出: {'count': 1}这段代码虽然简单,但揭示了 LangGraph 的几个核心机制:
- Schema 驱动:
StateGraph(CounterState)告诉图,状态里有一个叫count的整数。如果节点返回了 Schema 里没有的键,或者类型不对,编译或运行时可能会报错(取决于配置)。 - 部分更新:注意
increment函数。它没有返回整个状态对象,只返回了{"count": ...}。LangGraph 的运行时会自动把这个返回值合并到当前状态中。这意味着,如果状态里有 10 个字段,某个节点只改了其中 1 个,它只需要返回这 1 个字段即可,其他字段保持不变。 - 虚拟节点:
START和END是 LangGraph 内置的特殊节点,标记流程的开始和结束。
三、Reducer:状态到底怎么合并
在上面的计数器例子中,状态的合并逻辑很简单:新值直接覆盖旧值。这是 LangGraph 的默认行为。
但是,在真实的 Agent 场景中,「覆盖」往往不是我们想要的。最典型的场景就是聊天历史。
假设状态里有一个 messages 列表,存储对话历史。如果模型节点每次返回都使用默认覆盖,那么新的一轮对话会直接把之前的所有历史记录删掉,只保留最新的一条消息。这显然不是我们要的「记忆」。
这时候就需要 Reducer。Reducer 是一个函数,定义了当同一个键被多次写入时,如何将新值与旧值合并。
默认覆盖 vs 追加
先看默认覆盖的效果:
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
class TextState(TypedDict):
text: str
def write_a(state: TextState) -> dict:
return {"text": "A 节点写的"}
def write_b(state: TextState) -> dict:
return {"text": "B 节点写的"}
g2 = StateGraph(TextState)
g2.add_node("a", write_a)
g2.add_node("b", write_b)
g2.add_edge(START, "a")
g2.add_edge("a", "b")
g2.add_edge("b", END)
app2 = g2.compile()
print(app2.invoke({"text": ""}))
# 输出: {'text': 'B 节点写的'}可以看到,B 节点的结果覆盖了 A 节点的结果。
使用 add_messages 实现消息追加
对于消息列表,LangGraph 提供了一个内置的 Reducer:add_messages。它会智能地将新消息追加到旧消息列表后面,并且支持基于消息 ID 的去重和替换(这对工具调用的结果回填非常重要)。
from typing import Annotated, TypedDict
from langchain_core.messages import AIMessage, HumanMessage
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
class ChatState(TypedDict):
# 关键:使用 Annotated 指定 reducer
messages: Annotated[list, add_messages]
def append_ai(state: ChatState) -> dict:
return {"messages": [AIMessage(content="这是 AI 追加的一条")]}
g3 = StateGraph(ChatState)
g3.add_node("append_ai", append_ai)
g3.add_edge(START, "append_ai")
g3.add_edge("append_ai", END)
app3 = g3.compile()
result = app3.invoke({"messages": [HumanMessage(content="用户的第一句")]})
print([(type(m).__name__, m.content) for m in result["messages"]])
# 输出: [('HumanMessage', '用户的第一句'), ('AIMessage', '这是 AI 追加的一条')]注意 Annotated[list, add_messages] 的写法。这是 Python 的类型注解语法,第一个参数是类型,第二个参数是元数据(这里传入 Reducer 函数)。
add_messages 比简单的 list.append 更强大:
- 追加:默认将新消息加到列表末尾。
- 去重/替换:如果新消息的 ID 与旧消息相同,它会替换旧消息。这在工具调用场景中非常有用:当 Agent 发出工具调用请求时,生成一条 ToolMessage;当工具执行完毕返回结果时,再传入一条同 ID 的 ToolMessage,此时就会替换掉之前的占位符或更新状态,而不是产生两条重复消息。
四、案例:带记忆的多轮对话 Agent
结合前面的知识,我们写一个真正的多轮对话 Agent。这个 Agent 没有工具调用,只有模型交互,重点展示状态如何在多轮对话中累积。
我们需要安装依赖:pip install langgraph langchain-deepseek,并配置好 DEEPSEEK_API_KEY。
import sys
from typing import Annotated, TypedDict
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_deepseek import ChatDeepSeek
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages
# 解决 Windows 控制台编码问题
sys.stdout.reconfigure(encoding="utf-8")
class ChatState(TypedDict):
messages: Annotated[list, add_messages]
model = ChatDeepSeek(model="deepseek-chat")
def call_model(state: ChatState) -> dict:
"""模型节点:读取当前所有消息,生成回复。"""
response = model.invoke(state["messages"])
return {"messages": [response]}
graph = StateGraph(ChatState)
graph.add_node("model", call_model)
graph.add_edge(START, "model")
group.add_edge("model", END)
app = graph.compile()
# 模拟多轮对话
messages = [SystemMessage(content="你是一个简洁的助手,回答尽量简短,不超过两句话。")]
questions = [
"你好,我叫小明,帮我记一下。",
"我刚才说我叫什么名字?"
]
for question in questions:
messages.append(HumanMessage(content=question))
# 每次 invoke 传入当前累积的消息列表
result = app.invoke({"messages": messages})
# 更新本地消息列表,以便下一轮使用
messages = result["messages"]
print(f"你:{question}")
print(f"AI:{result['messages'][-1].content}")
print("---")运行结果大致如下:
你:你好,我叫小明,帮我记一下。
AI:你好,小明!很高兴认识你。已记住你的名字,有什么需要帮忙的吗?
---
你:我刚才说我叫什么名字?
AI:你叫小明。有什么我可以帮你的吗?
---关键点在于:
- 状态累积:
add_messages确保了每一轮 AI 的回复都被追加到messages列表中,而不是覆盖。 - 上下文传递:在循环中,我们将上一轮输出的完整
messages作为下一轮的输入。这样,模型在回答第二个问题时,能看到第一个问题的历史记录,从而正确回答出「小明」。
注意,这里的记忆是「进程内」的。如果程序重启,状态就丢失了。要实现持久化记忆,需要引入 Checkpointer,这将在后续文章中讨论。
五、工程化要点:Schema、Reducer、导入来源、两条写法
在实际工程中,有几个坑需要避开。
1. 状态 Schema 设计
务必使用 TypedDict 而不是裸 dict。TypedDict 能提供 IDE 的智能提示和静态类型检查。当状态字段变多时,这能极大减少拼写错误带来的调试痛苦。
2. Reducer 的选择
- 默认覆盖:适用于大多数标量字段(如
step_count,status)。 - add_messages:专用于消息列表。不要自己写
list.append,因为add_messages处理了 ID 去重和线程安全等细节。 - 自定义 Reducer:如果有特殊的合并逻辑(比如取最大值、合并字典、去重列表),可以编写
(old, new) -> merged函数,并通过Annotated挂载。
特别注意:如果图中存在并行分支(Fan-in),多个节点同时写入同一个键,且该键没有定义 Reducer,LangGraph 会抛出 InvalidUpdateError。因为运行时不知道该如何合并这两个冲突的值。因此,任何可能被并行写入的键,都必须显式指定 Reducer。
3. 导入来源
LangGraph 的模块结构经过了几次调整,请确保使用最新的导入路径:
StateGraph,START,END来自langgraph.graph。add_messages来自langgraph.graph.message。- 不要再使用已弃用的
MessageGraph。
4. StateGraph vs Functional API
LangGraph 支持两种编程风格:
- StateGraph(命令式):显式定义节点和边。优点是结构清晰,易于可视化和调试,适合复杂的工作流。本专栏主要采用这种方式,因为它更贴近底层实现。
- Functional API(声明式):使用
@entrypoint和@task装饰器。代码看起来像普通的 Python 函数调用,由框架自动构建图。适合线性、简单的流程。
两者底层运行时相同。对于初学者,建议先掌握 StateGraph,理解图的本质,再根据项目复杂度选择是否使用 Functional API。
附:Deep Agents 等价实现
如果你使用的是 create_agent 或 create_deep_agent,它们内部其实就是构建了类似的 StateGraph。例如:
from langchain.agents import create_agent
agent = create_agent(model=model, tools=[], system_prompt="你是简洁的助手")
result = agent.invoke({"messages": [{"role": "user", "content": "你好"}]})这行代码背后,框架自动帮你处理了状态 Schema、add_messages Reducer 以及模型节点的编排。当你需要更细粒度的控制(比如自定义状态字段、插入预处理节点、复杂的路由逻辑)时,就需要像本文这样,手动构建 StateGraph。
结语
StateGraph 是 LangGraph 的灵魂。理解了节点如何读写状态、边如何控制流转、Reducer 如何合并数据,你就具备了构建复杂 Agent 工作流的基础。下一篇,我们将探讨如何利用条件边实现工具调用循环,让 Agent 真正具备「思考」和「行动」的能力。