现在我们把前面的 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 创建到任务完成实时输出-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1627.png)
这比把所有能力都塞进一个长连接接口更容易恢复,也更符合后面做持久化、重连和多客户端订阅的需求。
完整 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 这样的命名空间;前后端一起遵守同一份事件合同即可。

















请登录后查看评论内容