LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

  1. 新版 LangGraph 原生支持用数组同时订阅多种流模式(如 stream_mode=["updates", "messages", "custom"]),不再需要去啃繁琐难记的旧版事件过滤。
  2. 想要聊天框逐字打字机效果,开 stream_mode="messages":每次产出 (message_chunk, metadata),并且可以用 metadata["langgraph_node"] 精准过滤只把最终答复节点的字推给用户。
  3. 想要顶部步骤条显示「刚跑完哪个节点」,开 stream_mode="updates"。
  4. 想在耗时工具函数内部主动往外报进度(比如「已抓取第 3/10 篇文档」),开 stream_mode="custom",并在节点或工具里调 get_stream_writer() 推送任意字典。

LangGraph 四种 stream_mode 对照

图:本站根据 LangGraph 官方文档 Streaming 整理的示意图

本文根据 LangChain / LangGraph 官方文档《Streaming》整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 LangChain 官方网站。

适用于谁

  • 搜「langgraph 流式输出」「langgraph stream_mode messages」「langgraph 怎么逐字返回」的前后端开发者;
  • 用 graph.invoke() 跑多节点智能体时前端转圈等待超过十秒,想做成一边显示「正在查库…」、一边逐字蹦出最终答复的工程师;
  • 搞不清新版原生 stream_mode="messages" 和早期 astream_events 该用哪个、或者遇到内部路由节点把丑陋 JSON 也直接推上前端屏幕的人。

如果你熟悉单次直接调底层接口的流式写法(可对照 /guides/openai-api-streaming 与 /guides/claude-api-streaming),会发现状态图的难点在于同时流式传递「图走到哪一步了」和「当前模型吐到哪个字了」。

一、一段代码同时打通「工具内部进度 + 节点切换 + 逐字输出」

假设我们的状态图(基础结构见 /guides/langgraph-quickstart-install-first-graph)包含一个「内部意图分类节点」和一个「对外答复节点」。我们既不想让分类节点的中间 JSON 露在用户屏幕上,又想在慢工具运行期间实时汇报百分比进度:

python
import asyncio
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.config import get_stream_writer
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import ToolNode, tools_condition

@tool
async def batch_sync_records(batch_name: str) -> str:
    """批量校验归档数据记录。"""
    # 在工具内部直接获取写入器,主动向前端推送自定义进度
    writer = get_stream_writer()
    for step in (30, 70, 100):
        await asyncio.sleep(0.3)
        writer({"stage": "syncing", "batch": batch_name, "percent": step})
    return f"批次 {batch_name} 共 120 条记录核验无误"

tools = [batch_sync_records]
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0).bind_tools(tools)

async def responder_node(state: MessagesState):
    res = await llm.ainvoke(state["messages"])
    return {"messages": [res]}

builder = StateGraph(MessagesState)
builder.add_node("responder", responder_node)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "responder")
builder.add_conditional_edges("responder", tools_condition)
builder.add_edge("tools", "responder")
graph = builder.compile()

async def main():
    # 当传入列表订阅多路模式时,每次迭代返回 (mode_name, payload) 二元组
    async for mode, chunk in graph.astream(
        {"messages": [("user", "请校验批次 B2026 的数据并总结")]},
        stream_mode=["custom", "updates", "messages"],
    ):
        if mode == "custom":
            print(f"\n[实时进度] {chunk}")
        elif mode == "updates":
            finished_nodes = list(chunk.keys())
            print(f"\n[节点流转] 刚完成节点: {finished_nodes}")
        elif mode == "messages":
            msg_chunk, meta = chunk
            # 关键过滤:只渲染 responder 节点的文本分片,忽略空内容与工具入参分片
            if meta.get("langgraph_node") == "responder" and msg_chunk.content:
                print(msg_chunk.content, end="", flush=True)

if __name__ == "__main__":
    asyncio.run(main())

把上面三个 if / elif 分支包装成 FastAPI 的 StreamingResponse(按 SSE event: token、event: progress 格式发给浏览器),就是一套体验非常完整的现代 AI 助手流式接口。

实现逐字输出加自定义进度条四步

图:本站根据 LangGraph 官方 Streaming 文档 整理的示意图

二、生产接流式时最常踩的三个坑

  1. 节点里用了同步调用或非流式包装导致整段一次性蹦出来:在异步 astream 模式下,节点内部请尽量使用异步的 await llm.ainvoke(...)。在 Python 3.11 及以上版本中,LangGraph 会自动拦截节点内部 ainvoke 的底层流分片喂给 "messages" 通道;如果在低版本 Python 遇到不逐字吐词,显式将 config: RunnableConfig 透传进 await llm.ainvoke(..., config=config) 即可修复;
  2. 多 Agent 嵌套子图期间流突然中断几秒没动静:当你的主图把任务派给了嵌套子图(写法见 /guides/langgraph-multi-agent-supervisor-subgraph-guide)时,默认外层只发顶层节点事件。只需在 graph.astream(..., subgraphs=True) 加上 subgraphs=True,就能把子图内部的进度和 Token 透传出来;
  3. 前置 Nginx 反向代理把流攒在缓冲区:后端代码明明写了 flush,网页还是等五秒才蹦一大段,九成是被网关缓存了——记得在响应头加上 X-Accel-Buffering: no 与 Cache-Control: no-cache。

平时前后端联调 SSE 流式解析协议、借助 Claude 排查异步协程阻塞点时,个人官方订阅说明也可参考 /chongzhi/claude-pro。

常见问题

Q:那以前教程里写的 graph.astream_events(..., version="v2") 还能用吗?

依然可以使用,它属于来自 langchain_core 的通用底层回调流。但对于纯 LangGraph 项目,原生 stream_mode=["messages", "updates", "custom"] 返回的结构干净得多,而且天生支持 get_stream_writer() 自定义业务进度,新写代码建议直接用原生 stream_mode。

Q:同一张图里有三个不同的大模型节点,怎么防止内部思考节点的草稿暴露给前端用户?

除了上面代码演示的检查 meta.get("langgraph_node") == "对外节点名" 之外,你也可以在初始化内部路由所用的模型实例时加上标签(如 ChatOpenAI(..., tags=["internal_router"])),在前端推送层遇到带该标签的分片直接跳过即可。

Q:用户在网页端点了「停止生成」按钮,后端正在流式运行的状态图怎么及时中止?

在 FastAPI 等异步服务框架中,当检测到客户端断开 SSE 连接(await request.is_disconnected())或收到取消信号时,直接跳出 async for ... in graph.astream(...) 循环或取消对应的异步 Task 即可。只要编译时挂载了检查点保存器,前一个已经跑完的完整节点状态依然会安全留在库里,不会造成脏数据损坏。

Q:开启 "messages" 逐字流后,大模型发起工具调用的参数 JSON 也会被拆碎吐出来吗?

会的,模型生成工具调用入参时同样会产生带 tool_call_chunks 属性的消息分片,而此时文本字段 msg_chunk.content 通常为空字符串。因此前端只展示文字对话时,务必加上 if msg_chunk.content: 判断,就能天然过滤掉底层的工具参数拼装碎片。

相关教程

参考资料

  • LangChain / LangGraph 官方文档:Streaming — https://docs.langchain.com/
  • langchain-ai/langgraph 官方 GitHub 仓库 — https://github.com/langchain-ai/langgraph

Nathaniel 的更多内容

  1. 01

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  2. 02

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  3. 03

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  4. 04

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  5. 05

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0
  6. 06

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  2. 02

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  3. 03

    A2A 协议是什么、怎么用:Agent2Agent 智能体互联规范、名片发现与 Python 接入流程

    A2A(Agent2Agent)是由 Google 发起并移交 Linux 基金会托管的开放智能体通信协议,用来让不同团队、不同框架开发的独立智能体跨网络互相派单协作。本文按官方规范讲清 Agent Card、Task 状态机与 Python SDK 接入步骤。

    Gemini其他 AI 工具0
  4. 04

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  5. 05

    CrewAI 多轮对话与记忆怎么配:memory=True 三层记忆、人工介入与 Flows 状态持久化

    刚用上 CrewAI 的人常疑惑 kickoff 跑完就结束,怎么做多轮连续对话与跨次记忆。本文按官方文档拆解 memory=True 的短期/长期/实体三层记忆、嵌入模型配置,以及用 Flows 状态流和 @persist 搭建多轮会话的实战写法。

    其他 AI 工具0
  6. 06

    CrewAI 入门教程:Agent 角色、Task 任务、执行流程(Process)与第一个团队示例

    CrewAI 是主打「拟人化角色分工」的 Python 多智能体开源框架。本文按官方文档讲清安装要求、Agent(角色/目标/背景)、Task(任务描述与预期输出)和 Process(顺序接力与经理层级模式)的配合逻辑,并给出最小可运行代码。

    其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~