A2UI 是什么:让 Agent 用你的组件回一张界面

问 Agent「下周五和朋友吃饭,帮我挑个时间订位」,回来的往往是一大段编号文字,改一项还得再聊一轮。谷歌 11 月 11 日(美国时间)发布了 A2UI 1.0,这是它的生成式 UI 开放协议的第一个稳定版:Agent 不写 HTML,只用 JSON 描述「这里放一张航班卡、那里放一个确认按钮」,你的 App 用自己的原生组件画出来。下面按官方文档讲它怎么工作、本地怎么跑起来、接进自己项目时要注意什么。
A2UI 是什么:Agent 描述界面,App 负责画
A2UI(Agent to UI)是一套开源的生成式 UI 框架,仓库在 GitHub 的 a2ui-project/a2ui,Apache-2.0 许可,11 月 20 日查看时有 17,675 颗星。它由三部分组成:一份协议,规定 Agent 和客户端之间传哪些 JSON 消息;服务端的 Agent SDK,有 Python、TypeScript、Dart 3 种语言;客户端渲染器,官方共 6 个:Web 端 React、Angular、Lit,移动端 Flutter、SwiftUI、Jetpack Compose。
核心是组件目录 catalog.json。你把 App 里已有的组件登记进去,每个组件的属性用 JSON Schema 写清楚。Agent 生成界面时只能用目录里的组件,目录外的东西会在到达屏幕前被拦下。官网的说法是传输的始终是声明式 JSON 数据,不是可执行代码,所以界面风格和安全边界都握在 App 自己手里。
谷歌博客列了几个已在用的团队:Atlassian 让 Jira 里的 Agent 用交互卡片向团队追问细节;字节跳动 6 月给跨端框架 Lynx 发布了 A2UI 渲染器,目前支持 0.9;Gemini 已经能渲染企业注册的 A2UI Agent,当前支持 0.9.1。
一次请求怎么走:从 catalog 到按钮点击
官方概念页拿订机票举例,整条链路是这样的:
- 生成 Skill。Agent SDK 读取
catalog.json,生成一个 A2UI Skill,里面是提示词说明、语法规则和每个组件的签名,比如FlightCard(flightNumber, origin, destination, price, passengers)。 - 模型输出。你的 Agent 先调自己的业务工具查航班,再带着 Skill 调模型。模型不直接写线上 JSON,而是写一种更紧凑的格式 A2UI Express,例如
$/outbound/pax = 1加一行root = Card(Column([...]))。 - 编译校验。SDK 边收边解析,检查每个组件是否在目录里、属性是否符合 schema,出错当场报告,然后发出
createSurface(开一块界面)、updateComponents(组件列表)、updateDataModel(初始数据)。 - 客户端渲染。渲染器把扁平的组件列表按 ID 拼成树,用原生控件画在一块叫 surface 的区域里,绑定了
{"@path": "/outbound/pax"}的属性会随数据更新。 - 用户操作。点「+」改乘客数只改本地数据模型,不发给 Agent;点「确认预订」才发一条
action消息,带上解析后的上下文,比如{"outboundPax": 2, "returnPax": 2}。
消息可以走 AG-UI、A2A、MCP 或 WebSocket,协议本身不绑传输方式。
组件目录就是护栏:Agent 只能用你登记过的组件,目录外的东西到不了用户屏幕。
1.0 改了什么
- 双向函数调用。按钮、校验、绑定值都可以用
@call调函数。App 里有这个函数就在本地执行,没有就通过callAgentFunction交给 Agent,比如订位界面当场查余位,不用开新一轮对话。0.9.1 里函数只能在渲染器本地跑。 - 单条消息建界面。
createSurface可以直接内联components和dataModel,catalogId变成可选,0.9.1 的theme属性去掉,样式交给宿主 App。 - 无障碍和扩展元数据。协议加了无障碍支持,扩展信息放在
metadata.extensions。 - 版本字段。1.0 消息里写
"version": "1.0",旧版是"v0.9"。从 0.9 升级看官方的 evolution guide。
Flutter 这边,原来的 genui 包改名为 a2ui_flutter,去掉了 Transport 抽象,SurfaceController 和 Conversation 合并成一个 MessageProcessor。
本地跑起官方示例
快速上手用的是 A2UI Labs 里的 Travel A2UI:一个 Python 服务端放 Agent,React 和 Flutter 两个客户端负责画。官方写明它只用来学习,不适合生产。环境要求 Python 3.11+、Node 20+(Web 端)、Flutter 3.38+(移动端)。
git clone https://github.com/a2ui-project/labs
cd labs/samples/travel-a2ui
./scripts/quickstart.sh both # 只要 Web 写 react,只要移动端写 flutter
curl -s http://127.0.0.1:8080/api/healthz # 返回 {"ok":true,...} 说明服务起来了
脚本会把服务端装进 .venv、构建客户端,然后在 8080 端口启动。Web 端开 http://127.0.0.1:8080,没有 API Key 也能看一段录好的示例行程;要和 Agent 对话,需要在页面里贴一个 AI Studio 的免费 Gemini Key,官方说明 Key 只存在浏览器里。Web 端建议点开两个标签:Catalog 页列出 Agent 能用的全部组件,Wire 页把模型写的 Express 和客户端收到的消息并排显示。Flutter 端在 /flutter/,是按手机布局编译的 Web 版。
不想克隆代码,还有两条路:在自己项目里跑 npx skills add a2ui-project/a2ui,给编程 Agent 装上 A2UI 的协议规则和集成指南;或者直接打开浏览器里的 A2UI Playground 试提示词和组件目录。
A2UI、MCP Apps 和生成代码怎么选
| 方式 | Agent 产出 | 优点 | 代价 |
|---|---|---|---|
| 预置组件 | 挑一个现成组件填数据 | 完全受控 | 没预料到的需求只能回文字 |
| A2UI 组合 | 用目录组件拼界面 | 原生渲染,跨 Web 和移动端 | 要先维护组件目录 |
| 生成代码 | HTML/JS 跑在沙箱里 | 能做地图、3D 等定制画面 | 脱离设计系统,只限 Web/WebView |
这三种可以混用。谷歌说 Web 和 Flutter 渲染器可以跑在 MCP App 里,让 A2UI 界面出现在 Claude、Gemini 这类支持 MCP Apps 的助手中;反过来,生成的 HTML 也能作为 MCP App 嵌进 A2UI 界面。MCP Apps 本身怎么做,可以看站内的 MCP Apps 入门。
常见坑
- 平台版本没对齐。Jetpack Compose 渲染器目前还是 0.9.1,Gemini 渲染也是 0.9.1,Lynx 还在 0.9。要上这些平台,先确认对方支持的版本,别直接发 1.0 消息。
- 把固定界面也交给 Agent。官方的经验是:每轮都一样的部分(顶栏、输入框、聊天气泡)写成普通 App 代码,随用户请求变化的部分才让 Agent 组合。
- 目录写得太粗。Agent SDK 靠目录里的 schema 和描述生成 Skill、做校验。属性描述写得含糊,模型就更容易填错属性。
- 以为数据都要过模型。博客提到 A2UI 可以在服务端把数据和子组件绑定好,敏感值不用经过模型。界面里要显示的账户信息这类数据,按这个思路走数据模型绑定。
完成标准
- Travel A2UI 跑起来,
/api/healthz返回 ok,能在 Wire 页看到createSurface和updateComponents。 - 知道自己 App 的哪些组件要进 catalog,每个属性都有 schema 和描述。
- 用户点按钮后,服务端能收到
action消息并读到context。 - 确认目标平台渲染器支持的协议版本。
如果你的场景是网页本身给 Agent 提供工具,而不是 Agent 回界面,看站内的 WebMCP 上手教程;Vercel 的 UI SDK 则是另一种让 Agent 写组件的思路。
最后
先把 Travel A2UI 跑起来,盯着 Wire 页看一次模型输出怎么变成消息,再挑自己 App 里最常被问的一个场景,整理出 3 到 5 个组件写进 catalog。