导航

基本介绍

什么是 A2UI？

A2UI（Agent-to-User Interface , 智能体到用户界面）是一个开放协议与框架，它允许 AI 智能体（Agent）根据当前场景和上下文，实时生成交互式用户界面。

为什么需要 A2UI

纯文本 Agent 交互效率低:

用户：帮我订明天晚上 7 点、2 人的位子
Agent：好的，请问哪一天？
用户：明天
Agent：几点？
用户：7 点
Agent：几位？
...

更好的体验：Agent 直接生成一个带日期选择器、人数输入框和确认按钮的表单，用户在 UI 上操作，而不是来回打字。

当前版本说明

版本	状态	说明
v0.8	稳定（Stable）	消息名如 `surfaceUpdate`、`dataModelUpdate`、`beginRendering`
v0.9	当前主推（Draft/Current）	消息名如 `createSurface`、`updateComponents`、`updateDataModel`；结构更扁平
v0.10	演进中	Catalog 与类型持续迭代

下文介绍默认使用 v0.9，并在关键处标注 v0.8 差异。

核心概念

A2UI 建立在三个核心思想之上：

流式消息：UI 更新作为从 Agent 到客户端的 JSON 消息序列流动。
声明式组件：UI 被描述为数据，而不是被编程为代码。
数据绑定：UI 结构与应用状态分离，支持响应式更新。

核心术语

术语	含义
Agent	生成 A2UI 消息的一方（可以是 LLM，也可以是确定性逻辑）
Renderer	接收消息、维护状态、渲染原生 UI 的客户端
Surface	一块独立的 UI 画布（如一个表单、一张卡片），有各自的组件树和数据模型；Surface 之间不能嵌套
Component	UI 元素（Button、TextField、Card 等），在消息里以扁平列表 + ID 引用描述
Data Model	每个 Surface 各自的 JSON 状态对象，组件通过路径绑定到它
Catalog	组件白名单：Agent 只能使用 Catalog 里定义的组件类型和属性
Message	Agent → Renderer 的单条 JSON 指令（如 `updateComponents`）
Action / Event	用户交互后 Renderer → Agent 的回传消息
Data Reference	组件属性中的值引用：字面量、路径绑定 `{ "path": "..." }` 或表达式

Agent 与 Renderer 的职责分工

Renderer 提供：

支持的 Catalog（组件能力清单）
如何把消息渲染成 UI 的指令

Agent 循环：

根据 Catalog 生成 UI 结构 + 数据
接收用户 Action / 同步的数据模型
更新 UI 或数据，进入下一轮

消息与数据流

端到端架构

Agent (LLM) → A2UI 消息生成 → 传输层 (SSE/WS/A2A/AG-UI)
                                      ↓
客户端 (流读取) → 消息解析（Processor） → Renderer → 原生 UI
																			↑
															  用户 Action 回传

消息格式：JSONL

A2UI 定义了一系列描述用户界面的 JSON 消息。在流式传输时，这些消息通常格式为 JSON 行（JSONL）， 每行是一个完整的 JSON 对象。便于：

边生成边下发（渐进式渲染）
LLM 增量纠错（先补结构，再补数据）
单条消息损坏时不拖垮整段流

v0.9 核心消息类型

消息	方向	作用
`createSurface`	Agent → Renderer	创建 Surface，指定 `catalogId`（及可选 `theme`、`sendDataModel`）
`updateComponents`	Agent → Renderer	新增或更新组件（扁平数组，按 `id` 合并）
`updateDataModel`	Agent → Renderer	更新数据模型的某个路径
`deleteSurface`	Agent → Renderer	销毁 Surface
`action`	Renderer → Agent	用户触发的事件（按钮点击等）
`error`	Renderer → Agent	校验失败等错误反馈

v0.8 对照：surfaceUpdate ≈ updateComponents；dataModelUpdate ≈ updateDataModel；beginRendering 在 v0.9 中被 createSurface 取代（v0.9 约定 id: "root" 的组件为根节点）。

典型消息顺序

一个 Surface 从创建到可交互，Agent 通常按下方顺序发消息。

客户端收到后即可渲染；后续 Agent 可以只发 updateDataModel 刷新显示，无需重画整棵组件树。

{
  "version": "v0.9",
  "createSurface": {
    "surfaceId": "main",
    "catalogId": "<https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json>"
  }
}
{
  "version": "v0.9",
  "updateComponents": {
    "surfaceId": "main",
    "components": [...]
  }
}
{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/user",
    "value": { "name": "Lance" }
  }
}
{
  "version": "v0.9",
  "deleteSurface": { "surfaceId": "main" }
}

渐进式渲染

不必等 Agent 生成完整响应。updateComponents 可以分批到达——用户会看到 UI 边生成边出现，而不是长时间白屏。

实践建议：

结构（updateComponents）相对稳定时一次性发齐
高频变化的内容走 updateDataModel
避免对同一组件属性反复全量覆盖导致闪烁

生命周期示例：餐厅预订

用户：“明天晚上 7 点预订两人桌”