小节四:实现真正的 Flask SSE Agent Streaming——从 Run 创建到任务完成实时输出

现在我们把前面的 Run 和 Streaming 串起来。

我们实现:

GET /api/v1/runs/{run_id}/events

这个接口负责,订阅某个 Run 的实时事件。

为什么不直接用:

POST /runs

响应流?

也可以。

但拆成:

POST /runs
GET /runs/{run_id}/events

更容易让:

Run 创建
状态查询
事件订阅

分别清晰。

拆开以后,三个接口的职责也更容易理解:创建 Run、订阅事件、查询状态可以独立演进。实时连接断了,不影响 Run 继续执行;页面刷新以后,也可以重新查询状态,再重新订阅事件。

图片[1]-小节四:实现真正的 Flask SSE Agent Streaming——从 Run 创建到任务完成实时输出-大赛人网

这比把所有能力都塞进一个长连接接口更容易恢复,也更符合后面做持久化、重连和多客户端订阅的需求。

完整 Demo

下面代码使用线程模拟 Agent 后台执行。为了先把“创建 Run—后台执行—持续推送”这条链路看清,它暂时给每个 Run 放一个内存队列,适合本机、单进程、单订阅者的教学实验。

这里要先把边界说透:queue.Queue 是竞争消费,一个客户端取走事件后,另一个客户端就拿不到同一条事件;页面刷新也无法补回已经取走的内容。因此它不是后面项目的最终存储结构。完整配套项目会改用 SQLite 事件日志和每个客户端自己的游标,演示代码的重点只是 SSE 主链路。

使用方法

先创建 Run:

curl -X POST \
  http://127.0.0.1:5000/api/v1/runs \
  -H "Content-Type: application/json" \
  -d '{"message":"检查这个 Python 项目"}'

得到:

{
  "run_id": "run_xxx",
  "status": "ready",
  "events_url": "/api/v1/runs/run_xxx/events"
}

再订阅:

curl -N \
  http://127.0.0.1:5000/api/v1/runs/run_xxx/events

你会实时看到:

event: progress
data: {"message":"正在读取项目..."}

event: progress
data: {"message":"发现 app.py..."}

event: completed
data: {"status":"completed", ...}

这就是第一个真正能“看到 Agent 工作过程”的 Backend。

浏览器如何消费 SSE

浏览器自带 EventSource,不需要额外安装库。我们的接口使用命名事件,因此要用 addEventListener() 监听对应类型

const source = new EventSource(
  `/api/v1/runs/${runId}/events`
);

let lastRenderedId = 0;

function handleProgress(event) {
  const eventId = Number(event.lastEventId || 0);

  if (eventId && eventId <= lastRenderedId) {
    return;
  }

  const payload = JSON.parse(event.data);
  renderProgress(payload);

  if (eventId) {
    lastRenderedId = eventId;
  }
}

source.addEventListener(
  "progress",
  handleProgress,
);

source.addEventListener(
  "completed",
  (event) => {
    renderResult(JSON.parse(event.data));
    source.close();
  },
);

source.addEventListener(
  "error",
  () => {
    renderConnectionState("正在重连");
  },
);

只设置 source.onmessage 容易踩坑:它主要接收没有自定义 event: 名称的 message 事件;服务端发送 event: progress 后,应监听 progress。终态到达时主动 close(),也能避免浏览器把一次正常结束误当成需要永久重连。

业务失败事件也尽量不要直接命名为 error。EventSource 本身会用 error 表示连接异常,两种含义混在一起后,前端很难判断应该展示任务失败,还是继续等待自动重连。稳定接口用 run.failed 会更清楚。

原生 EventSource 还有一个现实限制:它不能像普通 fetch 那样随意设置 Authorization 请求头。站内应用常用同源 Cookie;跨系统场景可以使用短期签名 URL,或改用支持流式读取的 fetch 客户端。不要把长期密钥直接塞进查询字符串,URL 很可能出现在日志和浏览器历史里。

上面的教学 Demo 使用短事件名 progress、completed。当接口进入稳定版本,可以统一升级为 run.progress、run.completed 这样的命名空间;前后端一起遵守同一份事件合同即可。

© 版权声明
THE END
喜欢就支持一下吧
点赞11 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容