LangGraph 中的 TypedDict, Annotated, Sequence

python 复制代码

from typing import TypedDict, Annotated, Sequence

这三个是 Python typing 模块中用于类型提示 的核心工具，尤其在 LangGraph 中定义状态时非常常用 ------ TypedDict 定义有什么 ，Sequence 说明是什么类型 ，Annotated 规定怎么处理。三者结合就能构建出结构清晰、行为明确的 LangGraph 状态。

TypedDict：定义字典的结构

TypedDict 用于定义一个字典应该包含哪些键 ，以及每个键对应的值是什么类型。

核心作用：让 IDE 能提供自动补全，并在你错误地使用键名或赋值错误类型时给出提示。

python 复制代码

from typing import TypedDict

# 定义状态结构
class State(TypedDict):
    messages: list          # 键 'messages' 的值应为 list 类型
    user_name: str          # 键 'user_name' 的值应为 str 类型
    total_score: int        # 键 'total_score' 的值应为 int 类型

# 使用时，IDE 会提示你 'messages', 'user_name', 'total_score' 这些键
state: State = {
    "messages": ["你好", "你好！"],
    "user_name": "Alice",
    "total_score": 42
}
# state["wrong_key"]  # 如果使用未定义的键，类型检查工具会报错

Annotated：给类型附加元数据

Annotated 允许在类型提示的基础上附加额外的信息 。它在 LangGraph 中最重要的用途是为状态字段指定 reducer 函数。

核心作用 ：告诉 LangGraph 当多个节点返回相同状态字段时，应该如何合并这些值。

python 复制代码

from typing import Annotated, TypedDict
from operator import add
from langgraph.graph.message import add_messages

class State(TypedDict):
    # 当多个节点向 'messages' 字段添加消息时，使用 'add_messages' 这个 reducer 来合并
    messages: Annotated[list, add_messages]
    
    # 当多个节点向 'total' 字段返回值时，使用 'add' 函数（即 operator.add）来累加
    total: Annotated[int, add]
    
    # 普通字段，没有 reducer。如果多个节点都返回该字段，后执行的会覆盖先执行的
    user_name: str

Sequence：表示只读的序列

Sequence 是一个抽象基类 （不是一个具体的类），用于表示一个元素有序的、可遍历的、只读的集合。

核心作用 ：让函数或状态能接受任何类型的序列 （如 list、tuple、range 等），增强了代码的灵活性，同时表明不会修改这个序列。

python 复制代码

from typing import Sequence, TypedDict
from langchain_core.messages import BaseMessage

class State(TypedDict):
    # messages 可以是任何序列（list, tuple 等），并且应该包含 BaseMessage 对象
    # 这比直接写 list 更灵活，也表明了你不打算修改这个序列
    messages: Sequence[BaseMessage]
    
# 也可以用于函数参数
def process_items(items: Sequence[int]) -> int:
    return sum(items)  # 这个函数可以接受 list, tuple, range 等

# 均有效
print(process_items([1, 2, 3]))   # list
print(process_items((1, 2, 3)))   # tuple
print(process_items(range(5)))    # range

对比

组合用法：

python 复制代码

from typing import TypedDict, Annotated, Sequence
from langgraph.graph.message import add_messages
from langchain_core.messages import BaseMessage

# 这就是 LangGraph 项目中最标准的状态定义模板
class State(TypedDict):
    # Sequence[BaseMessage] 表示这是一个只读的消息序列，更准确
    # Annotated[..., add_messages] 告诉 LangGraph 用 add_messages 规则来合并消息
    messages: Annotated[Sequence[BaseMessage], add_messages]
    
    # 其他普通字段
    question: str
    context: str
    answer: str