A2UI 快速上手完整指南：让 AI Agent 自动生成界面的开源协议-开发者社区

A2UI 快速上手完整指南：让 AI Agent 自动生成界面的开源协议

【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui

你想让 AI 应用拥有真正的交互界面，却不想为前端开发再雇一个人、再排一个季度的期？A2UI（Agent to User Interface）为此而生：它是一套开放标准加配套库，让 AI Agent 直接"说 UI"——Agent 输出一段描述界面意图的声明式 JSON，你的客户端用自己的原生组件把它渲染出来。下面这份指南带你从原理到跑通示例，完整走一遍 A2UI 的核心链路。

A2UI 的核心主张只有一句话：Agent 生成的界面，要像数据一样安全，又像代码一样 expressive（表达力强）。

A2UI 能为你解决什么问题

A2UI 不是一种 UI 框架，而是一个"界面传输协议"。Agent 负责生成，客户端负责渲染，中间靠 JSON 消息流动。拆开看，它给你提供了四层能力：

声明式 JSON 消息，替代不可信代码

让 LLM 直接生成 HTML/JavaScript 塞进 iframe，是安全审查的噩梦。A2UI 把界面变成纯数据：一条createSurface创建画布，updateComponents描述组件，updateDataModel填充状态。客户端不执行任何远程代码，只解析 JSON 并映射到本地组件。协议细节可以顺着 specification/ 目录逐版本（v0.8、v0.9、v1.0）查看。

客户端组件目录（Catalog）：安全边界由你掌控

客户端应用维护一份"可信组件清单"，Agent 只能请求渲染目录里存在的组件（Card、Button、TextField 等），无法凭空注入任意内容。目录本身也是声明式的 JSON，官方基础目录在 specification/v1_0/catalogs/basic/，你还能按自定义目录指南定义自己的组件集，把"信任阶梯"写进自己的业务里。

扁平组件列表 + 数据绑定：为 LLM 和流式渲染设计

组件用扁平列表加 ID 引用来表达层级，而不是嵌套树。这种结构让 LLM 更容易逐条增量生成，也让客户端可以边收边渲染、局部更新。数据绑定通过 JSON Pointer 路径（如/reservation/date）把组件和状态解耦，Agent 更新数据后界面自动响应。概念详解见 docs/public/concepts/。

一套 JSON，多端渲染

同一条 Agent 响应可以在 Lit、React、Angular（Web）和 Flutter（移动/桌面/Web）上渲染，Swift 渲染器也已提供核心实现。renderers/ 目录里每个渲染器都是独立工程，完整渲染器清单还列出了社区贡献的版本。

一条真实链路：餐厅查找器是怎么跑起来的

仓库里最能说明问题的示例是餐厅查找与订座 Agent（samples/agent/adk/restaurant_finder/），它是官方 Quickstart 的主角。整条链路是这样的：

你输入什么：在 Lit 客户端里输入"Book a table for 2"，或"Find me an Italian restaurant"。

项目如何处理：Python 侧的 ADK Agent 收到消息后把对话交给 Gemini，由模型生成 A2UI JSON 消息流，再通过 A2A 协议流式回传给客户端。生成的消息大致长这样（v0.9.1）：

{ "version": "v0.9.1", "createSurface": { "surfaceId": "main", "catalogId": ".../basic/catalog.json" } } { "version": "v0.9.1", "updateComponents": { "surfaceId": "main", "components": [ { "id": "header", "component": "Text", "text": "# Book Your Table", "variant": "h1" }, { "id": "date-picker", "component": "DateTimeInput", "value": { "path": "/reservation/date" }, "enableDate": true }, { "id": "submit-btn", "component": "Button", "child": "submit-text", "action": { "event": { "name": "confirm_booking" } } } ] } } { "version": "v0.9.1", "updateDataModel": { "surfaceId": "main", "path": "/reservation", "value": { "date": "2025-12-15", "time": "19:00", "guests": 2 } } }

你最终得到什么：渲染器解析这些消息，用原生组件画出一张订座表单，填好日期、时间、人数；你点"Confirm"后，用户操作被打包成userAction消息回传 Agent，Agent 再流式推送下一轮更新。整个过程中餐厅列表、订座流程、确认页面全部由 LLM 现场生成，客户端源码里没有任何硬编码的界面。

注意一个容易忽略的细节：界面的"长什么样"由客户端目录决定，Agent 只能决定"用哪些组件、填什么数据"。所以换个渲染器，同一份 JSON 会呈现出完全不同的原生风格。

三步跑通示例

你只要做这几件事（以 Lit 客户端为例）：

准备环境：Node.js 18+（开启 Corepack）、Python 包管理器 uv、一个 Gemini API Key。
克隆并启动：
```
git clone https://gitcode.com/GitHub_Trending/a2/a2ui cd a2ui export GEMINI_API_KEY="your_gemini_api_key" corepack enable yarn install cd samples/client/lit yarn demo:restaurant
```
demo:restaurant会同时拉起 Python Agent（等价于在 samples/agent/adk/restaurant_finder/ 下执行uv run .）和 Lit 客户端，浏览器打开http://localhost:5173即可。
换句话试试：把"Find Italian restaurants near me"换成任意需求，观察不同意图如何映射到不同的界面布局。

更完整的分步说明在 Quickstart 文档，Agent 侧开发见 Agent 开发指南。

不想装环境？仓库里的 A2UI Composer 是一个可视化编辑器，用自然语言描述就能生成 A2UI JSON，再粘贴进任意 Agent 的提示词里。

过来人视角：设计与避坑

首屏报ERR_CONNECTION_REFUSED不用慌。Web 客户端往往比 Python Agent 先启动完，这是已知的竞态，等几秒刷新即可。
端口被占用会自动顺延。5173 被占用时 dev server 会换下一个端口，以终端实际打印的 URL 为准。
API Key 报错先自查：echo $GEMINI_API_KEY确认已导出，且用的是有效的 Gemini Key。
生产环境把外部 Agent 当不可信输入。示例的 README 安全声明写得很直白：外部 Agent 的字段、UI 定义、数据流都可能携带注入或伪造内容，务必做输入清洗、CSP、嵌入内容隔离。A2UI 的目录机制降低了风险面，但没有取消你的验证责任。
别把它当成完整前端框架。A2UI 刻意不追求强大的样式系统——样式归客户端所有，Agent 只描述结构、状态与交互意图。如果你的场景需要像素级视觉控制，那应该是"自定义目录 + 自定义组件"的路子，而不是指望协议本身。

调试时可以从两个方向入手：用浏览器开发者工具观察 SSE 消息流，逐条对照消息参考；或对照 specification/v1_0/test/cases/ 里的协议测试用例，理解每条消息的合法形态。

生态与走向

A2UI 目前是早期公开预览：生产可用的版本是 v0.9.1，v1.0 规范已是发布候选，v0.8 作为遗留版本继续保留。路线图的方向大致有四条：规范走向 v1.0 稳定、补齐 SwiftUI 与 Jetpack Compose 官方渲染器、增加 REST 等传输方式、接入更多 Agent 框架（Genkit、LangGraph 等）。社区侧已经有 React Native、Android Compose、跨平台原生等第三方渲染器在跟进。

它也在往 MCP 生态延伸，MCP Apps 集成指南演示了让 MCP 服务返回 A2UI 界面的玩法。