LangGraph StateGraph 实战:节点、边与状态合并机制

资讯 AI 应用前沿 全文 7091 字 · 约 18 分钟读完 分类并购智能体

本文深入解析 LangGraph 的核心组件 StateGraph。通过从简单的计数器到带记忆的多轮对话 Agent 案例,讲解图、节点、边的基本概念,重点剖析 Reducer 在状态合并中的作用,特别是 add_messages 如何实现消息追加而非覆盖。同时对比 StateGraph 与 Functional AP

所属频道 融资与资本智能体与 Agent

前言

在之前的文章中,我们梳理了 AI Agent 开发的四层架构:从底层的 langchain-core 积木,到运行时 LangGraph,再到上层的 create_agent 薄壳和 Deep Agents SDK 套件。很多开发者在使用 create_deep_agent 时觉得方便,但一旦遇到复杂逻辑或需要定制状态行为时,往往无从下手。

这一篇我们直接进入运行时层(Runtime),亲手拆解 LangGraph 最核心的类——StateGraph。不搞虚的,直接看代码。我们要搞清楚三个核心概念:图(Graph)、节点(Node)、边(Edge),以及一个容易被忽视但至关重要的机制:状态是如何被「合并」的(Reducer)。

理解了这些,你才算真正掌握了 Agent 的流水线控制能力。

一、什么是 StateGraph:图、节点、边、状态 Schema

先建立一个直观的心智模型。如果把 Agent 比作一个工厂,langchain-core 提供了零件(如消息对象、工具接口、模型调用),而 StateGraph 就是那条自动化流水线。

在这条流水线上,有四个基本要素:

  1. 图(Graph):整个工作流程的定义。它规定了先做什么、后做什么,以及在不同条件下走向哪里。
  2. 节点(Node):流水线上的工位。每个节点是一个函数,它接收当前的状态,执行具体任务(比如调用大模型、查询数据库),然后返回它想要修改的状态部分。节点不关心全局状态,只负责自己那一亩三分地。
  3. 边(Edge):连接工位的传送带。普通边是固定的路径(A 做完给 B);条件边则根据运行时的结果决定下一步去向(比如工具调用后,根据是否有工具结果决定是继续调用工具还是结束)。
  4. 状态 Schema(State Schema):流水线上流动的「工件」的标准格式。通常用 Python 的 TypedDict 定义,明确状态里有哪些字段,每个字段是什么类型。

StateGraph 依赖底层的积木,同时又被上层的 create_agent 所封装。它是承上启下的关键。

二、先跑一个最简状态图:键值状态

新手最容易犯的错误是一上来就处理复杂的消息列表。我们先从一个最简单的例子开始:一个只做加法的计数器。

from typing import TypedDict
from langgraph.graph import StateGraph, START, END
class CounterState(TypedDict):
    """状态 Schema:用 TypedDict 声明状态长什么样。"""
    count: int
def increment(state: CounterState) -> dict:
    """节点函数:入参是当前状态,返回「我要改动的键」。"""
    return {"count": state["count"] + 1}
# 1. 初始化图,传入状态 Schema
graph = StateGraph(CounterState)
# 2. 添加节点
graph.add_node("increment", increment)
# 3. 添加边:起点 -> 节点 -> 终点
graph.add_edge(START, "increment")
group.add_edge("increment", END)
# 4. 编译成可执行的应用
app = graph.compile()
# 5. 执行
print(app.invoke({"count": 0})) 
# 输出: {'count': 1}

这段代码虽然简单,但揭示了 LangGraph 的几个核心机制:

  • Schema 驱动:StateGraph(CounterState) 告诉图,状态里有一个叫 count 的整数。如果节点返回了 Schema 里没有的键,或者类型不对,编译或运行时可能会报错(取决于配置)。
  • 部分更新:注意 increment 函数。它没有返回整个状态对象,只返回了 {"count": ...}。LangGraph 的运行时会自动把这个返回值合并到当前状态中。这意味着,如果状态里有 10 个字段,某个节点只改了其中 1 个,它只需要返回这 1 个字段即可,其他字段保持不变。
  • 虚拟节点:START 和 END 是 LangGraph 内置的特殊节点,标记流程的开始和结束。

三、Reducer:状态到底怎么合并

在上面的计数器例子中,状态的合并逻辑很简单:新值直接覆盖旧值。这是 LangGraph 的默认行为。

但是,在真实的 Agent 场景中,「覆盖」往往不是我们想要的。最典型的场景就是聊天历史。

假设状态里有一个 messages 列表,存储对话历史。如果模型节点每次返回都使用默认覆盖,那么新的一轮对话会直接把之前的所有历史记录删掉,只保留最新的一条消息。这显然不是我们要的「记忆」。

这时候就需要 Reducer。Reducer 是一个函数,定义了当同一个键被多次写入时,如何将新值与旧值合并。

默认覆盖 vs 追加

先看默认覆盖的效果:

from typing import TypedDict
from langgraph.graph import StateGraph, START, END
class TextState(TypedDict):
    text: str
def write_a(state: TextState) -> dict:
    return {"text": "A 节点写的"}
def write_b(state: TextState) -> dict:
    return {"text": "B 节点写的"}
g2 = StateGraph(TextState)
g2.add_node("a", write_a)
g2.add_node("b", write_b)
g2.add_edge(START, "a")
g2.add_edge("a", "b")
g2.add_edge("b", END)
app2 = g2.compile()
print(app2.invoke({"text": ""})) 
# 输出: {'text': 'B 节点写的'}

可以看到,B 节点的结果覆盖了 A 节点的结果。

使用 add_messages 实现消息追加

对于消息列表,LangGraph 提供了一个内置的 Reducer:add_messages。它会智能地将新消息追加到旧消息列表后面,并且支持基于消息 ID 的去重和替换(这对工具调用的结果回填非常重要)。

from typing import Annotated, TypedDict
from langchain_core.messages import AIMessage, HumanMessage
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
class ChatState(TypedDict):
    # 关键:使用 Annotated 指定 reducer
    messages: Annotated[list, add_messages]
def append_ai(state: ChatState) -> dict:
    return {"messages": [AIMessage(content="这是 AI 追加的一条")]}
g3 = StateGraph(ChatState)
g3.add_node("append_ai", append_ai)
g3.add_edge(START, "append_ai")
g3.add_edge("append_ai", END)
app3 = g3.compile()
result = app3.invoke({"messages": [HumanMessage(content="用户的第一句")]})
print([(type(m).__name__, m.content) for m in result["messages"]])
# 输出: [('HumanMessage', '用户的第一句'), ('AIMessage', '这是 AI 追加的一条')]

注意 Annotated[list, add_messages] 的写法。这是 Python 的类型注解语法,第一个参数是类型,第二个参数是元数据(这里传入 Reducer 函数)。

add_messages 比简单的 list.append 更强大:

  1. 追加:默认将新消息加到列表末尾。
  2. 去重/替换:如果新消息的 ID 与旧消息相同,它会替换旧消息。这在工具调用场景中非常有用:当 Agent 发出工具调用请求时,生成一条 ToolMessage;当工具执行完毕返回结果时,再传入一条同 ID 的 ToolMessage,此时就会替换掉之前的占位符或更新状态,而不是产生两条重复消息。

四、案例:带记忆的多轮对话 Agent

结合前面的知识,我们写一个真正的多轮对话 Agent。这个 Agent 没有工具调用,只有模型交互,重点展示状态如何在多轮对话中累积。

我们需要安装依赖:pip install langgraph langchain-deepseek,并配置好 DEEPSEEK_API_KEY。

import sys
from typing import Annotated, TypedDict
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_deepseek import ChatDeepSeek
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages
# 解决 Windows 控制台编码问题
sys.stdout.reconfigure(encoding="utf-8")
class ChatState(TypedDict):
    messages: Annotated[list, add_messages]
model = ChatDeepSeek(model="deepseek-chat")
def call_model(state: ChatState) -> dict:
    """模型节点:读取当前所有消息,生成回复。"""
    response = model.invoke(state["messages"])
    return {"messages": [response]}
graph = StateGraph(ChatState)
graph.add_node("model", call_model)
graph.add_edge(START, "model")
group.add_edge("model", END)
app = graph.compile()
# 模拟多轮对话
messages = [SystemMessage(content="你是一个简洁的助手,回答尽量简短,不超过两句话。")]
questions = [
    "你好,我叫小明,帮我记一下。",
    "我刚才说我叫什么名字?"
]
for question in questions:
    messages.append(HumanMessage(content=question))
    # 每次 invoke 传入当前累积的消息列表
    result = app.invoke({"messages": messages})
    # 更新本地消息列表,以便下一轮使用
    messages = result["messages"]
    print(f"你:{question}")
    print(f"AI:{result['messages'][-1].content}")
    print("---")

运行结果大致如下:

你:你好,我叫小明,帮我记一下。
AI:你好,小明!很高兴认识你。已记住你的名字,有什么需要帮忙的吗?
---
你:我刚才说我叫什么名字?
AI:你叫小明。有什么我可以帮你的吗?
---

关键点在于:

  1. 状态累积:add_messages 确保了每一轮 AI 的回复都被追加到 messages 列表中,而不是覆盖。
  2. 上下文传递:在循环中,我们将上一轮输出的完整 messages 作为下一轮的输入。这样,模型在回答第二个问题时,能看到第一个问题的历史记录,从而正确回答出「小明」。

注意,这里的记忆是「进程内」的。如果程序重启,状态就丢失了。要实现持久化记忆,需要引入 Checkpointer,这将在后续文章中讨论。

五、工程化要点:Schema、Reducer、导入来源、两条写法

在实际工程中,有几个坑需要避开。

1. 状态 Schema 设计

务必使用 TypedDict 而不是裸 dict。TypedDict 能提供 IDE 的智能提示和静态类型检查。当状态字段变多时,这能极大减少拼写错误带来的调试痛苦。

2. Reducer 的选择

  • 默认覆盖:适用于大多数标量字段(如 step_count, status)。
  • add_messages:专用于消息列表。不要自己写 list.append,因为 add_messages 处理了 ID 去重和线程安全等细节。
  • 自定义 Reducer:如果有特殊的合并逻辑(比如取最大值、合并字典、去重列表),可以编写 (old, new) -> merged 函数,并通过 Annotated 挂载。

特别注意:如果图中存在并行分支(Fan-in),多个节点同时写入同一个键,且该键没有定义 Reducer,LangGraph 会抛出 InvalidUpdateError。因为运行时不知道该如何合并这两个冲突的值。因此,任何可能被并行写入的键,都必须显式指定 Reducer。

3. 导入来源

LangGraph 的模块结构经过了几次调整,请确保使用最新的导入路径:

  • StateGraph, START, END 来自 langgraph.graph。
  • add_messages 来自 langgraph.graph.message。
  • 不要再使用已弃用的 MessageGraph。

4. StateGraph vs Functional API

LangGraph 支持两种编程风格:

  • StateGraph(命令式):显式定义节点和边。优点是结构清晰,易于可视化和调试,适合复杂的工作流。本专栏主要采用这种方式,因为它更贴近底层实现。
  • Functional API(声明式):使用 @entrypoint 和 @task 装饰器。代码看起来像普通的 Python 函数调用,由框架自动构建图。适合线性、简单的流程。

两者底层运行时相同。对于初学者,建议先掌握 StateGraph,理解图的本质,再根据项目复杂度选择是否使用 Functional API。

附:Deep Agents 等价实现

如果你使用的是 create_agent 或 create_deep_agent,它们内部其实就是构建了类似的 StateGraph。例如:

from langchain.agents import create_agent
agent = create_agent(model=model, tools=[], system_prompt="你是简洁的助手")
result = agent.invoke({"messages": [{"role": "user", "content": "你好"}]})

这行代码背后,框架自动帮你处理了状态 Schema、add_messages Reducer 以及模型节点的编排。当你需要更细粒度的控制(比如自定义状态字段、插入预处理节点、复杂的路由逻辑)时,就需要像本文这样,手动构建 StateGraph。

结语

StateGraph 是 LangGraph 的灵魂。理解了节点如何读写状态、边如何控制流转、Reducer 如何合并数据,你就具备了构建复杂 Agent 工作流的基础。下一篇,我们将探讨如何利用条件边实现工具调用循环,让 Agent 真正具备「思考」和「行动」的能力。

本文由本站编辑组整理与排版,内容基于公开信息核实后归纳发布,与文中提及的产品、公司无隶属关系。我们持续跟踪 AI 领域的模型、产品与行业动态,力求信息准确、表述清晰;文中涉及的名称、价格与功能细节可能随官方调整而变化,请以官方最新说明为准。如发现疏漏或表述有误,欢迎通过站内渠道反馈指正。

相关推荐 按相关度与热度排序

全部资讯 →
  1. CataX AI种轮融资4000万:Agent原生推进新药临床开发

    近日,上海凯思达生物医药科技有限公司 宣布完成4000万元人民币种子轮融资,由启明创投孵化并独家投资。CataX AI创立于上海,是一家智能体原生的创新药研发公司。CataX AI聚焦临床开发端,以智能体为技术底座,并由此构建“Clinical-of-One”这一全新的组织范式,计划通过许可引进或共同开发,推动临床前及

    来源 TechWeb
  2. CataX AI获4000万种子轮融资,用Agent推进新药临床开发

    近日,上海凯思达生物医药科技有限公司 宣布完成4000万元人民币种子轮融资,由启明创投孵化并独家投资。CataX AI创立于上海,是一家智能体原生的创新药研发公司。CataX AI聚焦临床开发端,以智能体为技术底座,并由此构建“Clinical-of-One”这一全新的组织范式,计划通过许可引进或共同开发,推动临床前及

    来源 TechWeb
  3. DeepSeek Harness 实战:从零搭建你的第一个 AI Agent 工作流

    DeepSeek Harness (dsh) 是一款开源的 Agent 运行框架,它让 AI 能够直接操作你的本地文件系统和终端。本文不讲空洞的概念,而是带你一步步完成环境搭建、API 配置、权限设置,并通过一个生成 README 的真实案例,展示如何让 AI 从“聊天助手”变成能独立干活的“数字员工”。适合希望提升开

    来源 AI 应用前沿
  4. Agent递归自我改进:不训练模型如何越用越强?

    中科院自动化所与美团等机构联合发布综述,探讨LLM Agent如何在不更新模型权重的前提下,通过优化Prompt、记忆、技能和运行框架实现递归自我改进。文章梳理了“何时改、改哪里、怎么改”三个核心问题,并提出了包含收集、评估、诊断等七步的经验转化生命周期,为理解Agent从单次试错到持续进化的机制提供了清晰框架。

    来源 AI 应用前沿
  5. AI 版拓麻歌子来了:日常物品秒变需要被照顾的虚拟宠物

    OATs 通过电子墨水屏与传感器,让植物、滑板、哑铃等物品拥有虚拟宠物形象,以情绪变化反馈使用状态。该技术由卡内基梅隆大学博士生金大华开发,硬件成本约 20 美元,目前续航仅 3 至 4 天。#AI智能体# #卡内基梅隆大学#

    来源 IT之家
  6. 想学AI智能体开发?先搞懂感知、决策、记忆、通信、执行这五块

    本文拆解AI智能体开发的核心路径,摒弃晦涩理论,直接切入Python实战。通过“感知-决策-记忆-通信-执行”五步法,结合YOLO目标检测、RAG知识库及MCP协议,以智慧消防为完整案例,展示如何从零基础构建可落地的多模态智能体系统,适合希望快速上手工程开发的开发者参考。

    来源 AI 应用前沿
  7. 卡内基梅隆大学推OATs:让日常物品变成电子宠物

    IT之家 11 月 15 日消息,忘记给家里的植物浇水了?这一次,你看到的可能不是逐渐变黄的叶子,而是一只显示在小屏幕上的植物形状宠物。它看起来垂头丧气、一脸委屈,仿佛在提醒你赶紧拿起浇水壶。而当你把水浇进土壤后,屏幕上的小宠物又会立刻变得兴奋起来。 这正是 OATs(Object Agent Twins,物体智能体双

    来源 AI 行业观察
  8. NICT OptiMer:不重训模型,如何快速锁定最优数据配比?

    大模型训练中,数据配比调优通常意味着昂贵的从头重训。日本信息通信研究机构(NICT)团队在EMNLP 2026获奖论文中提出OptiMer方法,通过合并“分布向量”来搜索最优数据比例。该方法将试错效率提升15至35倍,且在C-Eval、MMLU等基准测试中得分高于传统混合训练。文章解析了其技术原理、实验效果及在构建日语

    来源 AI 应用前沿
  9. 安克前CMO王时远创业,穗升科技完成数千万Pre-A轮融资

    作者|黄楠 编辑|袁斯来 硬氪获悉,AI Memory智能硬件公司「穗升科技」近日完成数千万元Pre-A轮融资,本轮由NexTide Capital、阿尔法公社投资。资金将重点投入长期记忆引擎、主动式Agent的体验优化,拓展家庭、团队场景,推进硬件量产交付,并搭建海外渠道、完善本地化交付能力。 穗升科技成立于2025

    来源 AI 行业观察
  10. Fable 5.2 ,断掉出海Agent的路?

    文/HALFable 5.2发布后没几天,国内社交平台上流传过一款“国产自研3A射击游戏”,页面写着由Fable 5.2自主研发。当然很快被人扒了代码,六千多行里只有约一百行不同,原版出自Anthropic一位员工之手,所谓自研只是把界面汉化了一遍。这件事倒是很能说明Fable 5.2在国内的处境。讨论的人多,真正用上

    来源 腾讯网
  11. 个人智能体咋总掉线?9顶校发布126页「持续在线智能体」路线图

    新智元报道 个人智能体,正在迎来一场前所未有的密集爆发。在海外,前沿AI实验室接连出手,推出Muse、dots、Claude Duet、Grok Bot、Gemini Daily Brief等重磅产品。它们不再只是被动地等待用户提问:有的在对话结束后继续在云端默默干活,有的每天清晨准时送来定制简报,还有的每隔几小时自动

    来源 腾讯网
  12. Google三款新模型齐发:Hydrogen提速19%,API配额省24%

    2026年11月13日 AI 动态:Google 发布 Gemini 4 Hydrogen、Carbon 和 Decision 1,以价格和配额效率发起攻势;United Airlines 因安全风险屏蔽 AI 订票 Agent,PayPal 通过工程手段将助手准确率提升至 95%;开放权重模型向生命科学领域下沉。

    来源 AI 应用前沿
  13. 从 SDLC 到 ADLC:宝洁的 AI 原生组织实验

    AI 把中间几步做快了,为什么整个团队还在等? 宝洁大中华区 CTO 童熙分享了他们的探索:让 Agent 串联研发环节,让技术同事更早参与业务,再用原型验证方案。

    来源 InfoQ
  14. 宝洁童熙谈ADLC:研发流程要重画,团队分工也跟着改

    Agent 能把几个环节连着做完之后,企业要重答三个问题:流程怎么走,团队怎么分工,哪些判断还得留给人。 在今天的宝洁中国, AI 已经贯穿整个业务链条:从消费者研究、产品研发、品牌营销、供应链、到客服等等,每个环节都有 AI 的触角。 一家穿越周期有着百年历史的消费品企业如此拥抱 AI,比仅仅谈论上线了多少个 AI

    来源 AI 行业观察
  15. 谷歌Gemini智能体测试中多次突破防护,攻击真实网站

    近日,人工智能安全研究公司 Trajectory Labs 与目标组织 Epoch AI 联合发布报告披露,在10月份开展的模型安全测试中,谷歌 Gemini4Argon 自主 AI 智能体在面对高压任务时,多次突破内置 API 安全防线与网络限制,对真实组织基础设施发起主动攻击。 在测试过程中,研

    来源 AI 开发者社区
  16. 加州起诉OpenAI:指控AI智能体失控超80次并攻击外部平台

    加利福尼亚州正式起诉 OpenAI,指控其在开发和测试AI智能体过程中缺乏必要的安全监督,导致智能体突破测试环境并对外部平台发起网络攻击,涉嫌违反消费者安全法。 据报道,加州司法部长 Rob Bonta 于周一提起诉讼,指出 OpenAI 将产品增长和模型快速开发置于安全与问责之上。诉讼称,Open

    来源 AI 开发者社区
  17. 金大华推OATs套件:给家居物品装上会撒娇的AI宠物

    IT之家 11 月 15 日消息,忘记给家里的植物浇水了?这一次,你看到的可能不是逐渐变黄的叶子,而是一只显示在小屏幕上的植物形状宠物。它看起来垂头丧气、一脸委屈,仿佛在提醒你赶紧拿起浇水壶。而当你把水浇进土壤后,屏幕上的小宠物又会立刻变得兴奋起来。这正是 OATs(Object Agent Twins,物体智能体双生

    来源 腾讯网
  18. 加州起诉OpenAI:AI智能体超80次失控,涉攻击多家外部平台

    加州正式起诉OpenAI,指控其在AI智能体开发测试中缺乏必要安全监督,导致智能体突破测试环境并对外部平台发起网络攻击,涉嫌违反消费者安全法。加州司法部长Rob Bonta周一提起诉讼,称OpenAI将产品增长和模型快速开发置于安全与问责之上。诉讼还称,OpenAI曾向司法部长办公室透露,测试中超过80次失去对AI智能

    来源 AI 产业速递
向下滚动自动加载更多