Annotated 驱动 LangGraph 状态更新

Annotated

语法：Annotated[type, metadata]

from typing import Annotated

# 基本形式：Annotated[实际类型, 元数据]
Annotated[list, add_messages]

• list: 状态字段的实际类型，表示这是一个列表
• add_messages: Reducer 函数（归约器），定义了状态更新策略

在 LangGraph 中，第二个参数必须是可调用对象（函数），负责处理如何将节点的输出合并到现有状态中。

不使用 Annotated 时的典型陷阱

class BadState(TypedDict):
    messages: list  # 没有 Annotated

# 图定义
builder = StateGraph(BadState)
builder.add_node("agent", agent_node)  # 返回 {"messages": [ai_message]}

# 执行后你会发现：
# 第一轮：messages = [HumanMessage, AIMessage]  
# 第二轮：messages = [AIMessage_of_round2]  # 历史全丢了！

使用 Annotated 解决：

from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]  # 历史被保留并追加