[智能体-339]：LangGraph 节点返回值 完整规则总结
一、基础通用规则
1. 返回值类型要求
节点函数必须返回一个字典（dict），不允许返回列表、字符串、数字、None等其他类型。
- 合法：
{"key": value} - 非法：
[]、"hello"、123、None
2. 核心原则：只返回增量更新，不返回完整 State
节点无需把整个全局状态原样返回，仅写出当前节点需要修改 / 新增的字段：
- 未在返回字典中出现的字段：保持原有状态值，不会被改动；
- 出现的字段：按照该字段预设的更新规则（归约函数）合并新旧值。
例：State 有
loop_times、log、search_result三个字段 节点只改log→仅返回{"log": ["xxx"]}，另外两个字段维持原值。
二、字段更新规则（由Annotated + 归约函数决定）
这是 LangGraph最核心的规则，分两大类，由状态TypedDict定义时的注解控制。
1. 默认规则：直接覆盖（Overwrite）
无Annotated注解的普通字段，默认更新逻辑：新值直接替换旧值。
- 适用场景：数字、字符串、布尔、普通对象等单值字段；
- 状态定义示例：
python
运行
class LoopState(TypedDict): loop_times: int # 普通字段，默认覆盖 content: str - 执行过程： 原状态：
{"loop_times": 0}节点返回：{"loop_times": 1}最终状态：{"loop_times": 1}（旧值被覆盖）
2. 自定义规则：归约函数（Reducer）
通过Annotated[类型, 归约函数]显式指定合并逻辑，最常用在列表场景。
（1）内置常用：operator.add→ 列表追加
专门用于对话记录、执行日志、消息列表等需要保留历史、向后追加的场景。
- 状态定义：
python
运行
log: Annotated[list[str], operator.add] - 执行过程： 原状态：
{"log": ["第0轮思考完成"]}节点返回：{"log": ["第1轮思考完成"]}最终状态：{"log": ["第0轮思考完成", "第1轮思考完成"]}（新旧列表拼接）
（2）自定义归约函数
支持自己编写合并逻辑（保留最新、去重、条件合并等），规则同样作用于返回值。 函数格式：def 自定义函数(旧值, 新值) -> 合并后的值
三、多节点同时更新同一个字段的规则
当多个节点、或单次执行中多次更新同一个字段时，统一遵循该字段绑定的归约规则：
- 普通字段：后执行的节点值覆盖前面的值；
operator.add列表字段：所有更新内容依次追加；- 自定义归约字段：按自定义逻辑合并。
四、特殊场景规则
1. 节点无任何字段需要修改
如果当前节点仅做计算、打印日志，不需要修改任何状态：
- 写法：返回空字典
{} - 效果：全局状态完全不变，直接进入下一条边的路由逻辑。
python
运行
def empty_node(state: LoopState) -> dict: print("仅执行逻辑，不修改状态") return {} # 合法写法2. 字段值类型必须匹配
返回字典里的key: value，值的类型必须和 State 定义保持一致：
- State 定义
log: list[str]→ 返回必须是列表["内容"]，不能传字符串"内容"； - 类型不匹配不会直接报错（Python 动态类型），但会造成业务异常、IDE 类型校验失败，属于不规范写法。
3. 不允许新增 State 以外的字段
返回字典中的key，必须是TypedDict中预先定义好的字段名：
- 随意新增未定义字段，运行时不会报错，但违背状态结构约束，IDE 提示异常、后期难以维护，生产环境禁止。
五、结合之前代码举例复盘
状态定义
python
运行
class LoopState(TypedDict): content: str search_result: str loop_times: int log: Annotated[list[str], operator.add]节点返回值解析
python
运行
def think_step(state: LoopState) -> dict: cnt = state["loop_times"] print(f"【第 {cnt} 轮大模型的思考】") # 只更新 log 字段 return {"log": [f"第{cnt}轮思考完成"]}- 返回
dict，符合类型要求； - 仅返回增量字段
log，content/search_result/loop_times保持不变； log带有operator.add，执行列表追加，历史日志不丢失；- 值为字符串列表
[xxx]，和状态类型匹配。
六、完整规则速记（精简版）
- 格式：节点必须返回
dict； - 内容：只写需要修改的字段，增量更新，不返回完整状态；
- 更新逻辑
- 普通字段 → 新值覆盖旧值；
Annotated + operator.add列表 → 新内容追加；
- 边界情况：无需改状态 → 返回空字典
{}； - 约束：键名、值类型必须和
TypedDict定义一致，不随意增删字段