Agent SSE 可恢复流：后端别把长连接当任务生命周期

Tue, 12 May 2026 00:00:00 +0000

做 Agent 聊天时，最开始很容易把 SSE 当成一条“任务管道”。

用户点发送，后端开一个流，Agent 一边跑一边往这个 HTTP response 里写数据。浏览器断开，就认为用户不需要了，于是顺手把后台任务也取消。

这套在 demo 里很顺。但一到长任务就会暴露问题。

生成视频、跑工作流、调图像模型，可能要几十秒甚至几分钟。用户网络抖一下、页面切后台、代理断一下，SSE 连接断了。但 Agent 任务本身不应该死。

真正要拆开的，是两件事：

Agent run：后台任务生命周期
SSE connection：前端订阅事件的传输连接

连接可以断，可以重连。run 不能因为连接断了就被杀。

架构图

flowchart LR
  FE["Frontend<br/>sendMessage / resumeActiveRun<br/>POST /v1/agent/runs<br/>fetch-event-source 订阅 events<br/>最近 500 个 SSE id 去重"]
  API["Agent API<br/>POST /runs 创建 run<br/>GET /runs/{run_id}/events 订阅<br/>cancel / HITL<br/>active-run 只用于页面恢复"]
  Producer["Background Agent Producer<br/>执行 Agent run<br/>写 Redis Stream 事件<br/>刷新 runner lease<br/>最终历史写 MongoDB"]
  Redis["Redis Runtime Layer<br/>Stream per run<br/>id + event + data<br/>active run state<br/>runner lease TTL"]
  SSE["SSE Events Endpoint<br/>读取 Last-Event-ID header<br/>XREAD Redis Stream<br/>输出标准 SSE<br/>heartbeat comment"]
  Mongo["MongoDB Final History<br/>完整聊天历史<br/>最终一致性持久化"]

  FE -->|"create run / 409 active_run_id"| API
  API -->|"start background task"| Producer
  Producer -->|"XADD event"| Redis
  SSE -->|"XREAD from cursor"| Redis
  FE -.->|"SSE reconnect with Last-Event-ID"| SSE
  SSE -.->|"id / event / data"| FE
  Producer -->|"final messages"| Mongo
  SSE -.->|"closes only on run.completed / run.failed / run.cancelled"| FE

这个图里最重要的箭头不是 SSE，而是 Producer -> Redis。

SSE on niuzj

Agent SSE 可恢复流：后端别把长连接当任务生命周期

架构图