Aegra实时流式输出详解:8种SSE流模式、自动重连与事件回放
Aegra实时流式输出详解:8种SSE流模式、自动重连与事件回放
Aegra 是一个开源的自托管 AI Agent 后端(FastAPI + PostgreSQL),作为 LangGraph Platform 的免费替代方案。它的实时流式输出基于 SSE(Server-Sent Events)实现:Agent 每生成一个 token、每调用一次工具、每变更一次状态,都会实时推送给你的客户端。本文带你完整掌握 Aegra 的 8 种 SSE 流模式、自动重连机制和事件回放能力,让你的聊天界面真正做到"打字机式"输出。
为什么选择 Aegra 做 Agent 流式输出
传统的"发请求—等结果"模式在 LLM 场景下体验极差:一次回答可能要等 30 秒以上,用户只能盯着转圈。Aegra 通过 SSE 把执行过程拆解成细粒度事件流:
- 逐 token 输出:LLM 生成内容边产边推,前端即时渲染;
- 过程透明:工具调用、状态变更、节点执行进度全部可见;
- 断线可恢复:事件会保留在回放缓冲区,重连后从断点续传,不丢消息。
相关 API 路由定义在 runs.py,流式执行引擎在 graph_streaming.py。
8种SSE流模式速查表
Aegra 的流式输出由 stream_mode 参数控制——可以传单个模式字符串,也可以传列表组合使用。官方文档见 streaming.mdx。
| 模式 | 推送内容 | 典型用途 |
|---|---|---|
values |
每个节点执行后的完整状态快照 | 展示整体状态、调试 |
updates |
每个节点产生的状态增量(delta) | 只关心"变了什么" |
messages |
LLM token 与工具调用,聚合为 messages/partial 和 messages/complete 事件 |
打字机式聊天界面 |
messages-tuple |
原始 (message, metadata) 元组,不做聚合 |
JS 图兼容性 |
custom |
节点内部通过 get_stream_writer() 自定义推送的数据 |
进度条、中间提示 |
events |
底层 LangGraph astream_events 细粒度事件 |
精细追踪/可观测性 |
debug |
checkpoint 与任务结果事件(每条流内部自动启用) | 调试与中断检测 |
tools |
工具调用通道(Agent Protocol v2 事件流) | 前端展示工具调用卡片 |
💡
debug和updates在每条流内部都会运行(用于 checkpoint 跟踪和 human-in-the-loop 中断检测),但只有你显式请求时,对应事件才会推给客户端。
多模式同时开启时,每个 chunk 的 event 字段会标注它来自哪个模式,例如 ["values", "messages"] 组合可以既看完整状态又看逐 token 输出。
三个常用流式调用方式
1. 创建并流式(最常用):一次调用既创建 run 又流式返回输出,底层走 POST /threads/{thread_id}/runs/stream:
async for chunk in client.runs.stream(
thread_id=thread_id,
assistant_id="agent",
input={"messages": [{"type": "human", "content": "Hello!"}]},
stream_mode=["messages-tuple"],
):
if hasattr(chunk, "data") and chunk.data:
print(chunk.data)
2. 流式订阅已存在的 run:后台任务创建后,随时用 GET /threads/{thread_id}/runs/{run_id}/stream 挂上去看进度,并支持通过 Last-Event-ID 请求头断点续传。
3. 只等结果不流式:client.runs.wait() 调用 POST /threads/{thread_id}/runs/wait,直接返回最终输出;长任务也可以 runs.create() 后台执行,再 runs.join() 取结果。
自动重连:Last-Event-ID 断点续传
网络抖动、代理超时是长连接场景的家常便饭。Aegra 的解决方案分三步:
- 客户端记录收到的最后一个事件 ID;
- 重连时在请求头带上
Last-Event-ID; - 服务端从回放缓冲区补发所有错过的事件,然后继续实时推送。
重连逻辑实现在 runs.py 的 /runs/{run_id}/stream 端点中:若 run 已终结且未带 Last-Event-ID,直接发一条 end 事件收尾;带上了则先从缓冲区回放再结束,一个事件都不少。
事件回放缓冲区:断线10分钟内不丢事件
重连能生效的前提是事件还在。Aegra 把流式事件存入回放缓冲区:
- 生产环境(
REDIS_BROKER_ENABLED=true):事件写入 Redis List,由 Worker 经 Redis Pub/Sub 发布,任何实例的 SSE 连接都能订阅——客户端和 Worker 可以位于不同节点; - 开发模式:进程内内存列表,行为一致。
事件在 run 完成后保留 10 分钟(常量 REPLAY_RETENTION_SECONDS = 600,见 base_broker.py),Redis 侧通过 TTL 自动过期清理(redis_broker.py)。
防断线双保险:keepalive 心跳与断连策略
即使 Agent 长时间静默(比如某节点持有上游 WebSocket 不产出事件),连接也不会被 Nginx(默认 60 秒)、AWS ALB、Cloudflare 等空闲代理掐断——服务端每隔 KEEPALIVE_INTERVAL_SECS(默认 5 秒)发送一条 SSE 注释帧 : heartbeat。这是 W3C 规范的注释帧,LangGraph SDK、浏览器 EventSource、httpx-sse 等客户端会静默忽略它。
另一个关键参数是 on_disconnect,控制客户端断开后 run 的命运:
| 取值 | 行为 |
|---|---|
"cancel"(默认) |
客户端断开即取消 run |
"continue" |
run 转入后台继续执行,之后可重连取回结果 |
⚠️ 只有真实的客户端断开会触发自动取消,代理的空闲超时不会。
Agent Protocol v2:线程级 SSE 新协议
最新版 LangGraph JS/Python SDK(包括 Vue/React 的 useStream() 组合式 API)使用更新的流式协议,Aegra 已默认原生支持(环境变量 FF_V2_EVENT_STREAMING 是一键开关,设为 false 可无重启回滚)。
v2 与 v1 最大的区别:流的作用域是线程而非单次 run。客户端在整个会话中只开一条长连接,后续任意 run 的事件都从这一条连接流出:
| 端点 | 作用 |
|---|---|
POST /threads/{thread_id}/stream/events |
打开 SSE 流,按 channels 过滤 |
POST /threads/{thread_id}/commands |
下发 run.start、input.respond 等命令 |
v2 事件按**通道(channel)**组织,客户端在 POST 请求体里订阅:messages、values、updates、tools、lifecycle、input、checkpoints、tasks、custom(还支持 custom:<name> 命名通道,常量见 channels.py)。消息以 content-block 事件序列到达(message-start → content-block-delta → message-finish),生命周期通道报告 started/completed/failed/interrupted。
v2 的断线恢复同样简单:每个事件带自增 seq 序号,重连时把最后看到的 seq 作为 since 传回即可续传。事件封装、序号与通道过滤逻辑集中在 session.py,线协议封装在 protocol.py。
Human-in-the-loop 场景是 v2 的亮点:当订阅 input 通道时,图中的人工中断会作为 input.requested 事件出现;随后发送 input.respond 命令恢复执行——恢复的 run 复用同一条已打开的流,连接全程不关闭。
生产架构:事件如何从 Worker 走到你的浏览器
理解数据流能帮你排查"为什么我的实例收不到事件"。整体链路:
LangGraph 图 → native_stream → Broker(内存/Redis) → session 过滤 → SSE 写入 socket
多实例部署时,请求落在实例 A,但执行 run 的 Worker 可能在实例 B——Worker 把事件 PUBLISH 到 Redis Pub/Sub,实例 A 上的 SSE Broker 订阅并转发给客户端。完整图解见官方指南 worker-architecture.mdx,v2 流式内部管线详见 v2-streaming-architecture.md。
上手建议清单
- 🎯 纯聊天界面:用
messages(或 JS 图用messages-tuple)+ v2 的messages通道; - 📊 带进度条的任务:在节点里
get_stream_writer()推送自定义数据,客户端订阅custom; - 🔌 长任务/移动端:
on_disconnect="continue"+ 断线后用Last-Event-ID/since重连; - 🧪 调试复杂图:叠加
values+debug观察每个节点的完整状态与 checkpoint; - ⚡ 遇到 v2 异常:先检查
FF_V2_EVENT_STREAMING是否为false,以及langgraph版本是否过旧(服务端会返回带升级提示的503)。
掌握这些能力后,你完全可以在零厂商锁定的前提下,自建一个流式体验不输商业平台的 Agent 服务。
