教程2026-11-20 · 智涌AI

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

A2UI 协议入门头图:左侧大字 A2UI 协议入门与 1.0 首个稳定版、6 种官方渲染器、3 种 Agent SDK 语言三张数据卡,右侧四步流程图:catalog.json 登记组件、模型写 Express 由 SDK 编译校验、updateComponents 用原生控件渲染、用户点按钮后 action 回传 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 到按钮点击

官方概念页拿订机票举例,整条链路是这样的:

  1. 生成 Skill。Agent SDK 读取 catalog.json,生成一个 A2UI Skill,里面是提示词说明、语法规则和每个组件的签名,比如 FlightCard(flightNumber, origin, destination, price, passengers)。
  2. 模型输出。你的 Agent 先调自己的业务工具查航班,再带着 Skill 调模型。模型不直接写线上 JSON,而是写一种更紧凑的格式 A2UI Express,例如 $/outbound/pax = 1 加一行 root = Card(Column([...]))。
  3. 编译校验。SDK 边收边解析,检查每个组件是否在目录里、属性是否符合 schema,出错当场报告,然后发出 createSurface(开一块界面)、updateComponents(组件列表)、updateDataModel(初始数据)。
  4. 客户端渲染。渲染器把扁平的组件列表按 ID 拼成树,用原生控件画在一块叫 surface 的区域里,绑定了 {"@path": "/outbound/pax"} 的属性会随数据更新。
  5. 用户操作。点「+」改乘客数只改本地数据模型,不发给 Agent;点「确认预订」才发一条 action 消息,带上解析后的上下文,比如 {"outboundPax": 2, "returnPax": 2}。

消息可以走 AG-UI、A2A、MCP 或 WebSocket,协议本身不绑传输方式。

组件目录就是护栏:Agent 只能用你登记过的组件,目录外的东西到不了用户屏幕。

1.0 改了什么

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 入门。

常见坑

完成标准

如果你的场景是网页本身给 Agent 提供工具,而不是 Agent 回界面,看站内的 WebMCP 上手教程;Vercel 的 UI SDK 则是另一种让 Agent 写组件的思路。

最后

先把 Travel A2UI 跑起来,盯着 Wire 页看一次模型输出怎么变成消息,再挑自己 App 里最常被问的一个场景,整理出 3 到 5 个组件写进 catalog。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。