Streaming 与事件流

Deep Agents 有两层流式接口：稳定主线沿用 LangGraph graph streaming，暴露 messages、updates 与 subgraph namespace；实验性的 event streaming 再把复杂 graph 事件投影为 subagents、tool calls 和 output 等产品级概念。

先分清两层接口

接口	适合什么	稳定性
`stream` / `astream`	token、state update、custom event、原始 subgraph	当前核心能力
`stream_events` / `streamEvents`	面向 UI 的 subagent、message、tool-call 投影	Beta，v3 API

不要为了简单 token UI 引入 Beta event API。只有当产品需要展示 subagent 生命周期、嵌套工具或任务级进度时，再使用 event projection。

前端类比

普通 streaming 类似底层事件总线，携带不同 channel 的原始事件；event streaming 类似为 UI 封装的 selector，把底层节点和 namespace 转成“研究任务开始”“工具完成”等领域事件。

Deep Agents 原生语义：普通 stream 来自编译后的 LangGraph 图。Deep Agents event stream 在其上识别 task 委派并构造 subagent projection；stream.subagents 表示产品级委派，不等同于 LangGraph subgraphs 的任意图结构。

普通 Streaming

Python 推荐使用 v2 统一 chunk：

python

for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "比较两份本地政策"}]},
    stream_mode=["updates", "messages", "custom"],
    subgraphs=True,
    version="v2",
):
    print(chunk["type"])
    print(chunk["ns"])
    print(chunk["data"])

type 表示 updates、messages 或 custom。
ns=() 表示主图。
ns 中以 tools: 开头的片段通常来自 task/subagent 执行。
data 的形状由 stream mode 决定，不能全部当作字符串。

TypeScript 使用相同的 graph streaming 概念：

const stream = await agent.stream(
  {
    messages: [{ role: 'user', content: '比较两份本地政策' }],
  },
  {
    streamMode: ['updates', 'messages', 'custom'],
    subgraphs: true,
    version: 'v2',
  }
)

for await (const chunk of stream) {
  console.log(chunk.type, chunk.ns, chunk.data)
}

Beta Event Streaming

Beta：v3 projection 的方法名、字段和生命周期仍可能变化。前端事件协议应放在自己的 adapter 后面，不要让组件直接依赖所有原始字段。

PythonTypeScript

python

stream = agent.stream_events(
    {"messages": [{"role": "user", "content": "调研两个主题"}]},
    version="v3",
)

for event in stream.interleave("messages", "subagents"):
    print(event)

const stream = agent.streamEvents(
  { messages: [{ role: 'user', content: '调研两个主题' }] },
  { version: 'v3' }
)

for await (const event of stream.interleave('messages', 'subagents')) {
  console.log(event)
}

常用 projection：

Python	TypeScript	含义
`stream.messages`	`stream.messages`	主 Agent messages
`stream.tool_calls`	`stream.toolCalls`	主 Agent 工具调用
`stream.subagents`	`stream.subagents`	委派的 subagent 生命周期
`subagent.messages`	`subagent.messages`	指定 subagent messages
`subagent.tool_calls`	`subagent.toolCalls`	指定 subagent 工具调用
`subagent.output`	`subagent.output`	最终 subagent output
`subagent.task_input`	`subagent.taskInput`	委派给 task 的输入

UI 数据流

Adapter 应把实验字段转换成应用自己的稳定事件：

type AgentUiEvent =
  | { type: 'message.delta'; source: string; text: string }
  | { type: 'tool.started'; id: string; name: string }
  | { type: 'subagent.status'; id: string; status: string }
  | { type: 'approval.required'; interruptId: string }

正确处理流

使用 run、thread、message、tool call 与 subagent 的稳定 id 去重。
不假设不同 channel 严格按业务顺序到达。
对断线重连使用 checkpoint 或服务端事件游标，不只靠前端数组。
对 tool args 增量做缓冲，完整 JSON 未到达前不要执行。
对超大 tool result 展示摘要和 artifact 链接。
UI 卸载时取消订阅，但不要把取消订阅等同于取消后台任务。

先修

下一步

Human-in-the-loop

Streaming 与事件流 ​

先分清两层接口 ​

前端类比 ​

普通 Streaming ​

Beta Event Streaming ​

UI 数据流 ​

正确处理流 ​

先修 ​

下一步 ​

官方参考 ​