题目 1:为什么 Agent 比普通 CRUD API 更需要 Streaming?
请从执行时长、多步骤、用户等待体验和可见性四个角度说明。
普通 CRUD 往往几百毫秒就能返回,用户无需关心内部执行阶段;Agent 则可能运行几十秒甚至数分钟,而且内部有读取文件、调用 Tool、运行测试、错误恢复等多个 Step。若只显示 Loading,用户无法判断任务是否卡住。Streaming 可以持续展示关键进度,让等待过程有反馈,也让用户理解 Agent 正沿着什么路径工作。
题目 2:SSE 最核心的 HTTP 响应类型是什么?event: 与 data: 分别表示什么?
请写出一个最小 progress 事件格式。
SSE 响应通常使用
Content-Type: text/event-stream。event:表示事件类型,例如 progress、failed、completed;data:携带事件数据,常使用 JSON。一个最小事件可以写成:event: progress
data: {“message”:”正在读取项目…”}
题目 3:编程实现——用 Flask 写一个最小 SSE 接口
要求每秒推送一条消息,共三条,最后发送 completed。
import json
import time
from flask import (
Flask,
Response,
)
app = Flask(__name__)
@app.get("/stream")
def stream():
def generate():
messages = [
"正在读取项目",
"正在运行测试",
"正在分析结果",
]
for item in messages:
yield (
"event: progress\n"
"data: "
+ json.dumps(
{
"message": item
},
ensure_ascii=False,
)
+ "\n\n"
)
time.sleep(1)
yield (
"event: completed\n"
"data: "
+ json.dumps(
{
"status": "completed"
},
ensure_ascii=False,
)
+ "\n\n"
)
return Response(
generate(),
mimetype="text/event-stream",
)
if __name__ == "__main__":
app.run(
host="127.0.0.1",
port=5000,
debug=False,
threaded=True,
)
#用 curl -N http://127.0.0.1:5000/stream 可以观察逐条输出。
题目 4:为什么 Streaming Event 不应该直接等于完整 Trace?
请从用户体验、信息量、安全和职责分层四个角度解释。
完整 Trace 可能包含 Prompt、Tool Arguments、原始日志、Traceback、Token 和内部技术信息,体量大且不适合作为用户实时界面。Streaming Event 更应该是产品级摘要,例如“正在运行测试”“发现依赖错误”。Trace 服务工程排查和审计,Streaming 服务用户实时理解。两者可以来自同一个 RunStep,但展示粒度应该不同。
题目 5:Run Status 和 Streaming Progress 有什么区别?
请用一个正在运行 pytest 的任务举例。
Run Status 是粗粒度生命周期状态,例如当前是
running;它并不能说明任务具体正在做什么。Streaming Progress 则可以不断发送“正在执行 pytest”“已完成 20 个测试”“发现 1 个失败”等细粒度信息。用户刷新页面时可以重新 GET Run Status,而页面在线时则通过 Streaming 获得实时进度,两者互补。
题目 6:为什么 SSE 需要 heartbeat?
请说明它与 Agent Step 的区别。
当 Agent 某一步执行很久,例如一个测试命令运行 60 秒,期间没有新的业务事件,中间代理或网络设备可能把长时间空闲连接关闭。heartbeat 可以定期发送轻量保活事件,告诉客户端连接仍然有效。它属于传输层机制,不代表 Agent 完成了一个新的业务 Step,因此不应该增加 RunStep 计数。
题目 7:用户刷新页面后,怎样恢复断线期间的进度?
请结合事件 ID、Last-Event-ID、SQLite 和幂等消费说明。
SSE 连接本身不保存历史,恢复能力来自后端事件日志。服务端把业务事件写入 SQLite 并分配单调递增 ID;浏览器重连时通过
Last-Event-ID告诉服务端最后确认的位置,服务端查询并补发更大的 ID。客户端仍要按 ID 去重,因为断线边界附近的事件可能重复到达。Run 和 RunStep 继续作为最终状态与工程证据,不能只依赖页面当时收到的消息。
题目 8:进度事件流和模型 Token 流有什么区别?
为什么它们不能简单使用完全相同的持久化与消费策略?
进度事件是低频、结构化的任务状态摘要,例如
run.progress;Token 流是高频的回答文本增量,例如token.delta。进度事件适合逐条持久化和断线回放,Token 增量则要考虑合并、缓冲、顺序和慢客户端压力。无论是否流式展示,最终回答都应独立保存;Token 流也不等于公开模型内部推理。
进一步阅读
- Server-Sent Events:理解 Event Stream、自动重连、事件类型和 Last-Event-ID 等机制。
- Flask Streaming:学习 generator response 与 streaming response 的基本方式。
- WebSocket:对比 SSE 单向推送和 WebSocket 双向通信的适用场景。
- HTTP Proxy Buffering:了解为什么反向代理可能影响实时流输出。
- Event Bus:理解 AgentEngine 与 SSE 网络层之间为什么适合通过事件总线解耦。
- Run Observability:后面 Tracing 会把 RunStep 扩展成更加完整的执行证据。
- Frontend EventSource:浏览器端可以用 EventSource 消费 SSE。
- Persistent Event Log:后续 SQLite 会让已经产生的 Step 在刷新和重启后仍然可读取。
术语表
- Streaming:任务执行期间持续向客户端返回增量结果或进度,而不是等待整个任务完成后一次性响应。
- Server-Sent Events(SSE):基于 HTTP 的服务端单向事件推送机制,响应类型通常为
text/event-stream,非常适合 Agent 进度流。 - Progress Event:面向用户或前端展示的进度事件,例如“正在运行测试”“发现 ImportError”,通常比内部 Trace 更简洁。
- Event Stream:一条持续存在的 HTTP 响应流,服务端可以不断写入多个事件,客户端逐条消费。
- Heartbeat:在长时间无业务事件时发送的轻量保活消息,用于维持 SSE 连接,不代表真正 Agent Step。
- Event Bus:Agent Runtime 与网络层之间传递事件的中间组件,让 AgentEngine 不直接依赖 Flask 或 SSE 格式。
- EventSource:浏览器原生提供的 SSE 客户端 API,可持续接收服务端发送的 event/data。
- Streaming Endpoint:专门用于订阅某个 Run 实时事件的 HTTP 接口,例如
/api/v1/runs/{run_id}/events。
本章总结
这一节,我们把 Agent Backend 的用户体验向前推进了一大步。
上一节的 Run 已经让系统知道:
任务有没有开始
现在是否 running
最终 completed 还是 failed
但如果一个 Run 需要几十秒甚至几分钟,用户仍然会面对一个问题:
我知道它在 running,
但它到底在干什么?
所以我们引入,Streaming。
本节选择:
Server-Sent Events
因为当前需求主要是:
Server
↓
持续推送 Agent 进度
↓
Client
属于典型单向事件流。
我们实现了最基础 SSE 格式:
event: progress
data: {...}
并通过 Flask generator:
yield ...
持续发送事件。
之后又把它和 Run 真正串起来:
Agent Run
↓
RunStep
↓
Progress Event
↓
EventBus
↓
SSE
↓
Frontend
这条链路非常重要。
因为 Streaming 不应该单独维护一套“假进度”。
真正好的设计是,Agent Runtime 产生真实 Step,Streaming 只是把其中适合用户看的部分实时传出去。
我们还明确区分:
Run
Streaming
Trace
Run 负责:
任务生命周期
Streaming 负责:
实时反馈
Trace 负责:
完整技术证据
所以前端可以看到:
正在读取项目
发现 app.py
正在运行测试
发现 ImportError
正在检查依赖
但不需要看到:
完整 Prompt
完整 Tool Schema
完整 traceback
完整内部日志
这是产品层和工程层非常重要的边界。
本节还实现了:
GET /api/v1/runs/{run_id}/events
教学 Demo 通过内存 Event Queue 加线程模拟后台 Agent 执行;配套项目则进一步使用 SQLite 事件日志、独立游标、heartbeat 和 Last-Event-ID,支持历史补发与持续订阅。
现在我们已经真正做到:
POST /runs
↓
创建任务
GET /runs/{run_id}/events
↓
实时查看进度
GET /runs/{run_id}
↓
查询最终状态
这是一个非常像真实 Agent Backend 的形态。
如果你要验证自己是否真的掌握本章,可以做一个最直接的实验:
创建一个 10 秒任务。
让它每两秒产生一个事件:
正在读取项目
正在运行测试
发现错误
正在重试
任务完成
然后用:
观察是不是逐条出现。
如果不是等 10 秒以后一次性全部出现,就说明你的 Streaming 链路真正打通了。
下一节,我们会把配套项目里已经出现的持久化思路完整拆开:如果 Session、Run、Step 只存在 Python 内存里,服务一重启,它们就会全部消失。
所以接下来我们会进入,数据持久化:SQLite 保存 Session、Run 和 Trace。
从下一节开始,Agent Backend 就不再是“进程活着才有记忆”,而会真正拥有可恢复的数据层。
















请登录后查看评论内容