AI Agent / 系统课时
管理消息状态与归并规则
管理消息状态与归并规则
智能体会不断向状态写入用户消息、模型回复和工具结果。如果每次更新都直接替换 messages,历史上下文很容易丢失。本节用 LangGraph 的 reducer 与 add_messages 建立可持续追加、又能按消息 ID 修正内容的消息状态。
学习目标
- 理解普通状态更新与 reducer 归并的区别
- 使用
add_messages保存连续产生的消息 - 理解相同消息 ID 的替换语义及并行更新边界
reducer 决定状态如何接收新值
LangGraph 的节点读取共享状态,并返回需要更新的部分字段。对于没有 reducer 的字段,新值用于更新该状态键;当一个字段需要累计历史、合并集合或接收同一执行步骤中的多个更新时,就应明确声明归并规则。
reducer 可以理解为一个二元函数:它接收状态中的旧值和本次产生的新值,再返回合并后的值。因此节点不需要读取整个列表后手工拼接再写回,而只需返回自己新产生的部分数据。
消息状态尤其适合这种模型。用户消息、模型消息和工具消息都在不断产生,节点通常只负责新增一条或几条消息,不应该负责重新构造全部历史。

用 add_messages 管理消息历史
add_messages 是 LangGraph 针对消息列表提供的归并函数。把它通过 Annotated 绑定到 messages 字段后,每个节点只返回新消息即可。不同 ID 的消息会保留下来;新消息与已有消息 ID 相同时,则用新版本替换对应消息。
下面构建一个只有回复节点的最小图。输入中的用户消息和节点新产生的 AI 消息都会进入同一个 messages 状态。
from typing import Annotated
from typing_extensions import TypedDict
from langchain_core.messages import AIMessage, AnyMessage, HumanMessage
from langgraph.graph import END, START, StateGraph, add_messages
class ChatState(TypedDict):
# 节点只返回新增消息,由 reducer 与已有历史归并。
messages: Annotated[list[AnyMessage], add_messages]
def reply(state: ChatState) -> dict:
last_message = state["messages"][-1]
return {
"messages": [
AIMessage(
content=f"收到:{last_message.content}",
id="assistant-1",
)
]
}
builder = StateGraph(ChatState)
builder.add_node("reply", reply)
builder.add_edge(START, "reply")
builder.add_edge("reply", END)
graph = builder.compile()
result = graph.invoke({
"messages": [HumanMessage(content="你好", id="user-1")]
})
print([(message.id, message.content) for message in result["messages"]])
# 相同 ID 表示修正已有消息,而不是再追加一条重复记录。
corrected = add_messages(
result["messages"],
[AIMessage(content="收到:你好!", id="assistant-1")],
)
print([(message.id, message.content) for message in corrected])预期输出
[('user-1', '你好'), ('assistant-1', '收到:你好')]
[('user-1', '你好'), ('assistant-1', '收到:你好!')]这里的关键不是列表追加本身,而是节点只声明自己的增量。图执行器负责把增量交给 reducer,状态合并逻辑因此集中在状态定义中,而不会散落到每个节点里。
消息 ID 决定追加还是修正
如果新消息拥有新的 ID,add_messages 会让它与已有消息共存,适合用户继续提问、模型继续回答的常规对话。若新消息使用已经存在的 ID,则原位置对应的消息会被新内容更新,这适合纠正、重放或替换某条已有消息。
因此,消息 ID 不只是方便打印的字段。需要支持恢复、人工修正或工具调用结果更新时,应为消息保留稳定身份;如果每次都生成完全新的 ID,同一逻辑消息就只会不断追加,而不会被修正。
什么时候需要自定义 reducer
add_messages 适用于 LangChain 消息对象。如果状态保存的是计数、集合、事件记录或其他领域对象,可以为对应字段提供自己的 reducer,例如求和、去重或按主键合并。
是否需要 reducer 的判断标准很简单:字段表达的是单个当前值时,覆盖通常足够;字段表达的是跨节点持续积累的数据时,应把合并规则显式放进状态定义。对智能体的 messages 而言,使用专门的消息归并规则可以让节点保持局部、状态保持完整,也为后续持久化和恢复留下稳定基础。