概览
LangChain 的流式传输系统让你可以在应用中呈现代理运行的实时反馈。 LangChain 流式传输可以实现:- 流式传输代理进度:在每个代理步骤后获取状态更新。
- 流式传输 LLM tokens:在语言模型 tokens 生成时流式传输它们。
- 流式传输 thinking / reasoning tokens:在模型推理生成时呈现它。
- 流式传输自定义更新:发出用户定义信号(例如
"Fetched 10/100 records")。 - 流式传输多个模式:从
updates(代理进度)、messages(LLM tokens + metadata)或custom(任意用户数据)中选择。
支持的 stream modes
将以下一个或多个 stream modes 作为列表传给stream 或 astream 方法:
| 模式 | 描述 |
|---|---|
updates | 在每个代理步骤后流式传输状态更新。如果同一步中产生多个更新(例如运行多个节点),这些更新会分别流式传输。 |
messages | 从任何调用 LLM 的图节点流式传输 (token, metadata) 元组。 |
custom | 使用 stream writer 从图节点内部流式传输自定义数据。 |
代理进度
要流式传输代理进度,请使用带stream_mode="updates" 的 stream 或 astream 方法。这会在每个代理步骤后发出事件。
例如,如果有一个调用一次工具的代理,你应该会看到以下更新:
- LLM 节点:包含工具调用请求的
AIMessage - 工具节点:包含执行结果的
ToolMessage - LLM 节点:最终 AI 响应
config 传入 thread_id,使对话被 checkpoint,并让后续轮次可以恢复相同历史。thread_id 与 stream_mode 独立;也可以同时传入 context,用于工具从 runtime.context 读取每次运行的数据。
Output
使用
thread_id 持久化对话历史要求代理配置 checkpointer。在 LangSmith deployments 中会自动配置 checkpointer。在本地,请显式传入一个,例如 create_agent(..., checkpointer=InMemorySaver())。本页其余 snippets 为简洁起见省略 thread_id,但生产环境中应传入它。LLM tokens
要在 LLM 生成 tokens 时流式传输它们,请使用stream_mode="messages"。下面可以看到代理流式传输工具调用和最终响应的输出。
流式传输 LLM tokens
Output
自定义更新
要在工具执行时流式传输工具更新,可以使用get_stream_writer。
流式传输自定义更新
Output
如果在工具内部添加
get_stream_writer,就无法在 LangGraph 执行上下文之外调用该工具。流式传输多个模式
可以通过将 stream mode 作为列表传入来指定多个流式传输模式:stream_mode=["updates", "custom"]。
每个流式 chunk 都是一个带有 type、ns 和 data 键的 StreamPart dict。使用 chunk["type"] 判断 stream mode,并使用 chunk["data"] 访问 payload。
流式传输多个模式
Output
常见模式
下面示例展示流式传输的常见用例。流式传输 thinking / reasoning tokens
有些模型在生成最终答案之前会执行内部推理。可以通过筛选 standard content blocks 中type 为 "reasoning" 的内容,在这些 thinking / reasoning tokens 生成时流式传输它们。
必须在模型上启用 reasoning 输出。配置详情请参阅 reasoning section 和你的 provider’s integration page。要快速检查模型的 reasoning 支持,请参阅 models.dev。
stream_mode="messages" 并筛选 reasoning content blocks:
Output
content_blocks 属性,将 provider 特定格式(Anthropic thinking blocks、OpenAI reasoning summaries 等)规范化为标准 "reasoning" content block 类型。
要直接从聊天模型(不使用代理)流式传输 reasoning tokens,请参阅 streaming with chat models。
流式传输工具调用
你可能想同时流式传输:- tool calls 生成时的部分 JSON
- 已完成、已解析且被执行的工具调用
stream_mode="messages" 会流式传输代理中所有 LLM 调用生成的增量 message chunks。要访问带有已解析工具调用的完整消息:
- 如果这些消息在 state 中被跟踪(例如
create_agent的 model 节点),请使用stream_mode=["messages", "updates"]通过 state updates 访问完整消息(如下所示)。 - 如果这些消息没有在 state 中被跟踪,请使用 custom updates,或在流式循环期间聚合 chunks(见下一节)。
如果代理包含多个 LLM,请参阅下面的从 sub-agents 流式传输部分。
Output
访问完整消息
在某些情况下,完整消息不会反映在 state updates 中。如果你可以访问代理内部,可以使用 custom updates 在流式传输期间访问这些消息。否则,可以在流式循环中聚合 message chunks(见下文)。 考虑下面的示例,其中将 stream writer 集成到简化版 guardrail middleware 中。该 middleware 演示如何通过工具调用生成结构化的 “safe / unsafe” 评估(也可以使用 structured outputs 实现):Output
结合 human-in-the-loop 流式传输
为了处理 human-in-the-loop interrupts,这里基于上面的示例继续构建:- 使用 human-in-the-loop middleware 和 checkpointer 配置代理
- 收集
"updates"stream mode 期间生成的 interrupts - 使用 command 响应这些 interrupts
Output
Output
Output
从 sub-agents 流式传输
当代理中的任意位置存在多个 LLM 时,通常需要在消息生成时区分消息来源。 为此,请在创建每个代理时向其传入name。随后在 "messages" 模式下流式传输时,可以通过 metadata 中的 lc_agent_name 键获取该名称。
下面更新流式传输工具调用示例:
- 将工具替换为内部调用代理的
call_weather_agent工具 - 为每个代理添加
name - 创建流时指定
subgraphs=True - 流处理与之前相同,但增加逻辑,使用
create_agent的name参数跟踪当前活动代理
Output
禁用 streaming
在某些应用中,你可能需要为给定模型禁用单个 tokens 的流式传输。这在以下场景中很有用:- 使用 multi-agent 系统时,控制哪些代理流式传输输出
- 混合使用支持 streaming 和不支持 streaming 的模型
- 部署到 LangSmith,并希望阻止某些模型输出流式传输到客户端
streaming=False。
并非所有 chat model integrations 都支持
streaming 参数。如果你的模型不支持它,请改用 disable_streaming=True。该参数可通过基类在所有聊天模型上使用。v2 streaming 格式
需要 LangGraph >= 1.1。
stream() 或 astream() 传入 version="v2",即可获得统一输出格式。每个 chunk 都是一个带有 type、ns 和 data 键的 StreamPart dict,无论 stream mode 或模式数量如何,形状都相同:
invoke():它返回带有 .value 和 .interrupts 属性的 GraphOutput 对象,清晰分离 state 与 interrupt metadata:
相关
- Frontend streaming:使用
useStream构建支持实时代理交互的 React UI - Streaming with chat models:不使用代理或图,直接从聊天模型流式传输 tokens
- Reasoning with chat models:配置并访问聊天模型的 reasoning 输出
- Standard content blocks:了解用于 reasoning、text 和其他内容类型的规范化 content block 格式
- Streaming with human-in-the-loop:在处理人工审核 interrupts 时流式传输代理进度
- LangGraph streaming:高级流式传输选项,包括
values、debugmodes 和 subgraph streaming
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

