Langgraph 的节点函数都是返回的是状态更新字典吗
好问题!这涉及 LangGraph 的核心设计。让我从源码和实际使用两个层面来完整回答。
核心结论:StateGraph 节点签名 = State → Partial<State>
源码 state.py:113 明确写了:
The signature of each node is State → Partial<State>.
意思是:节点函数接收完整的当前状态,返回一个"部分状态字典"(只包含要更新的字段)。
节点函数的返回值,不止一种
结合你的项目和源码,实际有 5 种合法情况:
1️⃣ 返回部分状态字典(最常见 ✅)
就是你 Reducers.py 里的写法:
def example_node(state: State):
return {"bar": state["bar"] + ["OK"]} # 只写要更新的字段LangGraph 会把这个返回值合并到当前状态中。有 reducer 的字段用 reducer 合并,没有的字段直接覆盖。
2️⃣ 返回 None(或不 return)—— 节点只做副作用
def logging_node(state: State):
print("当前状态:", state) # 只打印,不更新
# 隐式返回 None状态不变,图继续往后走。你项目里 初识Graph.py:47 有个 pass 的占位节点就是这种情况。
3️⃣ 返回完整状态字典(⚠️ 不推荐,但可行)
def bad_node(state: State):
return {"foo": 1, "bar": ["a", "b"]} # 把所有字段都写一遍这也能跑,但语义上很危险——你很容易在无意中把某个字段遗漏/改错。而且有 reducer 的字段依然会走合并逻辑,导致结果出乎意料。应该只返回你真正想更新的字段。
4️⃣ 返回 Command 对象(高级用法,支持条件跳转)
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__") |
# 路由函数 —— 决定往哪走,不更新状态
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)。