h1A2UI (Agent-to-User Interface) 协议详解/h1 A2UI 是一个开放的协议标准,让 AI Agent 能够安全地向客户端发送丰富的交互式用户界面。Agent 发送声明式 JSON 描述 UI 的意图,客户端使用自己的原生组件库渲染出来。 h2一、原始内容概述/h2 h31.1 什么是 A2UI/h3 A2UI(Agent-to-User Interface)是一个开放的协议标准,由 Google 主导开发,CopilotKit 及开源社区共同贡献,Apache 2.0 许可。它的核心使命是:strong让 AI Agent 能够安全地向客户端发送丰富的交互式用户界面/strong。 一句话概括:A2UI 让 Agent "说 UI 的语言"——Agent 发送声明式 JSON 描述 UI 的意图,客户端使用自己的原生组件库渲染出来。 h31.2 核心问题/h3 A2UI 解决的核心问题是:strongAI Agent 如何在跨信任边界的情况下,安全地发送丰富的用户界面?/strong ul li纯文本响应:体验太差,无法表达复杂 UI/li li执行代码(HTML/JS):安全风险极高,LLM 生成的代码不可信/li li预定义模板:不够灵活,无法适应动态场景/li /ul A2UI 的答案:strong声明式数据格式,不执行任何代码/strong。安全像数据,表达力像代码。 h31.3 核心设计哲学/h3 ol listrong安全第一/strong:声明式 JSON 数据格式,客户端维护受信任的"组件目录"(Catalog)/li listrongLLM 友好/strong:扁平组件列表 + ID 引用(邻接表模型),LLM 可以逐步生成、流式渲染/li listrong框架无关/strong:一套 JSON 同时渲染到 Angular、Flutter、React、Lit 等/li listrong渐进式渲染/strong:流式更新,用户无需等待完整响应/li /ol h31.4 协议版本状态/h3 ul listrong当前生产版:v0.9.1/strong/li li候选版:v1.0(增加 actionResponse RPC、action ID、surfaceProperties)/li li稳定版:v0.9(Prompt-First 模式)/li li遗留版:v0.8(Structured Output 模式)/li /ul h31.5 四类核心消息/h3 A2UI 协议是服务端到客户端的单向 JSON 流,仅四种消息类型: strong① createSurface/strong:创建 UI 表面,必须最先发送。包含 surfaceId(唯一标识)、catalogId(组件目录标识)、theme(主题)和 sendDataModel(是否回传数据模型)属性。 strong② updateComponents/strong:更新组件结构。组件以扁平列表形式发送,通过 ID 引用建立关系(邻接表模型)。每个 surface 必须有一个 id 为 "root" 的根组件。 strong③ updateDataModel/strong:更新数据模型。使用 JSON Pointer 路径定位更新位置,无需重发整个组件结构。 strong④ deleteSurface/strong:删除 UI 表面及其所有组件和数据。 h31.6 组件目录(Catalog)/h3 ul listrongBasic Catalog/strong:内置基础组件(Text, Button, Row, Column, Card, TextField, Icon, Image, Select, Checkbox, Slider, DataTable 等)/li listrong自定义 Catalog/strong:开发者可定义自己的组件目录,限制 Agent 只能使用你应用中的受信任组件/li /ul h31.7 数据绑定/h3 使用 JSON Pointer 路径将组件属性绑定到数据模型,支持动态类型。动态类型可以接受字面值、路径绑定或函数调用。 h31.8 传输层解耦/h3 A2UI 协议本身是传输无关的,支持多种传输方式:A2A(推荐)、AG-UI、MCP、SSE+JSON-RPC、WebSocket、REST。 每个传输层需要保证:顺序可靠送达、消息分帧、元数据支持。 hr / h2二、使用场景举例/h2 h3场景 1:动态表单生成/h3 用户说"帮我预订一间带会议室和投影仪的商务套房"——Agent 即时生成定制表单(日期选择器、房型下拉、设施多选),客户端用原生组件渲染。 h3场景 2:远程子 Agent UI 注入/h3 主 Agent 委派酒店预订给远程 Agent,远程 Agent 返回 A2UI payload,通过 A2A transport 传回主客户端——酒店 Agent 无需关心用户用的是什么前端框架。 h3场景 3:自适应审批看板/h3 Agent 根据查询动态生成 DataTable + 审批按钮,用户点击后实时更新面板数据。 h3场景 4:实时数据监控面板/h3 Agent 先 createSurface 创建面板结构,updateComponents 定义卡片布局,然后持续通过 updateDataModel 推送 CPU/内存/磁盘指标,界面无需重绘。 h3场景 5:聊天中嵌入地图/图表组件/h3 Agent 在对话流中插入 Google Map 组件或 DataTable 组件,客户端原生渲染。 hr / h2三、最佳实践/h2 h3Agent 端/h3 ul listrongPrompt-First 设计/strong:把目录 schema 嵌入 prompt/li listrong渐进式流输出/strong:先 createSurface → updateComponents → updateDataModel/li listrong先结构后数据/strong:组件结构优先于数据填充/li listrong利用数据绑定/strong:用 { "path": "/xxx" } 而非硬编码/li /ul h3客户端/h3 ul listrong容错渲染/strong:对缺失引用用占位符兜底/li listrong自定义 Catalog 做安全边界/strong/li listrong合理启用 sendDataModel/strong/li /ul h3传输层/h3 ul liA2A 传输时用 contextId 关联 surfaces/li liSSE 一行一个 JSONL/li li消息分帧必须正确/li /ul hr / h2四、避坑指南/h2 ol listrongcreateSurface 之前发 updateComponents/strong:被丢弃/li listrong重复创建相同 surfaceId/strong:报错/li listrongJSON Pointer 路径错误/strong:必须以…