【LangGraph】类型驱动配置（Annotated 类型注解以及与之绑定的字段行为控制机制）

LangGraph声明式编程与类型驱动配置总结

最新推荐文章于 2025-10-02 10:21:48 发布

原创最新推荐文章于 2025-10-02 10:21:48 发布 · 1.3k 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#LangGraph #Annotated #reducer #类型

LangGraph 专栏收录该内容

67 篇文章

订阅专栏

本文总结了 LangGraph 中使用 声明式编程 + 类型驱动配置 的编程方式，特别是基于 Python 的 Annotated 类型注解以及与之绑定的字段行为控制机制（reducer 函数或其他策略）。以下对 LangGraph 中这类编程方式的系统性总结，涵盖常见和可能的用法。

LangGraph 中声明式编程 + 类型驱动配置的编程方式总结

LangGraph 利用 Python 的 Annotated 类型注解，结合特定的 reducer 函数或内置机制，将字段的行为（更新、合并、计算等）绑定到类型定义上。这种方式通过声明式配置减少样板代码，支持动态工作流和复杂状态管理。以下是 LangGraph 中常见的此类编程方式，逐一列举：

1. 消息字段的合并（`add_messages`）

用法: Annotated[Sequence[AnyMessage], add_messages]
作用: 用于处理对话历史或消息序列，自动按消息 ID 替换已有消息或追加新消息。
模块: langgraph.graph
适用场景: 对话系统、聊天机器人、Agent 交互历史。

示例:

from typing import Sequence
from typing_extensions import Annotated
from langgraph.graph import add_messages
from langchain_core.messages import AnyMessage

class State:
    messages: Annotated[Sequence[AnyMessage], add_messages]

说明: add_messages 是 LangGraph 专为消息设计的 reducer，处理复杂消息合并逻辑（如去重、更新）。

2. 数值字段的加法（`operator.add`）

用法: Annotated[int | float, operator.add]
作用: 对数值型字段执行加法操作，累加新值到现有值。
模块: operator（Python 标准库）
适用场景: 计数器、累加分数、统计指标。

示例:

from typing_extensions import Annotated
from operator import add

class State:
    count: Annotated[int, add] = 0

说明: 当状态更新时，新值会通过 operator.add 与旧值相加，适合简单数值累加。

3. 列表字段的扩展（`operator.extend`）

用法: Annotated[List[T], operator.extend]
作用: 将新列表的元素追加到现有列表（类似 list.extend()）。
模块: operator（Python 标准库）
适用场景: 收集搜索结果、批量添加数据、动态列表扩展。

示例:

from typing import List
from typing_extensions import Annotated
from operator import extend
from dataclasses import field

class State:
    items: Annotated[List[str], extend] = field(default_factory=list)

说明: operator.extend 直接调用列表的 extend 方法，适合批量追加元素。

4. 字典字段的合并（`update_dict`）

用法: Annotated[Dict, update_dict]
作用: 合并两个字典，后者的键值对覆盖前者的键值对（类似 dict.update()）。
模块: langgraph.utils
适用场景: 配置管理、元数据更新、动态键值存储。

示例:

from typing import Dict
from typing_extensions import Annotated
from langgraph.utils import update_dict
from dataclasses import field

class State:
    metadata: Annotated[Dict, update_dict] = field(default_factory=dict)

说明: update_dict 提供了一种声明式的字典合并方式，避免手动编写合并逻辑。

5. 字典键值对的更新（`operator.setitem`）

用法: Annotated[Dict, operator.setitem]
作用: 更新字典中的特定键值对，仅针对指定键进行替换。
模块: operator（Python 标准库）
适用场景: 精确更新字典中的某个键值，而不影响其他键。

示例:

from typing import Dict
from typing_extensions import Annotated
from operator import setitem
from dataclasses import field

class State:
    config: Annotated[Dict, setitem] = field(default_factory=dict)

说明: operator.setitem 更适合单键更新场景，相比 update_dict 更精细。

6. 只读管理字段（`IsLastStep`）

用法: IsLastStep
作用: 由 LangGraph 运行时自动管理，用于标记是否为图执行的最后一步。
模块: langgraph.graph
适用场景: 控制工作流终止条件、状态检查。

示例:

from langgraph.graph import IsLastStep
from dataclasses import field

class State:
    is_last_step: IsLastStep = field(default=False)

说明: IsLastStep 是一个特殊类型，LangGraph 自动设置其值，开发者无需手动干预。

7. 自定义 Reducer 函数

用法: Annotated[T, custom_reducer]
作用: 开发者可以定义自定义的 reducer 函数，指定字段的更新逻辑。
模块: 用户自定义
适用场景: 复杂状态更新逻辑，如条件合并、过滤、转换等。

示例:

from typing import List
from typing_extensions import Annotated
from dataclasses import field

def custom_reducer(current: List[str], new: List[str]) -> List[str]:
    return list(set(current + new))  # 去重合并

class State:
    unique_items: Annotated[List[str], custom_reducer] = field(default_factory=list)

说明: LangGraph 支持用户定义 reducer 函数，灵活性高，适合特殊场景。

8. 集合字段的并集（`operator.or_`）

用法: Annotated[Set[T], operator.or_]
作用: 对集合型字段执行并集操作，合并两个集合并去重。
模块: operator（Python 标准库）
适用场景: 去重合并数据、标签集合、唯一标识集合。

示例:

from typing import Set
from typing_extensions import Annotated
from operator import or_
from dataclasses import field

class State:
    tags: Annotated[Set[str], or_] = field(default_factory=set)

说明: operator.or_ 使用集合的 | 操作符，自动去重，适合集合操作。

9. 布尔字段的逻辑运算（`operator.or_` 或 `operator.and_`）

用法: Annotated[bool, operator.or_] 或 Annotated[bool, operator.and_]
作用: 对布尔字段执行逻辑或（or）或逻辑与（and）操作。
模块: operator（Python 标准库）
适用场景: 状态标志、条件检查。

示例:

from typing_extensions import Annotated
from operator import or_
from dataclasses import field

class State:
    has_error: Annotated[bool, or_] = field(default=False)

说明: 适合需要累积布尔状态的场景，如错误标志或完成状态。

10. 自定义合并策略（`Annotated` + 闭包或类）

用法: Annotated[T, CustomReducerClass]
作用: 使用类或闭包定义复杂的合并逻辑，封装状态更新行为。
模块: 用户自定义
适用场景: 高度定制化的状态更新，如多字段联动、复杂条件逻辑。

示例:

from typing import List
from typing_extensions import Annotated
from dataclasses import field

class ListMerger:
    def __init__(self, max_length: int):
        self.max_length = max_length

    def __call__(self, current: List[str], new: List[str]) -> List[str]:
        result = current + new
        return result[-self.max_length:]  # 保留最后 max_length 个元素

class State:
    recent_items: Annotated[List[str], ListMerger(max_length=5)] = field(default_factory=list)