知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# Agent 流式交互与实时反馈设计 > 导读:本文从"用户盯着空白屏幕等 8 秒,以为系统挂了,反复点提交把服务压垮"这个典型体验事故出发,把流式事件体系、SSE 与 WebSocket 选型、进度与 ETA 估算、取消链路与 Checkpoint 联动、工具调用流式、后端 async generator 实现与前端 UX 模式逐项讲透,最后给出工程实践与踩坑。适合正在做 Agent 交互层、或准备 Agent 系统设计面试的同学。 ## 一、先建立全局认知 ### Q:为什么 Agent 比普通 Chat 更需要流式? A:结论先行——因为 Agent 的执行链路比 Chat 长 3~10 倍,但**用户对"等待"的容忍度没变**;流式是弥合这个鸿沟的唯一手段。  *图:Chat 2 秒可接受;Agent 8 秒无流式反馈,易被误认为死机* ```text 普通 Chat 的延迟感知: [用户输入] ────2秒──── [完整回答] 用户体验:可以接受,2秒不长 Agent 的延迟感知: [用户输入] ──1秒──[思考]──3秒──[查数据库]──1秒──[再思考]──2秒──[调API]──1秒──[生成答案] 总耗时:8秒 用户体验:没有流式反馈 → 盯着空白屏 8 秒 → 极度焦虑,误以为死机 ``` 所以 Agent 流式的定义要放宽:它不只是"文字逐字输出",而是一个完整的**实时状态透明化体系**——目标是**让用户在 Agent 执行过程中的每一刻都知道它在做什么、为什么这样做、进展如何、何时完成**。  *图:Agent 流式交互与实时反馈* ### Q:流式带来的三个核心价值是什么? A:结论先行——**可见性(Visibility)、可控性(Control)、体验(Experience)**。 | 价值 | 说明 | 没有流式的后果 | |---|---|---| | 可见性 | 用户实时看到 Agent 的思考链路 | 黑箱执行,用户不信任输出 | | 可控性 | 用户看到中间步骤后可提前取消 | 方向错误也要等全部跑完,浪费 token/时间 | | 体验 | 渐进式内容呈现降低心理等待感 | 8 秒空白屏幕,用户焦虑/离开 | ### Q:为什么说流式不只是 UX 问题,还是成本问题? A:结论先行——因为**提前取消能省掉绝大部分成本**:Agent 每多跑一步就是真金白银。  *图:一次 Run 成本 ¥0.028,提前取消省 82%* ```text 一次完整的 Agent Run: 思考步骤 500 tokens → ¥0.005 工具调用(搜索) → ¥0.01 再思考 300 tokens → ¥0.003 工具调用(计算) → ¥0.002 最终回答 800 tokens → ¥0.008 总计:¥0.028 如果用户在第一步思考时就发现方向错误并取消: 实际花费 ¥0.005(节省 ¥0.023,约 82%) ``` 关键点解读:这个成本数字(具体金额因模型定价而异,需按实际计费确认)支撑了一个重要结论——**"取消"不是体验功能的附属品,而是成本控制的核心手段**。如果用户看不见中间过程,他就没有机会在第一步就喊停。 ## 二、流式事件体系:该流什么 ### Q:Agent 的流式内容到底包含哪些? A:结论先行——不是一个 `text` 流,而是**多类型事件流**,分四类:**元事件(Meta)、内容事件(Content)、进度事件(Progress)、错误/警告事件**。  *图:Agent SSE 事件按用途分为元事件、内容事件、进度与错误事件* ```text ┌─────────────────┬─────────────────┬─────────────────┐ │ 元事件 Meta │ 内容事件 │ 进度事件 │ │ run.started │ llm.thought │ progress.step │ │ run.completed │ llm.token │ progress.time │ │ run.error │ tool.call │ progress.eta │ │ run.cancelled │ tool.result │ │ │ │ step.start │ 错误/警告事件 │ │ │ step.complete │ warning │ │ │ answer.start │ error │ │ │ answer.token │ │ │ │ answer.complete│ │ └─────────────────┴─────────────────┴─────────────────┘ ``` 事件 Schema 的字段设计有四个必须一致的约定(以 `tool.result` 与 `progress` 为例): ```json { "tool.result": { "event": "tool.result", "data": { "run_id": "run_abc123", "step_number": 3, "tool_call_id": "tc_456", "status": "success|error|timeout", "result_preview": "Q2营收: 150亿, 利润: 22亿...", "full_result_available": true, "duration_ms": 1150, "timestamp": "2026-08-10T10:00:06.150Z" } }, "progress": { "event": "progress", "data": { "run_id": "run_abc123", "current_step": 3, "total_steps": 6, "completed_subtasks": 2, "total_subtasks": 5, "elapsed_ms": 5200, "estimated_remaining_ms": 4800, "progress_percentage": 50.0 } }, "run.error": { "event": "run.error", "data": { "run_id": "run_abc123", "error_code": "MAX_STEPS_EXCEEDED", "message": "Agent 已达到最大执行步数(20步),已保存检查点", "checkpoint_id": "cp_789", "recoverable": true } } } ``` 关键点解读:`tool.result` 里的 `result_preview` + `full_result_available` + `tool_call_id` 是"**预览 + 按需拉全量**"的经典组合;而 `run.error` 里的 `checkpoint_id` + `recoverable` 把"错误"从"结束"变成了"**可恢复的中断**"——这是 Agent 与普通 Chat 流式在语义上的关键差别。  *图:流式事件分类* ### Q:事件设计有哪些原则? A:结论先行——四条:**每个事件独立可消费、轻量 payload、事件自带时序、分层流量控制**。 1. **每个事件独立可消费**:客户端不需要保存完整状态机也能理解当前事件的含义; 2. **轻量 payload**:工具结果只发 preview(示例取前 200 字符),完整内容客户端按需拉取; 3. **事件自带时序**:每条事件带 `timestamp`,前端可做时间线可视化; 4. **分层流量控制**:`llm.token` 高频(约每 50ms 一个 token)、`progress` 中频(每秒)、`step.*` 低频(每步一次)。 关键点解读:第 4 条是"**把不同频率的事件分开设计**"的意识。如果所有事件都按 token 级频率推送,前端渲染和网络都会被打爆;如果所有事件都按 step 级推送,用户又感受不到"活的"反馈。 ## 三、流式传输协议选型 ### Q:SSE 还是 WebSocket? A:结论先行——**Agent 流式首选 SSE**,因为它的流量本质是"服务端持续推送、客户端偶尔发取消指令",不需要全双工。 | 维度 | SSE | WebSocket | |---|---|---| | 方向 | 单向:服务端 → 客户端 | 双向:全双工 | | 协议 | HTTP/1.1 长连接,标准 `text/event-stream` | 独立 `ws://`,需升级握手 | | 浏览器支持 | 原生 `EventSource`,自动重连 | 原生 API,需手动重连 | | 代理/CDN | 大部分 HTTP 代理直接透传 | 部分代理不支持 WS 升级 | | 断线重连 | 内置自动重连 + `Last-Event-Id` | 需自行实现 | | 负载均衡 | 标准 HTTP LB 友好 | 需要 sticky session 或专用 LB | | 适用场景 | 服务端推送数据流(监控、日志、AI 流式) | 双向实时通信(聊天、游戏、协作) | 取消指令用**一个独立的 HTTP POST 请求**(`POST /runs/{run_id}/cancel`)即可,不需要全双工连接。WebSocket 只在以下场景才考虑: - 客户端需要**高频**发送中间反馈(如人对 Agent 中间步骤做实时评价); - 需要真正的**双向流**(如语音 Agent,用户边说话 Agent 边响应); - 企业内部网络,没有代理/CDN 兼容性问题。 ### Q:SSE 落地最容易踩的坑是什么? A:结论先行——**代理缓冲**:Nginx 默认开启 `proxy_buffering`,会把 SSE 变成"攒够了再一次性下发",流式直接失效。 ```nginx location /api/agents/runs/ { proxy_pass http://agent_backend; proxy_http_version 1.1; proxy_set_header Connection ''; proxy_buffering off; # ← 必须关闭,否则 SSE 变批量推送 proxy_cache off; proxy_read_timeout 600s; # Agent 可能执行很久 proxy_send_timeout 600s; chunked_transfer_encoding on; } ``` 服务端也要配合加响应头: ```text HTTP/1.1 200 OK Content-Type: text/event-stream Cache-Control: no-cache Connection: keep-alive X-Accel-Buffering: no # 禁用 Nginx 缓冲(关键!) event: run.started id: 1 data: {"run_id":"run_abc123","agent_name":"research-agent"} event: llm.thought id: 2 data: {"run_id":"run_abc123","step_number":1,"content":"我需要先理解用户的问题..."} ``` SSE 的四个关键字段: | 字段 | 含义 | Agent 流式中的用法 | |---|---|---| | `event:` | 事件类型 | 对应 `run.started`、`llm.thought`、`tool.call` 等 | | `id:` | 事件序号 | 全局递增,用于断线重连 `Last-Event-Id` | | `data:` | JSON payload | 各事件的数据体,**必须是单行 JSON**(或用 `\n` 换行) | | `retry:` | 重连间隔(ms) | 建议 3000ms,Agent 执行中不宜太激进 | ### Q:中间代理还有哪些兼容性坑? A:结论先行——四类:**流被缓冲、连接被空闲超时断开、CDN 缓存 SSE 响应、HTTP/2 下被多路复用打断**。 | 问题 | 原因 | 解决方案 | |---|---|---| | 流被缓冲,前端只收到完整响应 | Nginx `proxy_buffering on` | 设置 `proxy_buffering off` | | SSE 连接被中间代理断开 | 代理空闲超时(常见 60s) | 每 30s 发送 heartbeat comment `: heartbeat\n\n` | | CDN 缓存 SSE 响应 | CDN 默认缓存 GET 请求 | 设置 `Cache-Control: no-cache` | | HTTP/2 下 SSE 被多路复用打断 | HTTP/2 连接管理差异 | Nginx 设置 `proxy_http_version 1.1` 走 HTTP/1.1 | ### Q:断线重连怎么做?为什么 Agent 场景更麻烦? A:结论先行——`EventSource` 自带重连(会带上 `Last-Event-Id`),但 Agent 场景的特殊性在于**重连时 Run 可能还在跑、也可能已经结束**,两种情况的处理完全不同。 ```text 场景:Agent 已执行到 step 5,SSE 断开 15 秒后重连。 客户端做法: 1. 记录最后收到的 event id(如 id=42) 2. 重连时自动带上 Last-Event-Id: 42 3. 后端根据 event id 判断: - 该 run 仍在执行 → 从 id=42 之后的事件开始补推 - 该 run 已经结束 → 返回 run.completed(客户端拉取完整结果) ``` 服务端靠一个有界的事件缓冲区实现补推: ```python class EventBuffer: """服务端事件缓冲区:保留最近 N 条事件用于重连回放""" def __init__(self, max_size: int = 500): self.events: list[tuple[int, str, dict]] = [] # (id, event, data) self.max_size = max_size def append(self, event_id: int, event_type: str, data: dict): self.events.append((event_id, event_type, data)) if len(self.events) > self.max_size: self.events = self.events[-self.max_size:] # 有界,防内存膨胀 def get_since(self, last_event_id: int) -> list[tuple[int, str, dict]]: return [(eid, evt, data) for eid, evt, data in self.events if eid > last_event_id] ``` 关键点解读:**缓冲区必须"有界"**。这是个容易被忽视的取舍——理论上为了支持任意时长的重连,缓冲区越大越好;但实际上一个高频 token 流的 Run 可能产生上万条事件,无界缓冲会直接吃掉内存。所以取 `max_size`(示例 500~1000 条),并接受"超出窗口的旧事件无法回放"这个代价。 ## 四、流式架构:直接流还是发布订阅 ### Q:Agent 引擎和 API 网关之间怎么连? A:结论先行——**方案 A(Agent 直接产出 SSE 事件)为主**:简单、低延迟、无需中间件;**方案 B(经 Redis Pub/Sub 中转)作为企业级扩展**。 ```text 方案 A:Agent 直接产出 SSE 事件(推荐) Agent 引擎通过 async generator 直接产出事件, API 层把 generator 桥接到 SSE StreamingResponse。 优点:简单、低延迟、无需中间件 缺点:Agent 进程与 HTTP 连接绑定,进程重启 → SSE 断开 方案 B:Agent → Redis Pub/Sub → API 网关 → 客户端 Agent 引擎发布事件到 Redis Channel,网关订阅后转发(可多客户端) 优点:解耦,支持多客户端同时监听同一个 Run 缺点:增加一跳延迟(约 2~10ms),架构复杂度上升 ```  *图:流式交互架构——SSE 下发、取消回传与事件总线* ```text ┌──────────┐ SSE (HTTP) ┌──────────────┐ Async Gen ┌──────────────┐ │ 前端 │ ◄───────────── │ API 网关 │ ◄────────── │ Agent 引擎 │ │ (浏览器) │ │ (FastAPI) │ │ ReAct Loop │ │ │ POST /cancel │ │ │ │ │ │ ─────────────► │ │ │ │ └──────────┘ └──────┬───────┘ └──────┬───────┘ │ │ ┌─────▼──────┐ ┌──────▼───────┐ │ Redis │ │ LLM Provider │ │ (Pub/Sub) │ │ (OpenAI 等) │ │ (可选) │ └──────────────┘ └────────────┘ ``` 关键点解读:**方案 A 的缺点(进程重启 → SSE 断开)不是致命的**,因为它刚好被"断线重连 + Checkpoint 恢复"这套机制接住了:连接断了不影响 Agent Run 的状态,用户重连后可以补推或拉最终结果。**"连接"和"执行"解耦,是流式 Agent 设计的关键抽象。**  *图:SSE 流式架构* ## 五、进度反馈设计 ### Q:进度百分比怎么算?Agent 根本没有"总工作量"。 A:结论先行——用**多维度加权启发式估算**:Plan-and-Execute 型按子任务完成比例,ReAct 型退化为步数比例,两者加权。 ```python def estimate_progress(agent_state: dict) -> float: """ 多维度加权估算进度。权重可根据 Agent 类型和实际运行数据调优。 """ if agent_state.get("total_subtasks", 0) > 0: # Plan-and-Execute 模式:按子任务完成比例 subtask_weight = 0.6 subtask_progress = agent_state["completed_subtasks"] / agent_state["total_subtasks"] else: # ReAct 模式:无子任务划分,退化为步数比例 subtask_weight = 0.3 subtask_progress = 0 # 步数进度(ReAct Agent 核心指标) step_weight = 1.0 - subtask_weight step_progress = min(agent_state["current_step"] / agent_state["max_steps"], 1.0) progress = subtask_weight * subtask_progress + step_weight * step_progress return round(progress * 100, 1) ``` 关键点解读:这里最关键的设计是**`subtask_weight` 随形态切换**——有子任务时权重 0.6(子任务是更可信的进度信号),没有子任务时降到 0.3(只剩步数可依赖)。同时 `min(..., 1.0)` 的封顶很重要:ReAct 的实际步数**可能超过预估的 max_steps**(例如模型临时决定多验证一步),不封顶就会出现"进度 120%"这种穿帮。 ### Q:ETA(预估剩余时间)怎么算才不离谱? A:结论先行——用**滑动窗口的近期步均耗时 × 剩余步数 × 冗余系数**,并且窗口要小(示例 5),避免早期慢步拖累后期估算。 ```python class ETAEstimator: """基于滑动窗口的 Agent 执行时间预估器""" def __init__(self, window_size: int = 5): self.step_durations: deque = deque(maxlen=window_size) def record_step(self, duration_ms: float): self.step_durations.append(duration_ms) def estimate_remaining(self, remaining_steps: int) -> float: if len(self.step_durations) == 0: return remaining_steps * 2000 # 冷启动默认每步 2s avg_duration = sum(self.step_durations) / len(self.step_durations) return avg_duration * remaining_steps * 1.1 # 加 10% 缓冲 ``` 关键点解读:**用滑动窗口而不是全量平均**,是因为 Agent 各步耗时差异极大(思考步 1 秒、搜索步 3 秒);如果从第 1 步就开始全量平均,一个慢步会长期把 ETA 拉高。`deque(maxlen=5)` 让估算"只反映最近状态"。至于 +10% 缓冲:**ETA 宁可略偏保守也不要偏乐观**——显示"还剩 5 秒"然后拖到 20 秒,比直接显示"还剩 15 秒"体验更差。 ### Q:进度事件会不会推得太频繁? A:结论先行——会,所以要用**"变化阈值 + 最小间隔 + 心跳兜底"三重节流**。 ```python class ProgressThrottle: """进度事件节流器:避免高频推送完全相同的进度数据""" def __init__(self, min_interval_ms: int = 1000): self.last_emit_time = 0 self.min_interval_ms = min_interval_ms self.last_progress_pct: float | None = None def should_emit(self, progress_pct: float) -> bool: now = time.time() * 1000 # 进度变化超过 5% 且距上次发送 >= min_interval if self.last_progress_pct is None or abs(progress_pct - self.last_progress_pct) >= 5: if now - self.last_emit_time >= self.min_interval_ms: self.last_emit_time = now self.last_progress_pct = progress_pct return True # 即使进度没变,每隔 5 秒也发一次(心跳性质) if now - self.last_emit_time >= 5000: self.last_emit_time = now return True return False ``` 关键点解读:第三条"**即使没变化也每 5 秒发一次**"看着冗余,其实是体验刚需——用户看到"45%,已用时 8s"长时间不刷新,会怀疑卡死。**"进度没变"本身也是需要被传达的信息。** 与之对比,`llm.token` **不做合并节流**,因为它本来就是要保持实时性。 ## 六、流中断与取消机制 ### Q:一次完整的取消,链路是怎样的? A:结论先行——**前端 POST cancel → 后端收到取消信号 → 中断 LLM 调用 → 停止工具队列 → 保存 Checkpoint → 发 run.cancelled → 关闭 SSE**。  *图:取消执行链路:前端 POST 到关闭 SSE 流* ```text 用户点击 [取消] → 前端 POST /runs/{run_id}/cancel → 后端 Agent 引擎收到取消信号 → 停止当前 LLM 调用(abort) → 停止工具调用队列 → 保存 Checkpoint(关键!) → 发送 run.cancelled 事件 → 关闭 SSE 流 ``` 实现上用"取消令牌"贯穿整个生命周期: ```python class CancellationToken: """Agent 执行取消令牌——贯穿整个 Agent 生命周期""" def __init__(self): self._cancelled = asyncio.Event() self._cancel_reason: str | None = None def cancel(self, reason: str = "user_requested"): self._cancel_reason = reason self._cancelled.set() @property def is_cancelled(self) -> bool: return self._cancelled.is_set() async def wait_if_not_cancelled(self, timeout: float | None = None): """等待指定时间,除非被取消""" try: await asyncio.wait_for(self._cancelled.wait(), timeout=timeout) raise CancelledError(self._cancel_reason or "cancelled") except asyncio.TimeoutError: pass # 超时是正常的,继续执行 ``` 关键点解读:**取消点必须散布在循环的每个关键位置**(每步开始、LLM 流式 chunk 之间、每个工具调用前),而不是只在循环头检查一次。因为一个 LLM 调用可能持续 10 秒,只在循环头检查意味着"用户点了取消还要等 10 秒才生效",体验上和没做差不多。  *图:流式取消链路* ### Q:取消时 Checkpoint 怎么处理? A:结论先行——**按取消时机分三种策略**:本轮 step 未完成存 partial、工具 pending 存 partial 并记 `tool_call_id`、step 完整闭环存 committed。 | 取消时机 | Agent 状态 | Checkpoint 策略 | |---|---|---| | LLM 思考中 | 本轮 step 未完成 | 不保存完整 step,保存 partial emergency checkpoint | | 工具调用已发出、等待返回 | pending tool call | 记录 tool_call_id,保存 partial snapshot | | 工具调用已返回、准备下一步 | step 完整闭环 | 保存完整 committed checkpoint | ```python async def handle_cancellation(agent: "AgentRunner", reason: str): """取消处理核心逻辑""" agent.cancel_token.cancel(reason) # 中断正在进行的 LLM 调用 if agent.current_llm_task and not agent.current_llm_task.done(): agent.current_llm_task.cancel() # 根据当前状态决定 checkpoint 策略 if agent.state.step_completed: checkpoint = agent.create_committed_checkpoint() # 完整快照 else: checkpoint = agent.create_partial_checkpoint(reason) # 应急快照 await agent.checkpoint_store.save(checkpoint) # 发送取消事件到 SSE 流 await agent.event_queue.put({ "event": "run.cancelled", "data": { "run_id": agent.run_id, "reason": reason, "checkpoint_id": checkpoint.checkpoint_id, "can_resume": True, }, }) ``` 关键点解读:取消时必须区分 **committed / partial** 两种快照(这也串联了 Checkpoint 设计里"partial 快照不能直接 resume"的约束)。事件里回传 `checkpoint_id` 与 `can_resume`,前端才能给出"从断点恢复"的入口。 ### Q:前端取消按钮的体验应该怎么设计? A:结论先行——**按钮有明确的状态流转,并给出可恢复的出口**。  *图:取消按钮四态:思考、可取消、取消中、已取消* ```text [Loading 动画] "Agent 正在思考..." │ ▼ [取消按钮] "取消执行" ← 用户随时可点击 │ (点击后) ▼ [取消中...] "正在安全中断..." ← 按钮 disable,显示过渡状态 │ ▼ [已取消] "执行已中断,已保存进度。可恢复或重新开始。" │ ┌────┴────┐ ▼ ▼ [重新开始] [从断点恢复] ``` 关键点解读:**"取消中"这个过渡态不可省**。因为后端需要时间做"等工具调用收尾 + 写 Checkpoint",如果前端点完就直接跳到"已取消",用户可能立刻点"重新开始",而此时旧 Run 还在收尾——两个 Run 并发操作同一份状态,很容易出问题。 ## 七、工具调用流式 ### Q:为什么工具调用是流式体验最容易出问题的环节? A:结论先行——因为**用户在等工具返回时看不到任何输出,会以为 Agent 卡住了**;必须用"工具调用事件 + 周期性进度 + 计时器"三件套占住这个空窗期。  *图:工具调用三阶段的流式事件与前端提示文案* ```text 阶段1:工具选择(Tool Selection) → 流式事件: tool.call → 前端展示: "🔧 正在调用 search_financial_reports..." → 参数展示: {"query": "Q2财报", "source": "public"} 阶段2:工具执行(Tool Execution) → 流式事件: 无(可通过 progress 暗示在等待) → 前端展示: "⏳ 等待搜索结果..." + 已等待时间计时器 → 超时处理: 超过 N 秒 → 发 warning 事件 阶段3:结果返回(Tool Result) → 流式事件: tool.result → 前端展示: "✅ 获取到 3 条结果" + 缩略内容 ``` 关键点解读:**阶段 2 的"已等待时间计时器"是纯前端行为**(前端每秒自己累加),但阶段 2 的 `progress` 事件是后端发的。这种"前端计时 + 后端确认"的组合,能保证即使后端事件延迟,用户视野里的计时器仍在动。 ### Q:工具返回大数据怎么办?总不能全塞进 SSE。 A:结论先行——**小结果直接发,大结果只发 preview + 引用 URL**,前端按需拉取。 ```python async def stream_tool_result(tool_call_id: str, result: dict, event_queue, max_preview_chars: int = 200): """小结果直接发完整内容,大结果只发预览 + 引用""" result_str = json.dumps(result, ensure_ascii=False) if len(result_str) <= max_preview_chars: preview, needs_full_fetch = result_str, False else: preview, needs_full_fetch = result_str[:max_preview_chars] + "...", True await event_queue.put({ "event": "tool.result", "data": { "tool_call_id": tool_call_id, "status": "success", "result_preview": preview, "result_size_chars": len(result_str), "full_result_available": not needs_full_fetch, "full_result_url": (f"/runs/{run_id}/tools/{tool_call_id}/result" if needs_full_fetch else None), }, }) ``` 关键点解读:**同时给出 `result_size_chars`(大小)与 `full_result_url`(入口)**,让前端可以决定是"显示省略号"还是"提供一个查看完整结果的链接"。如果只发 preview 不给入口,用户就会怀疑"是不是偷偷丢数据了"。 ## 八、后端实现 ### Q:后端实现的核心抽象是什么? A:结论先行——**`async generator` 管道**:Agent 执行循环 `yield` 事件 → EventTransformer 格式化为 SSE 字符串 → FastAPI `StreamingResponse` → 前端 `EventSource`。  *图:事件经 SSE 从 Agent 循环流到前端 EventSource* ```text Agent 执行循环(async generator) │ ▼ yield event ────► EventTransformer(格式化为 SSE 字符串) │ ▼ FastAPI StreamingResponse │ ▼ HTTP SSE ──────────────► 前端 EventSource ``` SSE 端点要处理三件特殊事:**心跳、客户端断开检测、终止事件收尾**。 ```python @app.get("/runs/{run_id}/stream") async def stream_run(run_id: str, request: Request): event_queue = agent_engine.get_event_queue(run_id) if event_queue is None: raise HTTPException(status_code=404, detail="Run not found") async def event_generator(): event_id = 0 heartbeat_interval = 30 # 秒 try: while True: try: event = await asyncio.wait_for(event_queue.get(), timeout=heartbeat_interval) except asyncio.TimeoutError: yield ": heartbeat\n\n" # SSE comment 作为心跳 continue event_id += 1 yield f"id: {event_id}\n" yield f"event: {event['event']}\n" yield f"data: {json.dumps(event['data'], ensure_ascii=False)}\n\n" if event["event"] in ("run.completed", "run.error", "run.cancelled"): break # 终止事件 → 关闭流 except asyncio.CancelledError: pass finally: if await request.is_disconnected(): agent_engine.notify_client_disconnected(run_id) return StreamingResponse( event_generator(), media_type="text/event-stream", headers={ "Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no", # 禁用 Nginx 缓冲 "Access-Control-Allow-Origin": "*", }, ) ``` 关键点解读:**用 `asyncio.wait_for(queue.get(), timeout=30)` 实现"有事件就发、没事件就发心跳"**,而不是额外起一个心跳协程——这样代码路径单一、不会出现"心跳和事件并发写同一个流"的乱序问题。 ### Q:事件生命周期用什么组件管理? A:结论先行——用一个 `AgentStreamController` 集中管理:**事件队列 + 取消令牌 + 进度追踪 + ETA 估算 + 事件回溯缓冲**,并提供一组 `emit_*` 便捷方法。 ```python class AgentStreamController: """ Agent 流式控制器——管理整个 Agent Run 的流式事件生命周期。 职责:持有事件队列、提供事件发送方法、管理取消令牌、 管理进度追踪、支持事件回溯(replay) """ def __init__(self, run_id: str, max_event_buffer: int = 1000): self.run_id = run_id self.event_queue: asyncio.Queue = asyncio.Queue() self.cancel_token = CancellationToken() self._event_buffer: list[tuple[int, str, dict]] = [] self._event_counter = 0 self._max_buffer = max_event_buffer # 进度追踪 self._current_step = 0 self._max_steps = 0 self._completed_subtasks = 0 self._total_subtasks = 0 self._eta_estimator = ETAEstimator() self._progress_throttle = ProgressThrottle() async def _push(self, event_type: str, data: dict): """将事件推入队列 + 写入回溯缓冲区""" self._event_counter += 1 event_id = self._event_counter self._event_buffer.append((event_id, event_type, data)) if len(self._event_buffer) > self._max_buffer: self._event_buffer = self._event_buffer[-self._max_buffer:] await self.event_queue.put({"event": event_type, "data": data}) def get_events_since(self, last_event_id: int) -> list[dict]: """获取指定 ID 之后的所有事件(用于重连回溯)""" return [{"event": evt, "data": data} for eid, evt, data in self._event_buffer if eid > last_event_id] ``` 对外提供的 `emit_*` 方法覆盖全部事件类型:`emit_run_started` / `emit_run_completed` / `emit_run_error` / `emit_run_cancelled` / `emit_step_start` / `emit_step_complete` / `emit_llm_thought` / `emit_llm_token` / `emit_tool_call` / `emit_tool_result` / `emit_answer_start` / `emit_answer_token` / `emit_answer_complete` / `emit_warning`。 关键点解读:`emit_llm_token` 的注释写得很明确——"**Token 级流式高频调用(每 50ms 左右),不做事件缓冲合并,保持实时性**"。这与 `progress` 的节流形成对比:**不是所有事件都要节流,高频且对实时性敏感的 token 事件恰恰不能合并**(合并会破坏"逐字输出"的观感)。 ### Q:Agent 主循环里怎么嵌入事件发射? A:结论先行——**在 ReAct 循环的每个关键节点发射对应事件**:步骤开始发 `step.start`、LLM 流式逐 chunk 发 `llm.token`、工具前后发 `tool.call`/`tool.result`、步骤结束发 `step.complete`,最后发 `answer.*` 与 `run.completed`。 ```python async def run(self, user_input: str, max_steps: int = 20): cancel = self.stream.cancel_token await self.stream.emit_run_started(agent_name="research-agent", input_summary=user_input[:100], max_steps=max_steps) try: while self.step < max_steps and not cancel.is_cancelled: self.step += 1 # --- 步骤开始 --- await self.stream.emit_step_start(self.step, "thinking", f"Agent 正在进行第 {self.step} 步思考") if cancel.is_cancelled: break # --- LLM 流式调用 --- token_index = 0 async for chunk in self.llm.stream_chat(self.messages): if cancel.is_cancelled: break if chunk.type == "text": await self.stream.emit_llm_token(self.step, chunk.content, token_index) token_index += 1 elif chunk.type == "tool_call": tool_calls.append(chunk.tool_call) # --- 工具调用 --- for tc in tool_calls: if cancel.is_cancelled: break await self.stream.emit_tool_call(self.step, tc.id, tc.name, tc.arguments) result = await self.tools.execute(tc.name, tc.arguments) await self.stream.emit_tool_result( self.step, tc.id, "success", str(result)[:200], full_result_available=len(str(result)) <= 200, duration_ms=tool_duration) await self.stream.emit_step_complete(self.step, "thinking", step_duration, "success") finally: # 保存 checkpoint(completed → committed;其他 → partial) ... ``` ### Q:Token 级流式怎么对接 LLM Provider? A:结论先行——**把 Provider 的 SSE 流解析成自己的 `StreamChunk` 异步生成器**,逐帧区分 `text` 与 `tool_call`。 ```python class OpenAIClient: async def stream_chat(self, messages: list[dict], model: str = "gpt-4", tools: list[dict] | None = None): """SSE 流式调用 Chat Completions API,产出 StreamChunk 序列""" payload = {"model": model, "messages": messages, "stream": True} if tools: payload["tools"] = tools payload["tool_choice"] = "auto" async with self._client.stream("POST", f"{self.base_url}/chat/completions", headers={"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}, json=payload) as response: response.raise_for_status() async for line in response.aiter_lines(): if not line.startswith("data: "): continue data_str = line[6:] # 去掉 "data: " 前缀 if data_str == "[DONE]": break chunk = self._parse_chunk(json.loads(data_str)) if chunk: yield chunk ``` 关键点解读:示例里对 `tool_calls` 的处理留了坑并明确标注——**工具调用在流式中是分多帧到达的(首帧有 id + function.name,后续帧是 arguments 的增量),必须累积拼接**。这是"流式 + 函数调用"最容易写错的地方:如果每帧当成完整 tool_call 处理,最终拿到的工具参数会是残缺 JSON。具体帧结构需结合所用 Provider 的 API 版本确认。 ## 九、前端 UX 模式与工程实践 ### Q:Agent 的思考过程要不要给用户看? A:结论先行——**默认折叠**:`llm.thought` 对部分用户有价值,但对多数用户是干扰;应该"默认可折叠,需要时展开",并且工具卡片也做同样的折叠处理。  *图:流式输出卡片:思考流、工具调用与结果、分析结果* ```text ┌─────────────────────────────────────────────────────────┐ │ 🔍 Agent 正在分析 Q2 财报 [−] │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 💭 用户需要Q2财报数据。首先搜索公开财报信息... │ │ │ │ 💭 搜索返回3条结果,需要核实数据来源的权威性... │ │ │ │ 💭 数据已确认,可以开始计算财务指标... │ │ │ └─────────────────────────────────────────────────────┘ │ │ 🔧 调用工具: search_financial_reports(Q2, 2026) [−] │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 参数: {"quarter":"Q2","year":2026} │ │ │ │ 状态: ✅ 成功 (1200ms) │ │ │ │ 结果: Q2营收: 150亿, 利润: 22亿, 同比增长12%... │ │ │ └─────────────────────────────────────────────────────┘ │ │ 💡 分析结果: │ │ 根据Q2财报数据,公司营收150亿元... │ └─────────────────────────────────────────────────────────┘ ``` 进度条与步数指示器要同时给出"总量、已用时、预计剩余"与**子任务清单**:  *图:Run 进度卡片:45% 进度条、Step 5/12 与子任务清单* ```text ┌─────────────────────────────────────────────────────────┐ │ ████████████████░░░░░░░░░░░░░░░░░░ 45% │ │ Step 5/12 · 已用时 8.2s · 预计剩余 10s │ │ 子任务进度: │ │ ✅ 搜索财报数据 │ │ ✅ 计算财务指标 │ │ ⏳ 对比去年同期 (进行中...) │ │ ⬜ 生成趋势图表 │ │ ⬜ 撰写分析报告 │ └─────────────────────────────────────────────────────────┘ ``` 前端工具卡片要有一秒一跳的本地计时器(`setInterval` 每秒 +1),并在 `tool.result` 到达时切换到结果视图;流式回答则用 `EventSource` 监听 `answer.token` 累加 token,并在流式期间显示闪烁光标,`answer.complete` 时停掉光标。 ### Q:流式的代价是什么?什么时候不该上流式? A:结论先行——代价是**长连接占用、序列化开销、前后端复杂度上升、调试难度增加**;用"执行时长"作为决策依据。 | 维度 | 无流式(批量返回) | 有流式(SSE) | 权衡 | |---|---|---|---| | 网络连接 | 1 次请求-响应 | 1 个长连接(可能持续数分钟) | 长连接占用连接池资源 | | 序列化开销 | 一次 JSON 序列化 | 每条事件都要序列化 | 高频 `llm.token` 有 CPU 开销 | | 客户端复杂度 | 简单 `await fetch()` | 需要 EventSource + 状态管理 | 前端代码量增加 2-3 倍 | | 服务端复杂度 | 无状态函数调用 | 需管理连接、心跳、取消 | 服务端架构复杂度显著上升 | | 错误处理 | 一次 try-catch | 需处理中途断连、部分消费 | 需要幂等消费 + 重连机制 | | 调试难度 | 请求-响应可复现 | 时序依赖,难以复现 | 需要事件日志和 replay 能力 | ```text 决策框架: Agent 执行预计耗时 < 3 秒 → 不需要流式,批量返回即可 预计耗时 3~10 秒 → 建议流式,但可简化(只发 step 事件) 预计耗时 > 10 秒 → 必须完整流式,含 token 级 + 进度 + 取消 ``` ### Q:生产环境的检查清单有哪些? A:结论先行——十条,重点盯**代理配置、心跳、取消链路、错误事件化、缓冲区有界**。 ```text 1. SSE 事件格式规范:每条事件有 event: + id: + data:,符合 W3C 标准 2. Nginx/CDN 配置正确:proxy_buffering off,Cache-Control: no-cache 3. 心跳机制:每 30s 发送 ": heartbeat\n\n" 防止中间代理断开长连接 4. 取消链路完整:前端按钮 → POST cancel → CancellationToken → 中断 LLM/工具 → 保存 checkpoint 5. 错误事件化:后端异常不直接抛 HTTP 500,而是通过 run.error 通知前端 6. 事件 Buffer 有限:回溯缓冲区有 max_size 限制,防内存无限增长 7. 工具结果截断:tool.result 只发 preview,完整结果通过独立 API 获取 8. 进度节流:progress 不超过每秒 1 次,llm.token 不合并(保持实时性) 9. 连接断开检测:服务端检测 request.is_disconnected(),断开时清理资源 10. 并发 Run 隔离:每个 run_id 有独立事件队列与 Controller,互不干扰 ``` 关键点解读:第 5 条(**错误事件化**)值得单独强调。如果后端在流中途抛 HTTP 500,前端 `EventSource` 会直接触发 `onerror` 并尝试重连,用户看到的是"连接失败"这种无信息量的提示;而通过 `run.error` 事件下发,就能带上 `error_code`、`message`、`recoverable`、`checkpoint_id`,用户可以明确知道"发生了什么、能不能恢复"。 ### Q:常见反模式有哪些? A:结论先行——六条,本质都是"**把流式当成"只是一条通道",忽略了它需要专门的生命周期设计**"。 | 反模式 | 问题 | 正确做法 | |---|---|---| | 把所有数据塞进 SSE 事件 | 单条事件过大(如 500KB 工具结果)会阻塞后续事件 | 工具结果只发 200 字符预览 | | 没有事件 `id` | 断线后无法知道从哪恢复 | 每条事件带递增 id | | 工具调用中不发任何事件 | 用户看到 Agent "卡住了"不知在干什么 | 发 `tool.call` + 周期性 heartbeat/progress | | 取消时不保存状态 | 取消后白跑,用户无法恢复 | 取消时保存 partial checkpoint | | SSE 与业务请求混用同一个连接 | 取消请求需要额外 HTTP 调用 | 取消单独用 POST 端点 | | 前端 EventSource 不加错误处理 | 连接断了前端白屏 | 监听 `onerror` + 显示重连提示 | ### Q:这套能力应该怎么分期演进? A:结论先行——三阶段:**MVP(step 级事件 + 简单进度 + 暴力中断)→ 生产就绪(token 级 + 工具流式 + ETA + 优雅取消)→ 企业级(事件 replay + 多客户端 + 自适应预估 + 双向流)**。 ```text Phase 1(MVP): - 只有 step 级事件(step.start / step.complete) - 简单的进度(步数/总步数) - 基础取消(暴力中断) Phase 2(生产就绪): - Token 级 LLM 流式 - 工具调用流式(tool.call + tool.result) - ETA 预估 - 优雅取消 + checkpoint 保存 Phase 3(企业级): - 事件 replay(完整事件日志持久化) - 多客户端同步监听同一个 Run - 自适应进度预估 - WebSocket 双向流(语音 Agent) ``` ## 小结 - Agent 的执行链路比 Chat 长 3~10 倍,**流式是弥合"等待焦虑"的唯一手段**,同时还是"提前取消省成本"的前提(示例省 82%); - 流式内容不是一条 text 流,而是**四类事件**:元事件、内容事件、进度事件、错误/警告事件; - 协议选型首选 **SSE**(服务端推送为主,取消用独立 POST),并重点解决**代理缓冲、空闲超时、CDN 缓存、HTTP/2** 四类兼容问题; - 架构上推荐**直接流(async generator)为主**,Pub/Sub 作为企业级扩展;断线重连靠 `Last-Event-Id` + 有界事件缓冲; - 进度用**加权启发式**估算(子任务 0.6 / 步数 0.4,ReAct 退化到 0.3);ETA 用**滑动窗口近 5 步均值 × 1.1**;进度事件三重节流,token 事件不节流; - 取消必须**散布检查点 + 按状态区分 committed/partial Checkpoint**,前端要有"取消中"过渡态; - 工具调用的空窗期要用 `tool.call` + 计时器 + 周期 progress 占住;大结果只发 200 字符预览 + 拉取 URL; - 后端核心抽象是 **async generator 管道 + AgentStreamController**;错误必须**事件化**而非抛 HTTP 500; - 前端默认折叠思考过程,工具卡片带本地计时器;按执行时长(3s / 3~10s / >10s)决定是否上流式。 ## 思考题 1. 有界事件缓冲(示例 500~1000 条)会让超长 Run 的早期事件无法回放。如果业务要求"必须支持完整回放",你会怎么改造架构?代价是什么? 2. 进度百分比在 ReAct 场景下只是"步数比例",但 Agent 下一步可能调用一个耗时 30 秒的工具,导致进度从 40% 直接跳到 90%。你会怎么让进度曲线更平滑可信? 3. 用户的取消请求刚好落在"工具调用已发出、结果未返回"的窗口。除了保存 partial checkpoint,你还需要对工具层做什么防护?(提示:与幂等设计联动) 4. `progress` 事件节流到"每秒最多一次 + 变化 5%",但心跳兜底是 5 秒。如果 Agent 某一步耗时 60 秒,用户在这 60 秒里能看到什么?你会怎么优化这段体验? 5. 如果产品要求"支持多客户端同时观看同一个 Run",方案 A(直接流)会暴露什么问题?迁移到方案 B(Pub/Sub)后会引入哪些新的一致性挑战?
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入