a2ui

A2UI 开发技能

此技能可帮助你生成符合 A2UI（Agent to UI）协议的代码，以构建丰富、交互式的用户界面，供 AI Agent 流式传输到客户端。

协议版本

此技能面向 A2UI Protocol v0.8（稳定版）。

标准目录 ID：https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json

核心概念

1. 消息类型

A2UI 在 JSONL 流中使用四种消息类型：

消息	用途
surfaceUpdate	定义或更新 UI 组件
dataModelUpdate	填充或更新应用状态
beginRendering	通知客户端开始渲染
deleteSurface	移除 UI 界面

2. 邻接列表模型

组件以带 ID 引用的扁平列表形式定义，而不是嵌套树：

{"surfaceUpdate": {"surfaceId": "main", "components": [
  {"id": "root", "component": {"Column": {"children": {"explicitList": ["header", "content"]}}}},
  {"id": "header", "component": {"Text": {"text": {"literalString": "Welcome"}, "usageHint": "h1"}}},
  {"id": "content", "component": {"Text": {"text": {"path": "/user/name"}}}}
]}}

3. 数据绑定（BoundValue）

值绑定有三种模式：

// Literal only - static value
{"literalString": "Hello"}

// Path only - dynamic from data model
{"path": "/user/name"}

// Both - initialization shorthand (sets default AND binds)
{"path": "/form/email", "literalString": "[email protected]"}

4. 样式配置

在 beginRendering 中自定义外观：

{"beginRendering": {
  "surfaceId": "main",
  "root": "root",
  "styles": {
    "font": "Roboto",
    "primaryColor": "#1976D2"
  }
}}

属性	描述
font	主要字体系列
primaryColor	主题颜色（十六进制格式 #RRGGBB）

标准目录组件

布局组件

• Row - 水平容器，支持 distribution 和 alignment
• Column - 垂直容器，支持 distribution 和 alignment
• List - 可滚动列表，支持 direction（垂直/水平）
• Card - 带有单个 child 的 Material 卡片容器
• Tabs - 选项卡导航，带有 tabItems 数组
• Modal - 对话框，带有 entryPointChild 和 contentChild
• Divider - 分隔线，支持 axis（水平/垂直）

显示组件

• Text - 文本显示，支持 usageHint（h1-h5、caption、body）。支持简单 Markdown。
• Image - 图片，支持 url、fit、usageHint
• Icon - 标准图标集中的图标（参见组件参考）
• Video - 视频播放器，支持 url
• AudioPlayer - 音频播放器，支持 url 和 description

输入组件

• Button - 可点击组件，带有 child 和 action
• TextField - 文本输入，带有 label、textFieldType
• CheckBox - 切换组件，带有 label 和 value
• DateTimeInput - 日期/时间选择器，支持 enableDate/enableTime
• MultipleChoice - 选择组件，带有 options 和 maxAllowedSelections
• Slider - 范围输入，支持 minValue/maxValue

组件权重

在 Row/Column 内的组件上使用 weight 实现弹性布局：

{"id": "sidebar", "weight": 1, "component": {"Column": {...}}},
{"id": "main", "weight": 3, "component": {"Column": {...}}}

生成 A2UI 消息

基本流程

1. 通过 surfaceUpdate 定义组件
2. 通过 dataModelUpdate 填充数据
3. 通过 beginRendering 触发渲染

完整示例：简单表单

{"surfaceUpdate": {"surfaceId": "booking", "components": [
  {"id": "root", "component": {"Column": {"children": {"explicitList": ["title", "name_field", "date_field", "submit_btn"]}}}},
  {"id": "title", "component": {"Text": {"text": {"literalString": "Book a Table"}, "usageHint": "h2"}}},
  {"id": "name_field", "component": {"TextField": {"label": {"literalString": "Your Name"}, "text": {"path": "/form/name"}}}},
  {"id": "date_field", "component": {"DateTimeInput": {"value": {"path": "/form/date"}, "enableDate": true}}},
  {"id": "submit_btn", "component": {"Button": {"child": "submit_text", "action": {"name": "submit_booking", "context": [{"key": "name", "value": {"path": "/form/name"}}, {"key": "date", "value": {"path": "/form/date"}}]}}}},
  {"id": "submit_text", "component": {"Text": {"text": {"literalString": "Confirm Booking"}}}}
]}}
{"dataModelUpdate": {"surfaceId": "booking", "contents": [{"key": "form", "valueMap": [{"key": "name", "valueString": ""}, {"key": "date", "valueString": ""}]}]}}
{"beginRendering": {"surfaceId": "booking", "root": "root"}}

事件处理

用户操作

用户进行交互（例如点击按钮）时，客户端会发送 userAction：

{
  "userAction": {
    "name": "submit_booking",
    "surfaceId": "booking",
    "sourceComponentId": "submit_btn",
    "timestamp": "2025-01-01T10:00:00Z",
    "context": {"name": "John Doe", "date": "2025-01-15"}
  }
}

错误报告

客户端通过 error 消息报告错误：

{
  "error": {
    "type": "RENDER_ERROR",
    "message": "Component 'user_card' references missing child",
    "surfaceId": "main",
    "componentId": "user_card",
    "timestamp": "2025-01-01T10:30:05Z"
  }
}

最佳实践

1. 唯一 ID：每个组件在其界面内都需要唯一的 id
2. 扁平结构：使用 ID 引用表示父子关系
3. 数据分离：将 UI 结构放在 surfaceUpdate 中，将动态值放在 dataModelUpdate 中
4. 路径约定：路径使用 JSON Pointer 格式（例如 /user/profile/name）
5. 渐进式渲染：定义好必要组件后发送 beginRendering
6. 清理界面：流程完成后使用 deleteSurface

参考文档

核心参考

• 组件参考 - 全部 16 个组件及其属性
• 数据绑定指南 - BoundValue 模式和模板
• API 集成 - 事件处理和后端连接
• 架构参考 - 用于验证的 JSON Schema

高级主题

• 目录协商 - 多目录支持
• 界面管理 - 多个 UI 区域
• 流式传输与性能 - 渐进式渲染
• Agent 提示词 - 大模型集成

示例

基础模式

• 表单示例 - 注册和预订表单
• 列表示例 - 使用模板的动态列表
• 模态框示例 - 对话框和弹出窗口模式

高级模式

• 预订流程 - 端到端业务流程
• 多界面 - 多个 UI 区域
• 流式传输 - 渐进式渲染