A2UI 1.0 详解:让 AI 生成 Flutter 界面,还不怕它乱写
# 一、前言
在 App 里接入 AI 助手,最常见的做法还是聊天框:用户问一句,模型回一大段文字。可一旦涉及数据和操作,这种交互就很别扭。比如问「我这个月哪类支出最多」,答案埋在一段话里的第三行;想把订单里某个币的数量改一下,还得再打一句「把 SOL 改成 22 个」,然后等模型慢慢回。
Flutter 团队这次给出的解法是生成式 UI(Generative UI,下文简称 GenUI):智能体不回文字,而是直接回一个真实的 Flutter 界面,能点、能改、能滑。

11 月 17 号 A2UI 1.0 正式发布,原来的 genui 包也改名成了 a2ui_flutter。这篇从上手讲起,再把五个新能力逐个拆开,其中「层级护栏」会用一个单测把两层校验跑一遍。看完你能知道:
GenUI适合用在哪,不适合用在哪;- 最小可运行的
a2ui_flutter代码怎么写,和官方博客的示例有什么出入; 1.0的五个新能力分别解决什么问题,其中护栏的部分附上真实运行输出。
# 1、先别急着全换成 GenUI
官方博客里有个观点我很认同:GenUI 不是用来替换你的常规页面的。
| 维度 | 传统界面 | GenUI |
|---|---|---|
| 适合的问题 | 流程固定,如表单、列表、导航 | 要先推理、答案因人而异的开放问题 |
| 速度 | 直接渲染,最快 | 要等模型生成 |
| 可预测性 | 完全可控 | 靠组件目录和校验兜底 |
| 开发成本 | 每个场景都要写一个页面 | 写好组件,组合交给智能体 |
官方的餐饮示例 Commis 很能说明问题:主人说客人对贝类过敏,问菜单要不要改。智能体先确认现有菜单是安全的,再生成一个只包含无贝类菜品的勾选清单让你换。应用里根本不需要专门做一个「过敏原筛选」的设置项。

反过来,如果一个静态表单已经能把事情办得很好,那就继续用表单,没必要为了 AI 而 AI。
# 2、包的拆分
这次不只是改了个名,原来的 genui 被拆成了三个包(截至 2026-11-18,a2ui_flutter 最新是 0.4.0,依赖 a2ui_core ^0.8.0):
| 包 | 职责 |
|---|---|
a2ui_core | 处理 A2UI 消息,保存每个界面(Surface)的状态,MessageProcessor 就在这里 |
a2ui_flutter | 把界面渲染成 Flutter 组件,自带基础组件目录 |
a2ui_agent | 跑在 App 或 Dart 服务端,负责提示模型写 A2UI,再解析它的回复 |

和旧版 genui 相比,概念也精简了:
旧版 genui | A2UI 1.0 | 变化 |
|---|---|---|
Transport | 删除 | 不再绑定包里的传输抽象,SSE、WebSocket、HTTP 随你挑 |
SurfaceController + Conversation | MessageProcessor | 一个类管组件目录、校验消息和界面状态 |
Catalog、Surface、Data Model | 保留,能力变多 | 支持层级护栏、多目录、扩展元数据 |
删掉 Transport 这个改动很实在。接入 AI 的项目,传输层基本都是早就有的,硬要套一层包自带的抽象,反而难受。
# 二、跑起来
# 1、安装
flutter pub add a2ui_flutter a2ui_core
# 2、最小示例
先不接模型,手写两条消息喂给 MessageProcessor,看界面能不能出来:
class _HelloA2uiState extends State<HelloA2ui> {
final processor = MessageProcessor<ComponentImplementation>(
catalogs: [basicCatalog()],
);
SurfaceModel<ComponentImplementation>? surface;
void initState() {
super.initState();
// 收到 createSurface 后拿到界面模型
processor.model.onSurfaceCreated.subscribe(
(created) => setState(() => surface = created),
);
// 用户点了按钮,这里能收到动作
processor.model.onAction.subscribe(
(action) => debugPrint('Action: ${action.name}'),
);
// 实际项目里,这两条消息来自智能体
processor.processMessages([
{
'version': '1.0',
'createSurface': {
'surfaceId': 'hello',
'catalogId': BasicCatalog.v1_0Id,
},
},
{
'version': '1.0',
'updateComponents': {
'surfaceId': 'hello',
'components': [
{'id': 'root', 'component': 'Column', 'children': ['greeting', 'button']},
{'id': 'greeting', 'component': 'Text', 'text': 'Hello, A2UI!'},
{
'id': 'button',
'component': 'Button',
'child': 'label',
'action': {'event': {'name': 'greet'}},
},
{'id': 'label', 'component': 'Text', 'text': 'Say hi'},
],
},
},
]);
}
Widget build(BuildContext context) {
final surface = this.surface;
return Scaffold(
body: surface == null ? null : A2uiSurface(surface: surface),
);
}
}
这里有两个点要说一下。
第一,组件是一个扁平列表,不是嵌套的树。id 为 root 的是根节点,其它组件通过 children 或 child 按 id 引用。这样设计对流式生成很友好,模型吐出一个组件,客户端就能先存一个,不用等整棵树闭合。
第二,基础组件是 Material 组件,所以界面要放在 MaterialApp 下面,并且外层要有 Material,比如 Scaffold 的 body。
# 3、和官方博客示例的出入
官方博客讲多组件目录时,示例代码是这样的:
final processor = MessageProcessor(
catalogs: [
CommonCatalog(),
HealthWidgetsCatalog(),
CustomChartCatalog(),
],
);
照着抄会发现 CommonCatalog 找不到。以 0.4.0 为准,基础目录是 a2ui_flutter/basic_catalog.dart 里的 basicCatalog() 函数,MessageProcessor 来自 a2ui_core,并且需要带上泛型 MessageProcessor<ComponentImplementation>。博客里那段更像是伪代码,理解意思就好,真写的时候以 pub.dev 上的 README 为准。
# 三、五个新能力
# 1、层级护栏:按钮里别塞表格
给模型的自由太少,它没法因人而异地组织界面;给得太多,它可能发现 Button 能接一个 child,就往里塞一个 DataTable。

1.0 的做法是在组件目录里加 allowedParents 和 allowedChildren 两个字段,并且两头都管:

- 这两个字段是组件目录
schema的一部分,会进到智能体的提示词里,模型一开始就知道哪些嵌套是合法的; - 客户端在构建组件之前会再校验一遍,模型就算写错了也不会渲染出坏掉的界面,而是把错误回传给智能体。
光看图没感觉,直接写个单测验证。自定义一个 MyButton,只允许放在 Row、Column 里,只允许包含 Text、Icon:
final myButton = ComponentImplementation(
name: 'MyButton',
schema: Schema.object(properties: {
'child': Schema.fromMap({r'$ref': r'common_types.json#/$defs/ComponentId'}),
}),
allowedParents: ['Row', 'Column'],
allowedChildren: ['Text', 'Icon'],
builder: stub,
);
然后创建两个界面,一个合法(Column > MyButton > Text),一个故意在 MyButton 里塞 DataTable,并通过 outboundListener 把回传给智能体的消息打印出来:
final processor = MessageProcessor<ComponentImplementation>(
catalogs: [
CatalogImplementation(
id: catalogId,
protocolVersion: A2uiProtocolVersion.v1_0,
components: [BasicComponents.column, BasicComponents.text, myButton, dataTable],
definitions: BasicComponents.api.definitions,
),
],
defaultVersion: A2uiProtocolVersion.v1_0,
outboundListener: (m) => outbound.add(RendererToAgentMessagePayload.of(m).toJson()),
);
// 非法:MyButton 里塞 DataTable
send('bad', [
{'id': 'root', 'component': 'Column', 'children': ['btn']},
{'id': 'btn', 'component': 'MyButton', 'child': 'table'},
{'id': 'table', 'component': 'DataTable'},
]);
flutter test 的输出:
合法界面创建成功
code: UNALLOWED_CHILD
path: /components/1/child
message: Container 'btn' (MyButton) cannot contain child 'table' (DataTable). Allowed children: ['Text', 'Icon'].
outbound: [{messages: [{version: 1.0, error: {code: UNALLOWED_CHILD, surfaceId: bad, message: Container 'btn' (MyButton) cannot contain child 'table' (DataTable). Allowed children: ['Text', 'Icon']., path: /components/1/child}}]}]
schema: {type: object, properties: {child: {$ref: common_types.json#/$defs/ComponentId}}, allowedParents: [Row, Column], allowedChildren: [Text, Icon]}
00:00 +1: All tests passed!
两层都对上了:
- 最后一行是
catalog.toJson()里MyButton的定义,allowedParents和allowedChildren原样带上了,这份就是要给模型看的组件目录; - 非法嵌套被拦下,错误码是
UNALLOWED_CHILD,path用JSON Pointer精确指到了第 2 个组件的child字段,并且这条错误通过outboundListener发回了智能体,模型可以据此改了重来。
这里有个坑:processMessages 在校验失败时会直接抛出 A2uiValidationError,回传给智能体的同时,调用方也要自己 catch,不然会一路往上抛。另外,a2ui_core 0.8.0 的基础目录里,Button、Row 这些基础组件默认没有写这两个字段,想要约束,得在自己的组件目录里加。
# 2、Express 格式:少吐点 token
界面是边生成边显示的,模型每多吐一个 token,用户就多等一会。标准 JSON 里有大量重复的引号、括号、id 和 component 字段,都是开销。
Express 推理格式把同一棵组件树改写成函数调用的样子:

按官方给的例子,同样五个组件,Express 比压缩过的 JSON 少了 46% 的字符。官方博客里还提到一个医疗原型 GenUI Clinic:根据病人的病史和就诊原因,生成一份只读的临床简报。换成 Express 后,整屏看板的生成时间从 10 秒降到了 5 秒。

这两个数字是官方和合作方的测试结果,实际收益会因模型和组件数量而不同。不过思路很好理解:模型只负责输出紧凑的写法,由智能体 SDK 编译成标准的 A2UI 消息,App 这边完全无感。
# 3、多组件目录:各管各的
0.9 时一个 Surface 只能绑一个 Catalog,基础组件和业务组件只能手动合并成一个大目录。1.0 里一个界面可以混用多个目录:

final processor = MessageProcessor<ComponentImplementation>(
catalogs: [
basicCatalog(),
healthWidgetsCatalog, // 业务团队维护
customChartCatalog, // 图表团队维护
],
);
catalogs 是有优先级顺序的,排在前面的优先。对团队协作来说,这个改动很实用:平台团队维护基础布局组件,业务团队各自发布自己的组件目录,互不干扰。
# 4、callAgentFunction:不是每次点击都要问模型
生成出来的界面里,点击其实分两种:
| 操作 | 例子 | 该怎么处理 |
|---|---|---|
| 开放式点击 | 点一下图表的柱子、点一个追问的提示 | 是个新问题,发起新一轮对话,让模型推理 |
| 确定性点击 | 调步进器、拖滑块、改筛选 | 结果是算出来的,不该等模型几秒 |

callAgentFunction 就是给第二种准备的:组件直接调用智能体后端暴露的确定性函数,后端算完把数据直接写回当前组件,全程不经过大模型。
官方博客里的例子是 Somnio Software 的开源投资组合助手:用户让它把 1 万美元分配到 BTC、ETH、SOL 上,生成一张草稿订单卡片。点步进器上的加号调整 SOL 数量时,订单卡片通过 callAgentFunction 直接调后端,权重、手续费、剩余现金在一秒内原地更新,不用开新的一轮对话。
这让生成的界面从「答案的一张截图」变成了真正能用的工具,我觉得是这次更新里最有用的一个能力。
# 5、扩展元数据:把链路串起来
生产环境经常需要在 A2UI 消息旁边带点额外信息,比如路由标记、样式提示、安全上下文,或者用来关联日志的追踪令牌。

1.0 支持在界面、组件、组件目录定义和动作上挂元数据。Python 后端可以这样写:
CreateSurface(
surface_id="my_surface",
catalog_id="https://example.com/catalog.json",
metadata={
"extensions": {
"com_example_logging": {"token": "ABC123"}
}
},
)
Flutter 端在界面或组件模型上读 metadata 就能拿到。排查问题时,从后端哪个智能体生成了界面,到用户在 App 里点了什么,可以用同一个令牌串起来,这对多智能体的后端来说很重要。
# 四、最后
# 1、智能体用什么写
a2ui_flutter 只负责渲染,智能体那边有三种语言的 SDK,都能驱动同一个 Flutter 应用:
| 语言 | 包 | 搭配 |
|---|---|---|
Dart(新) | a2ui_agent | Genkit Dart,它的 genkit_a2ui 中间件目前还是预览版 |
Python | a2ui-agent-sdk | a2ui-adk 对接 Google ADK,a2ui-a2a 对接 A2A 协议 |
TypeScript | @a2ui/agent | Node.js,也可以配合 CopilotKit |

对 Flutter 开发者来说,最有吸引力的是全 Dart 这条路:智能体、工具和界面全用一门语言写。Very Good Ventures 就用这套做了一个开源的智能家居面板,后端是 Dart Frog 加 a2ui_agent 和 Genkit Dart,挂在厨房墙上,给每个家庭成员生成不同的看板。
# 2、注意项
- 版本:本文基于
a2ui_flutter 0.4.0和a2ui_core 0.8.0,包还在快速迭代,API以pub.dev为准; - 官方博客的部分示例代码是示意,类名和实际包不完全一致;
- 层级护栏要自己在组件目录里声明,校验失败时
processMessages会抛异常,记得处理; Express和callAgentFunction的性能数字来自官方和合作方,接入自己的模型后要实测。
# 3、资料
- 快速上手和协议文档:a2ui.org (opens new window)
a2ui_flutter:pub.dev/packages/a2ui_flutter (opens new window)Flutter AI与GenUI示例:g.dev/ai/flutter-demos (opens new window)- 智能家居面板源码:a2ui_vgv_smart_home (opens new window)

- 01
- 拿竞品 App 一扫,技术栈全暴露了😂11-15
- 03
- 从代码复用走向生态:Flutter Dart Package 实战全指南08-28