--- title: "第十章：A2UI 协议（流式 UI 组件）" --- 本章目标：实现 A2UI 协议，将 Agent 的输出渲染为流式 UI 组件。 ## 重要说明：A2UI 的边界 A2UI 并不属于 Eino 框架本身的范畴，它是一个业务层的 UI 协议/渲染方案。本章把 A2UI 集成进前面章节逐步构建出来的 Agent，是为了提供一个端到端、可落地的完整示例：从模型调用、工具调用、工作流编排，到最终把结果以更友好的 UI 方式呈现出来。 在真实业务场景中，你完全可以根据产品形态选择不同的 UI 形式，例如： - Web / App：自定义组件、表格、卡片、图表等 - IM/办公套件：消息卡片、交互式表单 - 命令行：纯文本或 TUI（终端 UI） Eino 更关注“可组合的智能执行与编排能力”，至于“如何呈现给用户”，属于业务层可以自由扩展的一环。 ## 代码位置 - 入口代码：[main.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/main.go) - Agent 构建：[agent.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/agent.go) - 服务端路由：[server/server.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/server/server.go) - A2UI 子集实现：[a2ui/types.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/a2ui/types.go) - A2UI 事件流转换：[a2ui/streamer.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/a2ui/streamer.go) - 前端页面：[static/index.html](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/static/index.html) ## 前置条件 与第一章一致：需要配置一个可用的 ChatModel（OpenAI 或 Ark） ## 运行 在 `quickstart/chatwitheino` 目录下执行： ```bash go run . ``` 输出示例： ```text starting server on http://localhost:8080 ``` ### （可选）启用 ch09 的 skills 能力 最终 Web 版使用的 Agent 构建逻辑与 Chapter 9 对齐：当 `EINO_EXT_SKILLS_DIR` 指向一个合法 skills 目录时，会自动注册 `skill` 中间件，模型就能按需调用 `skill` 工具加载 `eino-guide` / `eino-component` / `eino-compose` / `eino-agent`。 ```bash go run ./scripts/sync_eino_ext_skills.go -src /path/to/eino-ext -dest ./skills/eino-ext -clean EINO_EXT_SKILLS_DIR="$(pwd)/skills/eino-ext" go run . ``` ## 从文本到 UI：为什么需要 A2UI 前八章我们实现的 Agent 只输出文本，但现代 AI 应用需要更丰富的交互。 **纯文本输出的局限：** - 无法展示结构化数据（表格、列表、卡片等） - 无法实时更新（进度条、状态变化等） - 无法嵌入交互元素（按钮、表单、链接等） - 无法支持多媒体（图片、视频、音频等） **A2UI 的定位：** - **A2UI 是 Agent 到 UI 的协议**：定义了 Agent 输出如何映射到 UI 组件 - **A2UI 支持流式渲染**：组件可以实时更新，无需等待完整响应 - **A2UI 是声明式的**：Agent 只需声明"显示什么"，UI 负责渲染 **简单类比：** - **纯文本输出** = "终端命令行"（只能显示文本） - **A2UI** = "Web 应用"（可以显示任何 UI 组件） ## 关键概念 ### A2UI v0.8 子集（本示例的边界） 本 quickstart 并没有实现一个“完整的 A2UI 标准库”，而是实现了一个 **A2UI v0.8 的子集**：目标是把 Agent 的事件流，以稳定、可增量渲染的 UI 组件树方式推给浏览器。 当前实现的 A2UI 消息类型与组件类型，以 [a2ui/types.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/a2ui/types.go) 为准。 ### A2UI 消息：BeginRendering / SurfaceUpdate / DataModelUpdate / InterruptRequest 每一行 SSE（`data: {...}`）承载一个 A2UI Message，Message 是一个“信封结构”，每次只会出现一个字段： **关键代码片段（**注意：这是简化后的代码片段，不能直接运行，完整代码请参考** [a2ui/types.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/a2ui/types.go)）：** ```go type Message struct { BeginRendering *BeginRenderingMsg SurfaceUpdate *SurfaceUpdateMsg DataModelUpdate *DataModelUpdateMsg DeleteSurface *DeleteSurfaceMsg InterruptRequest *InterruptRequestMsg } ``` 其中： - `BeginRendering`：告诉前端“开始渲染一个 surface（会话）”，并指定根节点 ID - `SurfaceUpdate`：新增/更新一批组件（组件是一个树，用 `id` 互相引用） - `DataModelUpdate`：更新 data bindings（用于把流式文本增量更新到某个 Text 组件） - `InterruptRequest`：当 Agent 触发 interrupt（例如审批）时，通知前端展示批准/拒绝入口 ### A2UI 组件：Text / Column / Card / Row 本示例 UI 组件只实现了 4 种（见 [a2ui/types.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/a2ui/types.go)）： - `Text`：文本渲染（支持 `usageHint` 区分 caption/body/title）；当 `dataKey` 存在时，文本来自 `DataModelUpdate` - `Column` / `Row`：布局（children 是组件 ID 列表） - `Card`：卡片容器（children 是组件 ID 列表） ## A2UI 的实现：把 AgentEvent 转成 A2UI SSE 最终 Web 版的核心链路是： - 后端运行 Agent，得到 `*adk.AsyncIterator[*adk.AgentEvent]` - 把事件流转换为 A2UI JSONL/SSE 流输出给浏览器（见 [a2ui/streamer.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/a2ui/streamer.go)） - 前端解析 SSE 的 `data:` 行并渲染组件树（见 [static/index.html](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/static/index.html)） ### 服务端路由（高层） 与 A2UI 相关的关键接口（见 [server/server.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/server/server.go)）： - `GET /`：返回前端页面 `static/index.html` - `POST /sessions/:id/chat`：返回 SSE 流（A2UI messages），把 Agent 运行结果边跑边渲染到 UI - `GET /sessions/:id/render`：返回 JSONL（A2UI messages），用于“选中会话时回放历史” - `POST /sessions/:id/approve`：处理 interrupt 的批准/拒绝并继续返回 SSE 流 ### 事件流转换（高层） 服务端把 `Runner.Run(...)` 的事件流交给 `a2ui.StreamToWriter(...)`，后者负责： - 对 user/assistant/tool 的输出做拆分 - 把 tool call / tool result 渲染成 “chip 卡片” - 把 assistant 的流式 token 做成 `DataModelUpdate`，实现“边生成边渲染” - 遇到 interrupt 时发送 `InterruptRequest`，并暂停等待人类批准 ## 前端集成：fetch + SSE（不是 WebSocket） - 前端通过 `fetch('/sessions/:id/chat')` 发起请求，然后从 `res.body` 读取流式字节，按行切分并解析 `data: {...}` 的 JSON（见 [static/index.html](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/static/index.html)）。 **关键代码片段（**注意：这是简化后的代码片段，不能直接运行，完整代码请参考** [static/index.html](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/static/index.html)）：** ```javascript const res = await fetch(`/sessions/${id}/chat`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({message}), }); const reader = res.body.getReader(); const decoder = new TextDecoder(); let buffer = ''; while (true) { const {done, value} = await reader.read(); if (done) break; buffer += decoder.decode(value, {stream: true}); const lines = buffer.split('\n'); buffer = lines.pop(); for (const line of lines) { const trimmed = line.trim(); if (trimmed.startsWith('data:')) { const jsonStr = trimmed.slice(5).trimStart(); processA2UIMessage(JSON.parse(jsonStr)); } } } ``` ## A2UI 流式渲染流程（概览） ``` ┌─────────────────────────────────────────┐ │ 用户：分析这个文件 │ └─────────────────────────────────────────┘ ↓ ┌──────────────────────┐ │ Agent 开始处理 │ │ A2UI: AddText │ │ "正在分析..." │ └──────────────────────┘ ↓ ┌──────────────────────┐ │ 调用 Tool │ │ A2UI: AddProgress │ │ 进度: 0% │ └──────────────────────┘ ↓ ┌──────────────────────┐ │ Tool 执行中 │ │ A2UI: UpdateProgress│ │ 进度: 50% │ └──────────────────────┘ ↓ ┌──────────────────────┐ │ Tool 完成 │ │ A2UI: tool result │ └──────────────────────┘ ↓ ┌──────────────────────┐ │ 显示结果 │ │ A2UI: DataModelUpdate│ │ （流式更新 assistant）│ └──────────────────────┘ ``` ## 本章小结 - **A2UI**：Agent 到 UI 的协议，定义了 Agent 输出如何映射到 UI 组件 - **子集实现**：本示例只实现了 Text/Column/Card/Row 与 data binding - **流式输出**：后端以 SSE 推送 A2UI JSONL，前端增量渲染组件树 - **事件到 UI**：把 `AgentEvent` 转为 `tool call / tool result / assistant stream` 的可视化输出 ## 系列收尾：这个 Quickstart Agent 的完整愿景 到本章为止，我们用一个可以实际运行的 Agent 串起了 Eino 的核心能力。你可以把它理解为一个可扩展的“端到端 Agent 应用骨架”： - 运行时：Runner 驱动执行，支持流式输出与事件模型 - 工具层：Filesystem / Shell 等 Tool 能力接入，工具错误可被安全处理 - 中间件：可插拔的 middleware/handler，用于错误处理、重试、审批等横切能力 - 可观测：callbacks/trace 能力把关键链路打通，便于调试与线上观测 - 人机协作：interrupt/resume + checkpoint 支持审批、补参、分支选择等交互式流程 - 确定性编排：compose（graph/chain/workflow）把复杂业务流程组织为可维护、可复用的执行图 - 业务交付：像 A2UI 这样的 UI 集成，属于业务层自由选择的一环，用来把 Agent 能力以合适的产品形态呈现给用户 你可以在这个骨架上逐步替换/扩展任意环节：模型、工具、存储、工作流、前端渲染协议，而不需要推倒重来。 ## 扩展思考 **其他组件类型：** - 图表组件（折线图、柱状图、饼图） - 地图组件 - 时间线组件 - 树形组件 - 标签页组件 **高级功能：** - 组件交互（点击、拖拽、输入） - 条件渲染 - 组件动画 - 响应式布局