Langgraph 的节点函数都是返回的是状态更新字典吗

管理员
管理员
发布于 2026-11-03 编辑

好问题!这涉及 LangGraph 的核心设计。让我从源码和实际使用两个层面来完整回答。


核心结论:StateGraph 节点签名 = State → Partial<State>

源码 state.py:113 明确写了:

The signature of each node is State → Partial<State>.

意思是:节点函数接收完整的当前状态,返回一个"部分状态字典"(只包含要更新的字段)。


节点函数的返回值,不止一种

结合你的项目和源码,实际有 5 种合法情况:

1️⃣ 返回部分状态字典(最常见 ✅)

就是你 Reducers.py 里的写法:

Python
def example_node(state: State):
    return {"bar": state["bar"] + ["OK"]}   # 只写要更新的字段

LangGraph 会把这个返回值合并到当前状态中。有 reducer 的字段用 reducer 合并,没有的字段直接覆盖。

2️⃣ 返回 None(或不 return)—— 节点只做副作用

Python
def logging_node(state: State):
    print("当前状态:", state)   # 只打印,不更新
    # 隐式返回 None

状态不变,图继续往后走。你项目里 初识Graph.py:47 有个 pass 的占位节点就是这种情况。

3️⃣ 返回完整状态字典(⚠️ 不推荐,但可行)

Python
def bad_node(state: State):
    return {"foo": 1, "bar": ["a", "b"]}   # 把所有字段都写一遍

这也能跑,但语义上很危险——你很容易在无意中把某个字段遗漏/改错。而且有 reducer 的字段依然会走合并逻辑,导致结果出乎意料。应该只返回你真正想更新的字段。

4️⃣ 返回 Command 对象(高级用法,支持条件跳转)

Python
from langgraph.types import Command

def router_node(state: State):
    if state["foo"] > 10:
        return Command(update={"result": "big"}, goto="end_node")
    else:
        return Command(update={"result": "small"}, goto="process_node")

Command 把"状态更新"和"路由跳转"打包在一起,相当于一个节点同时做了业务逻辑 + 条件边的事。

5️⃣ MessageGraph 节点(已废弃 ⚠️)

# MessageGraph 已在 1.0.0 标记废弃,用 StateGraph + messages 字段替代
builder = MessageGraph()
builder.add_node("chatbot", lambda state: [("assistant", "Hello!")])  # 返回消息列表

MessageGraph 的节点返回的是消息列表而非字典,因为它整个 state 就是一个消息列表(用 add_messages 函数拼接)。源码也明确建议迁移到带 messages 字段的 StateGraph。


⚠️ 容易混淆的:路由函数(条件边)不返回状态字典

不要和节点函数搞混:

类型 输入 返回值
节点函数 当前 State 部分 State 字典 / None / Command
路由函数 当前 State 目标节点名字符串(如 "node_a" / "__end__")

Python
# 路由函数 —— 决定往哪走,不更新状态
def route(state: State) -> str:
    if state["foo"] > 0:
        return "positive_node"
    else:
        return "negative_node"

builder.add_conditional_edges("decide", route, {
    "positive_node": "positive_node",
    "negative_node": "negative_node",
})

一张图总结

LangGraph 节点函数返回值
├── dict[str, Any]        ← 部分状态更新(最常用)
├── None                  ← 无状态更新,仅副作用
├── Command               ← 状态更新 + 显式路由跳转
├── Runnable              ← 传入 LangChain Runnable(自动适配)
└── list[MessageLike]    ← 仅 MessageGraph(已废弃)

所以回答你的问题:大多数时候确实是返回状态更新字典,但这不是唯一选项——None、Command 也是合法的,旧版 MessageGraph 还返回消息列表。理解了这一点,在写 Agent 时就能灵活选择(比如副作用节点返回 None,需要动态跳边时用 Command)。