A8 · AG-UI、流式协议与产品体验深度版

本模块产出：ag-ui-adapter、用户可用的 Web Console · 对应总课表：第 23 周

学前自测

学习目标

把统一 Runtime Event 通过 AG-UI Adapter 转换成可恢复、可 steering、可人工协作的产品体验。

这个模块是整个课程里唯一直接面向最终用户的部分。前面所有模块的能力，用户能不能感知到、能不能用起来，取决于这一层。

课程内容

1. AG-UI Event 与 Agent / Client State
2. Snapshot、Delta 与 Patch
3. Text / Thinking / Tool / State 事件
4. Activity、Artifact、Citation 与 Custom Event
5. SSE、WebSocket 与 transport 取舍
6. Runtime Event 到 AG-UI Adapter
7. Native / Pi / LangGraph / Mastra Event 归一化
8. steering、follow-up 与 interrupt
9. Approval、Human-in-the-loop 与 editable state
10. reconnect、resume、event cursor 与去重
11. optimistic UI、backpressure 与 slow consumer
12. Conversation / Run / Session Tree UI
13. Error Recovery、Partial Result 与 Offline State
14. Accessibility、Sensitive Data 与前端权限边界

Snapshot、Delta 与 cursor 恢复

实施任务

实现统一事件协议：

type AgentEvent =
  | { type: 'run.started'; runId: string }
  | { type: 'text.delta'; text: string }
  | { type: 'tool.started'; tool: string; input: unknown }
  | { type: 'tool.completed'; tool: string; output: unknown }
  | { type: 'workflow.step'; step: string; status: string }
  | { type: 'approval.required'; approvalId: string }
  | { type: 'artifact.created'; artifact: Artifact }
  | { type: 'citation'; citation: Citation }
  | { type: 'run.completed'; result: unknown }
  | { type: 'run.failed'; error: PublicError }

实现 ag-ui-adapter，将统一 AgentEvent 映射为 AG-UI snapshot / delta 事件。前端通过 cursor 恢复流，能在运行中发送 steering、排队 follow-up、完成审批，并浏览 Session branch / replay。自定义事件必须命名空间化和版本化。

动手挑战

在最差的网络条件下用一次你自己的产品。

打开浏览器开发者工具的网络限速，设成 Slow 3G，再手工制造三种异常，全程录屏：

1. 断线重连：任务跑到一半断网三十秒再恢复，页面状态对不对？有没有丢事件或重复渲染？
2. 多标签页：同一个任务在两个标签页打开，一边审批，另一边看到了吗？
3. 慢消费者：打开开发者工具的 CPU 限速到最慢，让前端渲染跟不上，观察后端内存和事件缓冲区

第 3 条最容易翻车。很多实现在这里会发现服务端缓冲区无限增长，一个卡住的浏览器就能拖垮 Runtime。

录屏本身是极好的作品集素材：面试时播放一段断网三十秒后自动恢复的演示，比任何架构描述都有说服力。

Agent OS 里程碑

完成用户可用的 Web Console。

验收标准

• 页面刷新后可恢复 Run
• 工具调用可折叠查看
• 审批可在 UI 完成
• 文档引用可打开
• 长任务可离开后返回查看
• snapshot + delta 可在断线、重复包和乱序包后重建一致状态
• steering、follow-up、cancel 与 approval 的语义在所有已注册 Runtime 中一致
• 页面不直接依赖 Pi、LangGraph 或 Mastra 私有事件
• 慢客户端不会阻塞 Runtime，敏感 Tool 输入默认不发送到浏览器
• 通过键盘可完成运行、检查、审批和恢复流程

学后自测

本模块作业

1. packages/adapter-ag-ui/：统一 AgentEvent 到 AG-UI snapshot / delta 的映射
2. Web Console：运行、工具折叠、审批、引用打开、Session Tree 浏览
3. 恢复能力：cursor 续传、断线重连、乱序去重
4. steering 与 follow-up 的前端实现，五个 Runtime 语义一致
5. docs/streaming-resilience.md：动手挑战的三类异常测试报告 + 录屏

面试考点

这个模块对应面试里的产品工程能力，是纯后端候选人最容易丢分、也最容易差异化的地方。

• 「你做过 AI 产品的前端吗？」：这题机会很大。播放你的断网恢复录屏，然后讲 snapshot 加 delta 加 cursor 的设计。有可演示成果的候选人在这题上是压倒性优势。
• 「流式响应断了怎么办？」：答 cursor 续传加 Snapshot 重建，讲事件序号去重。这是流式产品的核心问题，答不好说明只做过一次性返回。
• 「慢客户端会不会影响后端？」：答 backpressure 加可合并事件丢弃加断开慢连接。这题知道的人不多，主动讲能明显加分。
• 「多个 Runtime 前端怎么统一？」：答 Adapter 层归一化，强调前端不能有框架判断分支。和 A5 串起来讲。
• 「steering 和 follow-up 的区别？」：程序员基础版第 8 周学过语义，这里讲前端怎么表达这个差异：steering 要有立即生效的视觉反馈，follow-up 要显示在队列里。产品意识的直接体现。
• 可访问性加分：主动提键盘可达和敏感数据不下发。这两点几乎没有候选人会提，提了会被记住。

复习与延伸

官方文档

• AG-UI 文档
• Server-Sent Events MDN
• WAI-ARIA Live Regions，流式内容的可访问性基础

本仓库对应源码

• packages/contracts/src/event.ts：AgentEvent 定义，AG-UI 映射的源头
• 五个 Adapter 包：事件归一化的实际差异都在这里

下一步：A9 · Agent 责任边界与合规