章末自测

题目 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 就不再是“进程活着才有记忆”,而会真正拥有可恢复的数据层。

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

昵称

取消
昵称

    请登录后查看评论内容