写在前面
大家好,我是三雒。
随着模型越来越聪明,用户对 AI 的期待也在变:不再满足于它实时生成一段文字回答,而是希望它能根据用户此刻的需求和特征,实时生成不同的界面。同一个问题,不同的人看到的 UI 可以不一样,也就是千人千面的 UI。
拿我最近在做的 AI 项目里最常见的商品对比来说。三个用户问的是同一句「这两款耳机哪个好」:
- 通勤党每天坐一个多小时地铁,最在意降噪和续航。界面最好把这两项并排放大,哪款更强一眼看出来;
- 学生党预算有限,最在意价格和性价比。界面最好先给价格差和当前优惠,再放一个「看看更便宜的」按钮;
- 音乐发烧友在意音质和支持的编码格式,想看的是一张参数对比表,外加试听入口。
问题一样,商品一样,该强调的东西却完全不同。如果 AI 只能回一段文字,这些差别只能靠措辞体现,用户还得自己从段落里找重点;如果前端按场景写死一张「对比卡」,它又只能照顾到其中一种人。
这就是这两年常说的生成式 UI(Generative UI):界面不再是前端事先写好的固定页面,而是由 AI 根据这一轮对话现场生成。但生成式 UI 不等于让 AI 现场写前端代码。更靠谱的做法是客户端事先准备好一套零件,图片、标题、价格、按钮、列表、对比项,AI 只决定用哪些零件、怎么拼、填什么数据。拼出来的界面千人千面,用的却始终是 App 自己的原生组件和设计规范。
这个想法落地时有几个绕不开的问题:
- Agent 拼界面时到底输出什么,才能既灵活、又能保证客户端的安全?
- Agent 跑在服务端,同一份描述怎样在 Web、Android、iOS 上都画出来?
- 模型是边想边输出token,那UI卡片能不能也边收边显示?
Google 去年 12 月开源的 A2UI(Agent-to-User Interface)协议,正好是冲着这件事来的。这一篇我们就围绕一个问题展开:
Agent 怎样在不下发任何代码的前提下,把一个可交互的原生界面交给用户?
A2UI 到底是什么
A2UI 让 Agent 描述界面,而不是生成界面代码。
- Agent 发什么:一串 JSON 消息。一部分描述组件树(用哪些组件、怎么嵌套),一部分描述数据模型(组件里显示什么值)。
- 客户端做什么:维护一份组件目录(Catalog),把 JSON 里的组件类型映射到自己的原生组件,按数据绑定填值,然后渲染。
- 安全边界:Agent 只能用目录里声明过的组件、属性和函数。目录外的组件在进入界面树之前就会被拦下,并作为错误回报给 Agent。
- 协议管到哪:只规定 Agent 和客户端之间的消息格式与语义(创建 Surface、更新组件、更新数据、删除 Surface,以及客户端回传的点击事件和错误;Surface 就是一块由 Agent 管理的界面,比如聊天里的一张卡片),还有组件目录的描述格式与能力协商。它不规定模型和 Agent 之间怎么输出,也不规定客户端具体有哪些组件、长什么样,传输通道同样不管,只要求消息有序、可靠、边界清楚。
官方的口号是 "safe like data, expressive like code",像数据一样安全,又像代码一样有表达力。
A2UI 解决的主要问题
- 纯文本交互太低效。订餐厅时,Agent 只能一轮轮追问「哪天」「几点」「几位」,用户也只能一句句回。有了界面,Agent 可以直接给出一张带日期选择器、人数输入和提交按钮的表单,一次填完。这是 A2UI 最直接要解决的问题。
- 不让客户端执行模型生成的代码,而是用json模版。最省事的做法是让模型直接写 HTML / JS,但让客户端执行一段谁都没审过的代码,等于把界面注入的口子交给了模型。A2UI 只传声明式的 JSON 数据,客户端只渲染预先批准过的组件,模型写错了最多是某个组件显示不出来,不会执行任何东西。
- 用原生组件渲染。就算把模型生成的 HTML 放进 iframe 或 WebView 里隔离起来,也还有两个问题:加载重;样式、主题、无障碍和 App 对不上,嵌在原生页面里很割裂。A2UI 交给客户端的是组件描述,客户端用自己的原生组件来画,看起来和 App 其他页面是一体的。
- 多端共用一份描述。同一个 Agent 往往要同时服务 Web、Android、iOS。A2UI 让 Agent 只输出一份 JSON,交给各端渲染器各自解释。要说明的是,这省掉的是「每端各定一套协议、Agent 为每端各生成一份」,组件实现和渲染器每端还是要各写一套。
- 支持流式,边生成边显示。模型是一个 token 一个 token 往外吐的,如果界面要等整段生成完才能显示,用户会干等好几秒。A2UI 把组件写成扁平列表、靠 id 互相引用,模型写完一个组件就能发一个,客户端收到一个就能画一个,界面是一点点「长」出来的。后面讲流式生成时会细说。
从商品询问看完整的交互链路
我们用一张最简单的商品卡把整个过程走一遍:用户问「XM6 怎么样」,Agent 回一张卡片,上面有商品图、标题、价格和「查看详情」按钮,点按钮进商品详情页。
先看卡片本身。左边是卡片的样子(示例数据),橙色标签是组件 id;右边是对应的组件树:
卡片外框是 Card,里面一个 Column 从上到下排 4 个子组件。这张图里最值得注意的是按钮:按钮上的文字也是一个单独的 Text,挂在按钮下面,所以一共是 7 个组件。
把这张卡放进完整链路里看:
sequenceDiagram
participant User as 用户
participant App as App(A2UI 渲染器)
participant Agent as Agent 服务端
participant LLM as 模型
participant Tool as 商品工具
User->>App: 1 提问:XM6 怎么样
App->>Agent: 2 用户消息 + supportedCatalogIds
Agent->>LLM: 3 对话 + 工具列表 + 目录 schema
LLM-->>Agent: 4 意图识别后发起工具调用:搜索 XM6
Agent->>Tool: 5 执行搜索
Tool-->>Agent: 6 商品数据:价格、图片、链接
Agent->>LLM: 7 工具结果:商品摘要
LLM-->>Agent: 8 流式输出文字和 updateComponents
Agent->>App: 9 createSurface:读到界面开始标签时
Agent->>App: 10 updateDataModel:商品真值,不经模型
loop 每写完一批组件
Agent->>Agent: 按目录 schema 校验,不合格让模型修正或降级为文字
Agent->>App: 11 updateComponents
end
App->>App: 解析、建树、绑定数据、原生组件渲染
App-->>User: 12 看到商品卡
User->>App: 13 点查看详情
App->>Agent: 14 action:事件名 + context,也可在本地拦截
这里有两个细节我觉得挺重要。
- 能力协商在第 2 步:客户端在请求的 metadata 里带上
supportedCatalogIds,按偏好排序。Agent 从中挑一个目录创建 Surface,这个 Surface 的生命周期内目录不变;一个都不兼容就不发界面。 - 组件和数据走两条线:组件树由模型生成,商品数据由 Agent 拿工具结果直接下发,不经过模型。协议本身不强制这样分,但它把组件和数据分成两种消息,让这种分法很自然。价格这种东西,我是不放心让模型抄一遍的。
模型到底输出什么
在开头部分已经强调过A2UI协议只是规定了Agent和客户端的输出格式,并没有严格约束模型和Agent之间的通信格式。官方 SDK 默认的输出格式叫 direct_json:模型在回复里正常写文字,界面部分写成一个 A2UI 消息的 JSON 列表,用 <a2ui-json> 标签包起来:
好的,这是 XM6 的信息:
<a2ui-json>
[
{"version": "v0.9.1", "updateComponents": {"surfaceId": "pd_1", "components": [
{"id": "root", "component": "Card", "child": "body"},
{"id": "body", "component": "Column", "children": ["img", "title", "price", "btn"]},
{"id": "img", "component": "Image", "url": {"path": "/product/image"}, "fit": "cover"},
{"id": "title", "component": "Text", "text": {"path": "/product/title"}, "variant": "h4"},
{"id": "price", "component": "Text", "text": {"path": "/product/price"}, "variant": "h3"},
{"id": "btn", "component": "Button", "variant": "primary", "child": "btnLabel",
"action": {"event": {"name": "navigate", "context": {"url": {"path": "/product/detailUrl"}}}}},
{"id": "btnLabel", "component": "Text", "text": "查看详情"}
]}}
]
</a2ui-json>
拆开看:
- 标签外的文字原样转发给客户端当普通消息;标签里的 JSON 由 Agent 解析、校验后作为 A2UI 消息发出。
- 扁平列表加 id 引用:子组件不嵌套在父组件里,而是在
child(一个)或children(多个)里写 id,必须有一个组件的 id 是root。扁平结构是流式的前提,后面会看到为什么。 - 属性值有三种写法:直接写值(
"查看详情")、绑定数据路径({"path": "/product/title"})、调用客户端本地函数({"call": "formatCurrency", …})。 - 商品字段只写路径:标题、图片、价格、链接都绑定到
/product/…,模型不写任何商品真值。 - 列表可以写成模板:
children写成{"path": "/items", "componentId": "card"},数组里有几项就渲染几份。
官方示例里,其实是模型把 createSurface、updateComponents、updateDataModel 三条都写了,商品数据也是模型照着工具结果抄进去的。本文采用「商品数据不经模型」的分工:用 SDK 的 allowed_messages 只允许模型写 updateComponents,另外两条由 Agent 代码发。
除了 direct_json,官方 SDK 还有一种类似代码的精简格式 express(如 root = Card(…)),由 SDK 编译成标准消息,但不支持流式;另有实验性的 elemental、atom。据 Express 提案,它针对端侧小模型,自称输出比 JSON 少 55%~70%,但没有给基准数据,这个数字大家看看就好。
模型流式生成,Agent怎么转发和处理
问题来了:模型是一个 token 一个 token 往外吐的,Agent 什么时候发、发多少?
每次只发新写完的组件
Agent 边收边解析模型输出,每到发送时机,就把这段时间里新写完的组件放进一条 updateComponents 发出去,没写完的先不带。所以每条消息带几个组件是不固定的。除了开头那句文字,客户端按顺序收到的 7 条 A2UI 消息如下(一行一条,商品数据为示例):
{"version":"v0.9.1","createSurface":{"surfaceId":"pd_1","catalogId":"https://example.com/catalogs/shopping/v1/catalog.json"}}
{"version":"v0.9.1","updateDataModel":{"surfaceId":"pd_1","path":"/product","value":{"title":"Sony WH-1000XM6 无线降噪耳机","image":"https://…","price":"Rp 4.999.000","detailUrl":"app://product/123"}}}
{"version":"v0.9.1","updateComponents":{"surfaceId":"pd_1","components":[{"id":"root","component":"Card","child":"body"}]}}
{"version":"v0.9.1","updateComponents":{"surfaceId":"pd_1","components":[{"id":"body","component":"Column","children":["img","title","price","btn"]},{"id":"img","component":"Image","url":{"path":"/product/image"},"fit":"cover"}]}}
{"version":"v0.9.1","updateComponents":{"surfaceId":"pd_1","components":[{"id":"title","component":"Text","text":{"path":"/product/title"},"variant":"h4"},{"id":"price","component":"Text","text":{"path":"/product/price"},"variant":"h3"},{"id":"btn","component":"Button","variant":"primary","child":"btnLabel","action":{"event":{"name":"navigate","context":{"url":{"path":"/product/detailUrl"}}}}}]}}
{"version":"v0.9.1","updateComponents":{"surfaceId":"pd_1","components":[{"id":"btnLabel","component":"Text","text":"查看详情"}]}}
{"version":"v0.9.1","updateDataModel":{"surfaceId":"pd_1","path":"/product/price","value":"Rp 4.599.000"}}
按顺序编号成 ① 到 ⑦:
| 消息 | 谁发的 | 内容 |
|---|---|---|
① createSurface | Agent 代码 | 创建 Surface pd_1,指定目录 |
② updateDataModel | Agent 代码 | 工具返回的商品数据 |
③ updateComponents | 模型写,Agent 转发 | [root] |
④ updateComponents | 模型写,Agent 转发 | [body, img] |
⑤ updateComponents | 模型写,Agent 转发 | [title, price, btn] |
⑥ updateComponents | 模型写,Agent 转发 | [btnLabel] |
⑦ updateDataModel | Agent 代码 | 价格变了,只改一个路径 |
一条消息带几个组件,取决于两次发送之间写完了几个:可能就是模型输出到达的节奏,也可能是 Agent 有意攒批,比如距上次发送超过 100ms 才把攒着的一起发。
几条约束要记住:
- 不合格的组件不发:Agent 按目录 schema 校验,不过就让模型修正,或者降级为纯文字。
- 每个组件都要发完整:客户端按 id 整个覆盖,只发改动的属性会把其他属性丢掉。
- 只发增量的前提是传输有序、不丢:长连接中途断了,重连后要补发,或者整块重发这张卡。
Surface 什么时候创建
规范要求 createSurface 必须先于这个 Surface 的组件和数据到达。但模型这一轮可能只回文字,所以 Surface 不能一开始就创建,而是等模型开始写界面时才建:
- 事先分配好 Surface id:在提示词里告诉模型「如果要输出界面,
surfaceId用pd_1」,最好和聊天消息 id 绑定; - 边收边看:Agent 把模型输出交给 SDK 解析的同时自己也检查,一旦读到
<a2ui-json>开始标签,说明模型决定出界面了; - 先创建 Surface、发数据,再转发组件:先发
createSurface,紧接着发updateDataModel,然后才转发模型写的组件。
下面是配合官方 Python SDK 的示意,create_surface、update_data_model、send_to_client 是为了说明流程起的函数名,不是 SDK 原有的 API:
state = RendererState(...) # SDK 的客户端状态镜像
stream = parser.open_stream(wrapped=True, state=state)
buf, created = "", False
async for chunk in llm_stream:
buf += chunk
if not created and "<a2ui-json>" in buf: # 标签可能被切成两段,所以看累计内容
msgs = [create_surface("pd_1", catalog_id),
update_data_model("pd_1", "/product", product)]
state.apply(msgs) # 同步登记,否则 SDK 会拒绝后续更新
send_to_client(msgs)
created = True
for part in stream.feed(chunk): # 文字片段、组件更新都从这里出来
send_to_client(part)
这里最容易踩的坑是 state.apply:createSurface 是 Agent 自己发的,SDK 并不知道。不登记的话,SDK 读到模型写的 pd_1 更新时,会因为「这个 Surface 没创建过」直接拒绝。
如果出不出卡片是代码决定的,也可以提前建。比如商品搜索工具一返回就一定出商品卡,那工具返回时就能创建 Surface、先把数据发过去。另一种思路是给模型一个「展示商品卡」的工具,模型调用它就等于决定出界面,官方 ADK 集成里的 send_a2ui_json_to_client 就是这么做的。
增量和全量
上面的示例每次只发新写完的组件。但官方 SDK 默认不是这样:它每次把这条消息到目前为止的全部组件都带上,官方一致性测试 conformance/agent/direct_json/response_streaming.yaml 的说法是按「当前的样子」重发。同样 4 次发送对比如下:
| 发送 | 增量 | 全量(官方 SDK 默认) |
|---|---|---|
| ③ | [root] | [root] |
| ④ | [body, img] | [root, body, img] |
| ⑤ | [title, price, btn] | [root, body, img, title, price, btn] |
| ⑥ | [btnLabel] | [root, body, img, title, price, btn, btnLabel] |
| 合计发送的组件个数 | 7 | 17 |
全量有冗余,组件越多冗余越大;好处是实现简单,中途丢了一次,下一次会把前面的全部带上。客户端结果是一样的,都是按 id 新增或覆盖:Android 官方库先比较内容,没变的直接跳过;Web 官方核心直接覆盖,重复的组件会重新渲染一次。协议两种都允许,一致性测试约束的是官方 SDK,不是协议本身。
四种服务端消息
到这里,服务端会发的消息就齐了:
| 消息 | 作用 | 关键字段 |
|---|---|---|
createSurface | 创建一个 Surface,指定组件目录 | surfaceId、catalogId、可选 sendDataModel |
updateComponents | 按 id 新增或覆盖组件 | surfaceId、components[],必须有一个 root |
updateDataModel | 写入数据模型 | surfaceId、path(JSON Pointer,缺省为整份)、value(省略即删除) |
deleteSurface | 删除 Surface | surfaceId |
客户端怎么把这些消息画出来
客户端每收到一条,先合并进自己存的组件表(按 id)和数据模型(按路径),界面层再从 root 开始按 id 查表渲染,只刷新受影响的部分,已经画出来的原生视图原地复用。父子关系只存在于父组件的 child / children 里,客户端没有「创建视图再 addView 到父视图」这一步。
一个组件要显示出来,需要满足:
root已经到了,而且从root到它的整条父组件链都到了,否则先存着、不显示;- 它自己的子组件或绑定的数据还没到时,先显示占位,到了再补上。
下图是 ③ 到 ⑦ 每条消息到达后屏幕的样子,橙色框是这一步刚变化的部分:
这张图里最值得注意的有三点:
- 数据可以先到:② 里的商品数据比组件早到,客户端先存着;④ 图片组件一到,绑定的地址已经有了,直接显示。反过来组件先到也行,数据一到自动填上。
- 每步只动一小块:③ 到 ⑥ 每次只有新来的组件从占位变成内容。Android 官方库基于 Compose 的状态机制,组件表按 id 各自是一个可观察状态,只重组读到变化的部分;同一帧收到多条消息,也只合并成一次布局。
- 纯数据变化更轻:⑦ 只改了一个路径,只有绑定
/product/price的文本刷新,组件树完全不变。
反过来说,如果模型先写叶子组件、最后才写 root,前面的组件只能存着,最后一次性出现,逐步长出来的效果就没了。所以提示词里要让模型先写骨架。
客户端要准备什么
- 组件目录:一个
catalogId,加上组件实现和本地函数。可以直接用官方基础组件,也可以加自己的业务组件; - 目录的 JSON Schema:交给服务端,放进提示词或结构化输出约束,模型才知道有哪些组件、各有什么属性;
- 传输层:SSE / WebSocket / A2A 任选,库不自带;
- 上行事件处理:
action发回 Agent,或在本地拦截后走 App 原生流程; - 加载态与错误态:数据没到、组件出错时显示什么。
Android:自定义一个 ProductCard
上面的例子只用了基础组件。实际项目里,我更倾向把整张商品卡做成一个业务组件,模型只输出一个组件,样式由客户端按设计稿实现。下面按 androidx.a2ui 1.0.0-alpha02 文档的 API 写成:
object ProductCardComponent : A2uiComponent {
private val titleProp = A2uiProperty.dynamicString("title", required = true)
private val imageProp = A2uiProperty.dynamicString("imageUrl", required = true)
private val priceProp = A2uiProperty.dynamicString("price", required = true)
private val badgeProp = A2uiProperty.dynamicString("badge")
private val layoutProp = A2uiProperty.stringEnum(
"layout", enumValues = listOf("compact", "large", "horizontal"),
)
private val actionProp = A2uiProperty.action("action", required = true)
override val name = "ProductCard"
// description 会进 schema 给模型看,写清每档用在什么场景
override val description =
"商品卡。compact:横滑列表小卡;large:单品主推大图;horizontal:左图右文"
override val properties =
listOf(titleProp, imageProp, priceProp, badgeProp, layoutProp, actionProp)
// 标题和价格没到之前不渲染,由框架显示加载态
@Composable
override fun A2uiComponentScope.isReady(properties: A2uiComponentProperties) =
properties.bind(titleProp) != null && properties.bind(priceProp) != null
@Composable
override fun A2uiComponentScope.Content(
properties: A2uiComponentProperties,
modifier: Modifier,
) {
val title = properties.bind(titleProp) ?: ""
val image = properties.bind(imageProp)
val price = properties.bind(priceProp) ?: ""
val badge = properties.bind(badgeProp)
val action by rememberUpdatedState(properties[actionProp])
val onClick: () -> Unit = remember { { action?.let { dispatchAction(it) } } }
when (properties[layoutProp] ?: "compact") {
"large" -> ProductCardLarge(title, image, price, badge, onClick, modifier)
"horizontal" -> ProductCardHorizontal(title, image, price, badge, onClick, modifier)
else -> ProductCardCompact(title, image, price, badge, onClick, modifier)
}
}
}
ProductCardCompact 这类函数就是设计系统里普通的 Composable,A2UI 只负责取好属性、绑定好数据,再交给它。用 A2uiProperty 声明的属性,同时也会用来生成给模型看的 schema。
然后注册目录、接消息、挂到页面:
// 基础组件与业务组件放进同一份目录
val shoppingCatalogV1 = A2uiCatalog(
catalogId = "https://example.com/catalogs/shopping/v1/catalog.json",
components = listOf(
MaterialA2uiBasicCatalogV1Defaults.text,
MaterialA2uiBasicCatalogV1Defaults.column, // column / list 的名字按 text / card 的命名推断
MaterialA2uiBasicCatalogV1Defaults.list,
ProductCardComponent,
),
functions = createBasicCatalogFunctions(/* … */), // formatCurrency、openUrl 等
)
class ShoppingAgentViewModel : ViewModel() {
private val parser = A2uiMessageParser()
private val processor = A2uiMessageProcessor(catalogs = listOf(shoppingCatalogV1))
val surfaces: StateFlow<List<A2uiSurfaceModel>> = processor.activeSurfaces
init {
viewModelScope.launch(Dispatchers.Default) { processor.collectMessages() }
viewModelScope.launch(start = CoroutineStart.UNDISPATCHED) {
processor.outboundEvents.collect(::sendToAgent) // action / error 发回 Agent
}
}
// 传输层每收到一行 JSONL 调一次
fun onAgentMessage(json: String) = processor.processInput(parser, json)
}
// 页面里
surfaces.forEach { surface ->
key(surface.id) { A2uiSurface(surfaceModel = surface) }
}
服务端:模型看到的 schema 长什么样
ProductCard 进到模型提示词里的目录片段,结构和官方基础目录一致:
"ProductCard": {
"type": "object",
"allOf": [
{"$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/ComponentCommon"},
{"type": "object",
"properties": {
"component": {"const": "ProductCard"},
"title": {"$ref": "…/common_types.json#/$defs/DynamicString"},
"imageUrl": {"$ref": "…/common_types.json#/$defs/DynamicString"},
"price": {"$ref": "…/common_types.json#/$defs/DynamicString"},
"layout": {"type": "string", "enum": ["compact", "large", "horizontal"]},
"action": {"$ref": "…/common_types.json#/$defs/Action"}
},
"required": ["component", "title", "imageUrl", "price", "action"]}
],
"unevaluatedProperties": false
}
这里有两个容易写错的地方:
- 字段类型要用
DynamicString:它表示可以直接写字符串、绑定数据路径或调用返回字符串的函数。直接写"type": "string"就只能写死,{"path": …}会被判为类型错误。 - 要用
unevaluatedProperties,不能用additionalProperties:allOf表示同时满足公共字段和专属字段;additionalProperties只认同一层列出的属性,会把公共部分的id也当成多余字段。
模型输出不合 schema 时(组件名拼错、多了字段、枚举值不对),服务端发送前就能拦下;漏到客户端的,客户端逐个组件校验,不合格的不显示,并以 VALIDATION_FAILED 回报,让模型自行修正。
基础目录能拼出什么
官方基础目录(v0.9.1)共 18 个组件、14 个函数,可以整份用,也可以只挑一部分:
| 类别 | 组件 / 函数 |
|---|---|
| 布局 | Row、Column、List、Card、Tabs、Modal、Divider |
| 展示 | Text(h1–h5 / body / caption,支持简单 Markdown)、Image、Icon(59 个内置图标名)、Video、AudioPlayer |
| 输入 | Button、TextField、CheckBox、ChoicePicker、Slider、DateTimeInput |
| 校验函数 | required、regex、length、numeric、email |
| 格式化函数 | formatString、formatNumber、formatCurrency、formatDate、pluralize |
| 动作与逻辑 | openUrl、and、or、not |
所有组件都有 id、component、accessibility;Row / Column 的直接子组件可以写 weight,类似 CSS flex-grow;输入组件和 Button 还有 checks 校验规则,Button 任一条件不满足时自动禁用,可以用来做「表单填对才能提交」。
Row / Column 的 justify 取 start / center / end / spaceBetween / spaceAround / spaceEvenly / stretch,align 取 start / center / end / stretch,一看就是照 CSS 弹性布局定义的。
基础目录里没有的东西同样值得注意:没有 Grid、Table、叠放(类似 Compose 的 Box、SwiftUI 的 ZStack)、单独的滚动容器;也没有任何内外边距、宽高、颜色、字号属性,这些数值由各端渲染器自己定。
协议只保证结构一致,不保证像素一致
这里必须分清两个容易混在一起的概念:结构一致和效果一致。
协议保证的是同一棵组件树、同一份目录 schema,所以组件类型、属性名、枚举值、必填项、嵌套关系各端一致。但布局属性只给语义,目录说明原文是 "similar to the CSS 'align-items' property",间距、圆角、尺寸这些数值由各端自己定。
那各端实际实现得怎么样?我对照三端官方源码整理了一张表:Android 是 androidx.a2ui 的 Material 3 实现,iOS 是官方仓库里还没发布的 SwiftUI 实现,Web 以 Angular 渲染器为准。「有」是平台有现成的控件或属性,「凑」是平台没有、靠别的方式模拟:
| A2UI 布局 | Android(Compose) | iOS(SwiftUI) | Web(Angular) |
|---|---|---|---|
| Row / Column | 有:Row / Column | 有:HStack / VStack | 有:display: flex |
| List | 有:LazyColumn / LazyRow | 有:ScrollView + LazyVStack | 有:弹性布局加滚动 |
| Card | 有:Surface | 凑:VStack 加圆角背景 | 凑:div 加圆角阴影 |
| Tabs | 有:PrimaryTabRow + Tab | 凑:自绘按钮条 | 凑:自绘 |
| Modal | 有:BasicAlertDialog,居中 | 有:.sheet,底部弹层 | 凑:遮罩加居中弹窗 |
justify 三种 space | 有:Arrangement.SpaceBetween 等 | 凑:插 Spacer,spaceAround 做成了 spaceEvenly | 有:justify-content |
justify: stretch | 凑:每个子项 weight(1) | 凑:子项宽度无限大 | 不生效(等于 start) |
align: stretch | 凑:fillMaxHeight / fillMaxWidth | Column 凑;Row 没实现 | 有:align-items: stretch |
weight | 有:Modifier.weight(w) | 凑:不按比例,Column 里忽略 | 有:flex: w |
归纳下来,官方实现里结果和协议不一致的有五处:
- Android 的 Row / Column 不写
align时按start处理,而协议缺省是stretch,子项不撑满; - iOS 的
weight不按比例(1 和 2 分到一样宽),Column 里直接忽略; - iOS 的 spaceAround 做成了 spaceEvenly;
- iOS Row 的
align: stretch不拉伸; - Web 的
justify: stretch不生效。
另外 Modal 在 Android、Web 是居中弹窗,在 iOS 是底部弹层,这是语义差异。
Web 对得最齐,因为协议本来就照 CSS 定义;Android 只缺拉伸对齐,显式写 align 就没问题;iOS 的 SwiftUI 栈天生没有分布方式和比例权重,凑得最不完整。说得直接一点:A2UI 帮你省掉的是「多端各写一套协议」,不是「多端各调一遍 UI」。
点一下按钮会发生什么
action 只有两种写法
Button 的 action 只有两种:event 发事件,functionCall 调函数。
// 发事件:交给 Agent,或被客户端拦截
"action": {"event": {"name": "showSimilar", "context": {"itemId": {"path": "/item/id"}}}}
// 调函数:执行客户端注册过的函数
"action": {"functionCall": {"call": "openUrl", "args": {"url": {"path": "/item/detailUrl"}}}}
context 和 args 里的值可以是常量,也可以绑定数据路径,点击时由客户端解析成实际值。比如前面商品卡点「查看详情」,客户端发出的消息是(信封格式为示意):
{"version":"v0.9.1","action":{"name":"navigate","surfaceId":"pd_1","sourceComponentId":"btn","timestamp":"2026-10-22T08:15:30Z","context":{"url":"app://product/123"}}}
五种处理方式
两种写法落到客户端,实际有五种处理方式:
| 方式 | 写法 | 谁处理 | 适合 |
|---|---|---|---|
| 事件发回 Agent | event | Agent 当作一轮新输入,回新的组件或数据 | 换一批、按预算重新推荐、帮我选一款 |
| 事件本地拦截 | event | 客户端按事件名处理,不发给 Agent | 看详情、加购、分享 |
| 调本地函数 | functionCall | 客户端执行目录里声明过的函数 | 同上,且需要参数校验 |
| 输入绑定加校验 | 输入组件 value 绑定路径,checks 写校验 | 客户端本地读写数据模型 | 选规格、预算滑块、收货信息 |
| 函数级远程调用(v1.0) | callAgentFunction / callRendererFunction | 一方调另一方的函数并等返回值 | 查库存、校验优惠码 |
确定性动作没必要回 Agent 走一轮模型。Android 上用拦截器在本地消费掉:
// 拦截器返回 null 表示消费掉,不再发给 Agent
val interceptor = A2uiActionInterceptor { action ->
if (action is A2uiEventAction && action.eventName == "openProduct") {
navigator.openProduct(action.context["itemId"] as String)
null
} else action
}
val processor = A2uiMessageProcessor(catalogs = listOf(catalog), interceptors = listOf(interceptor))
不过事件名只是客户端和 Agent 的口头约定,schema 校验不到。我更推荐长期用本地函数:在目录里声明函数名和参数 schema(如 openProductDetail(itemId)、addToCart(itemId, qty)),双端各实现一份(Android 实现 A2uiFunction.execute,iOS 实现 FunctionImplementation)。函数签名会随目录进入提示词,参数能被校验,比事件名约定更不容易写错。
输入框里打的字,什么时候到 Agent
输入组件的 value 绑定数据路径,用户输入立即写回本地数据模型,绑定同一路径的 Text 随之刷新,比如滑块拖到 500,旁边的「预算 ¥500」同步变化:
{"id": "email", "component": "TextField", "label": "Email", "value": {"path": "/form/email"},
"checks": [{"call": "email", "args": {"value": {"path": "/form/email"}}, "message": "邮箱格式不对"}]},
{"id": "submit", "component": "Button", "child": "submit-label",
"checks": [{"condition": {"call": "required", "args": {"value": {"path": "/form/email"}}}, "message": "请填写邮箱"}],
"action": {"event": {"name": "submitForm", "context": {"email": {"path": "/form/email"}}}}}
但协议规定双向绑定只在客户端本地,打字、勾选不会触发任何网络请求,数据只在触发 action 时回传,有两种方式:
- 事件里按字段带:
context引用数据路径,只发引用到的字段; - 附带整份数据模型:
createSurface设sendDataModel: true,之后客户端发给该 Agent 的每条消息,都在传输层元数据里附上该 Surface 的整份数据,格式为{"surfaces": {"s1": {...}}}。
第二种在聊天场景特别有用。用户经常填完卡片不点按钮,直接在输入框里说「就按这个来」,开了 sendDataModel,Agent 照样能拿到卡片上填的内容。
v1.0 的函数级远程调用
callAgentFunction:客户端调 Agent 侧函数并等返回值,期间组件显示加载态。它可以写在属性绑定和checks里,比如一段 Text 绑定checkCoupon(code)的返回值,输完优惠码就显示是否可用;Agent 侧直接执行工具,不经过模型。callRendererFunction:Agent 调客户端函数,比如读位置、读购物车数量,前提是目录里把该函数的allowedCallers设为agentOnly或rendererOrAgent。
官方 Swift 核心库已实现这两种消息;androidx.a2ui 1.0.0-alpha02 只支持 v0.9 目录,还不支持。
A2UI 客户端的架构分层
把前面几节串起来看,一个 A2UI 客户端从上到下可以分成几层。三端的分层是一样的,差别只在每一层用哪个库。下图按谁来写上色:橙色是服务端写,绿色是库提供,灰色是 App 自己写;虚线框是三端协议引擎的共同职责:
协议引擎这一层(解析消息、schema 校验、组件表和数据模型、从 root 建树、判断就绪)其实和平台无关。如果你的 App 已经在用 KMP,很容易想到把它放进共享层,组件目录和 Surface 容器留在原生。但现成的库是各管一端的:androidx.a2ui 的发布说明里没看到 iOS 目标,a2ui-swift 自带一套 Swift 引擎。所以现实的选择是两端各用各的库,或者在 KMP 里自研引擎、两端只写组件映射。iOS 如果是 UIKit 页面,用 SwiftUI 渲染 A2UI 的 Surface 再嵌进去会比自己实现「组件表 + 从 root 比对更新」省事得多。
动态性的边界:哪些能直接做,哪些必须发版
A2UI 本质上也是一种动态化:服务端下发描述、客户端预置组件,只不过描述的生产者从运营配置变成了模型。之前写 Tangram 那篇时聊过粗粒度动态化,判断标准是一样的:
一个需求要不要发版,只看客户端已经发版的组件能不能表达它。
按这个标准,需求分成三类:
- 换档位,不用发版:在组件预留的几档里选,比如多款推荐用横滑小卡、只聊一款用大图卡,只改服务端提示词里的选择规则。
- 换组合,不用发版:用现有组件拼一棵新树。比如两款对比,两张
ProductCard用Row并排,下面放一段差异总结和一个「帮我选一款」按钮。这几个组件都在目录里,服务端在提示词里描述版式、处理新事件就行。 - 加新行为,必须发版:比如商品卡上每秒跳一次的秒杀倒计时。协议只传数据,没有定时器,服务端也不可能每秒推一次,只能客户端新做一个组件、目录升版本。老版本 App 不认识新属性,这张卡会校验失败、直接不显示,所以服务端要看客户端声明的
supportedCatalogIds,确认对方支持再发。
两款对比渲染出来大概是这样(商品为示例数据):
除了倒计时,下面这些 A2UI 也做不到,只能提前做进客户端:
- 新的交互和逻辑:动画、手势,以及「先校验、再提交、再跳转」这种多步编排和条件分支。一个 action 只能是一个事件或一个函数调用,协议里没有表达式,社区一直有呼声,官方目前还没加。
- 目录外的平台能力:支付、相册、分享,要预置成组件或本地函数,或者通过 action 交回原生流程。
- 像素级样式:颜色、间距、字号由各端渲染器决定,想控制只能在自定义目录里开放受设计系统约束的档位。
- 下发代码或 HTML:这是协议的安全前提,真要这么做只能走 WebView 或 MCP Apps,安全模型完全不同。
所以我的建议是:高频卡片做成大组件,保证视觉统一;长尾版式用小组件来拼;倒计时、轮播这类行为做成通用组件,一次发版长期复用。
最后说一下平台支持。截至本文写作时,Web(React、Lit、Angular)和 Flutter 有官方的稳定渲染器;Android 官方的 Jetpack Compose 渲染器 androidx.a2ui 还在 Alpha(1.0.0-alpha02);iOS 官方的 SwiftUI 渲染器还在开发、没有发布,现在能用的是社区的 a2ui-swift;另外高德开源的 AGenUI 同时覆盖 iOS、Android 和鸿蒙。所有实现都还在 1.0 之前:协议当前正式版是 v0.9.1,v1.0 还在候选阶段,现在接入要接受 API 会变。
写到最后
回到开头的问题:Agent 怎样在不下发任何代码的前提下,把一个可交互的原生界面交给用户?
客户端先声明自己有哪些组件,Agent 只用这些组件拼一棵扁平的树、把数据单独下发,客户端边收边按 id 合并、用原生组件渲染;点击要么本地处理,要么作为新一轮输入回到 Agent。
客户端声明 supportedCatalogIds
→ 模型按目录 schema 流式写 updateComponents
→ Agent 校验、创建 Surface、下发真值数据
→ 客户端按 id 合并组件表和数据模型,从 root 增量渲染
→ 用户点击:本地拦截 / 本地函数 / 回 Agent 再来一轮
组件目录就是 Agent 的界面权限边界:目录里有的,模型可以随意组合;目录里没有的,模型永远碰不到。
所以,A2UI 不是一个「让模型随便画界面」的方案,而是一个「让模型在你画好的格子里排版」的方案。它真正省掉的是多端协议和每次改版式的发版,代价是新行为仍然要发版、多端 UI 仍然要各自调。对现在就想接入的同学,还要接受 1.0 之前 API 会变。
下一篇打算把视线转到 ChatGPT 这边:同样是让 Agent 出界面,它的做法和 A2UI 有什么不同?
参考资料
- A2UI 官网
- A2UI 规范 v0.9.1 · v1.0 候选版
- Catalogs 概念 · 组件参考 · Basic Catalog JSON
- 渲染器开发指南 · 客户端接入
- 官方渲染器列表 · 社区渲染器列表
- Android:Compose Agentic UI · 自定义组件 · 目录 · 渲染 surface
- androidx.a2ui.compose 发布页 · androidx.a2ui 发布页
- a2ui-swift · Flutter GenUI · Lynx GenUI:A2UI
- Google Developers Blog:Introducing A2UI
- CopilotKit:A2UI · CrewAI:A2UI