Google A2UI 极简教程(按当前生产版 v0.9.1)

https://github.com/a2ui-project/a2ui

先对齐版本,这是最容易踩坑的地方:官网当前把 v0.9.1 标为生产版(Current),v1.0 仍是候选版(Release Candidate)——规范页最后更新 2026-06-08,2026-08-06 的 Roadmap 仍写 Candidate,尚无正式 GA 公告。 另外要分清两套编号:协议是 v0.9.1,Python Agent SDK 是包版本(公开记录近期为 0.8.0 / 2026-10-08),别把 SDK 的 0.8.0 当成协议 v0.8。

1. 一句话讲清它是什么

A2UI 不是 UI 组件库,是一份声明式 JSON 协议:Agent 不吐 HTML/JS 代码,只说"我要一张卡片、一个按钮、绑定这些数据";客户端拿自家设计系统里的白名单组件渲染成原生界面。安全边界始终在客户端。

2. 四个概念、四条消息

概念作用
surface一块独立界面容器
components扁平邻接表,靠 id 引用子节点,必须有 id: "root" 作为入口
data model独立的数据层,用 JSON Pointer(/msg)绑定
action用户点击后回传给 Agent

v0.9+ 只有四条消息,JSONL 一行一条,边生成边渲染:createSurface → updateComponents → updateDataModel → deleteSurface。

3. 最小可跑的 JSONL

{"version":"v0.9.1","createSurface":{"surfaceId":"demo","catalogId":"https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"}}
{"version":"v0.9.1","updateComponents":{"surfaceId":"demo","components":[{"id":"root","component":"Column","children":["msg"]},{"id":"msg","component":"Text","text":{"path":"/msg"}}]}}
{"version":"v0.9.1","updateDataModel":{"surfaceId":"demo","path":"/msg","value":"Hello, A2UI!"}}

第三行之后想改文案,只需再发一条 updateDataModel 改 /msg,不用重建组件树。收尾发 {"version":"v0.9.1","deleteSurface":{"surfaceId":"demo"}}。

4. 五分钟跑官方 Demo

依赖:Node.js + Corepack/Yarn、Python 3.10+ 与 uv、一个 Gemini API Key。

git clone https://github.com/a2ui-project/a2ui.git && cd a2ui
export GEMINI_API_KEY="你的key"

# 终端 A:Agent 后端
cd samples/agent/adk/restaurant_finder && uv run .

# 终端 B:Lit 前端(默认 http://localhost:5173)
cd samples/client/lit && corepack enable && yarn install && yarn demo:restaurant

5. 接进自己的 Agent(ADK / Python)

pip install a2ui-agent-sdk
from a2ui.core.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
from google.adk.agents.llm_agent import LlmAgent

sm = A2uiSchemaManager(catalogs=[BasicCatalog.get_config(examples_path="examples")])
instruction = sm.generate_system_prompt(
    role_description="You are a helpful assistant that presents information with rich UI.",
    include_schema=True, include_examples=True,
)
agent = LlmAgent(model="gemini-flash-latest", name="ui_agent", instruction=instruction)

关键是别把 LLM 裸输出直接丢给前端:用 SDK 的 parse_response_to_parts(...)(配合 catalog 的 validator)做校验/修复,再以 A2UI Part 流式发回。 Schema Manager 会自动按客户端能力协商版本,也能钉死 version=VERSION_0_9。 客户端侧官方维护 Lit / Angular / React / Flutter 渲染器,Web 端用共享的 web_core 处理协议层。

6. 三个坑,比教程本身更值钱

  1. 别抄 v0.8 的消息名。surfaceUpdate / dataModelUpdate / beginRendering 是 v0.8 遗产,v0.9 起已换成 createSurface / updateComponents / updateDataModel / deleteSurface,网上不少中文教程把两代混着写,照抄必挂。
  2. 全链路锁同一版本族:Agent SDK、Schema、catalogId、示例、渲染器要对齐;v0.9.1 统一媒体类型为 application/a2ui+json,旧教程里的 application/json+a2ui 是草案写法。 仓库也已迁到 a2ui-project/a2ui,老地址是历史版本。
  3. 只信数据,不信意图:Agent 只能请求 catalog 里批准的组件,未知组件直接拒绝;用户点"Approve"也只是个请求,后端必须重新鉴权,UI 载荷一律当不可信输入处理。

版本怎么选

生产就钉 v0.9.1。想尝 v1.0,隔离在兼容边界里试:它新增 actionResponse / 双向函数调用、单条消息即可建面,并调整了主题字段,线格式与 v0.9.1 有 breaking change,别提前承诺兼容。

官方入口:a2ui.org(规范与版本状态)、a2ui.org/quickstart、github.com/a2ui-project/a2ui。


Google A2UI 目前有两个“最新”版本在并行推进,理解这一点是开始使用的关键:v0.9.1 是当前的生产可用版本,而 v1.0 是功能更新的候选版本,为未来的稳定版做准备。

下面是一个极简教程,帮你快速上手。

📌 先明确:你应该用哪个版本?

版本状态说明
v0.9.1当前生产版推荐用于学习和生产环境,是 v0.9 的 refinement,稳定可靠。
v1.0候选版引入了双向 RPC 等新特性,适合想尝鲜或评估未来特性的开发者。
v0.8旧版已过时,主要作兼容性参考。

对于大多数教程和SDK,默认的目标版本通常是 v0.9.x。


🚀 极简上手路径:两条路可选

路径一:5分钟跑通演示(推荐首选)

这是感受 A2UI 工作方式最快的方法。官方提供了一个“餐厅查找器”演示,你可以直接运行它。

第1步:准备环境
你需要:

  • uv(Python 包管理器):用于运行后端智能体。
  • Gemini API Key:从 Google AI Studio 免费获取。

第2步:克隆仓库并设置密钥

# 克隆官方仓库(假设你使用a2ui-project/a2ui)
# 设置你的 Gemini API 密钥
export GEMINI_API_KEY="你的密钥"

第3步:运行
仓库通常会提供一键启动脚本或清晰的启动命令(具体请参考仓库根目录的 README)。启动后,打开浏览器访问本地地址(如 http://localhost:4200)即可看到界面。

第4步:体验
在网页中尝试输入:

“Book a table for 2” 或 “Find Italian restaurants near me”

你会看到,界面(如预订表单、餐厅列表)是由背后的 Gemini 智能体实时生成的,而非前端写死的静态页面。

路径二:用 ADK 构建你自己的智能体(Python)

如果你想创建自己的 A2UI 智能体,官方的 A2UI Agent SDK 配合 Google ADK(Agent Development Kit) 是最直接的路径。

第1步:安装 SDK

pip install a2ui-agent-sdk

第2步:核心三步:管理 Schema → 生成提示词 → 创建智能体

from a2ui.core.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
from google.adk.agents.llm_agent import LlmAgent

# 1. 初始化 Schema Manager(它会加载组件目录)
schema_manager = A2uiSchemaManager(
    catalogs=[BasicCatalog.get_config(examples_path="examples")]
)

# 2. 生成系统提示词(将 A2UI 的“语法”和示例教给 LLM)
instruction = schema_manager.generate_system_prompt(
    role_description="你是一个 helpful assistant,用丰富的 UI 呈现信息。",
    workflow_description="分析用户请求,在合适时返回结构化的 UI。",
    ui_description="用 Card 做摘要,用 Table 做对比,用 Form 做输入。",
    include_schema=True,
    include_examples=True,
    allowed_components=["Heading", "Text", "Card", "Button", "Table"],
)

# 3. 创建 ADK 智能体
agent = LlmAgent(
    model="gemini-flash-latest",
    name="ui_agent",
    instruction=instruction,
)

第3步:验证与流式输出
SDK 提供了工具来确保 LLM 生成的 JSON 符合 A2UI 规范,然后将其包装成可流式传输的格式。

from a2ui.core.parser.parser import parse_response
from a2ui.a2a import parse_response_to_parts

# 假设 llm_output_text 是智能体的原始文本输出
# 一次性完成解析、验证并转换为传输格式
parts = parse_response_to_parts(
    llm_output_text,
    validator=schema_manager.get_selected_catalog().validator,
    fallback_text="这是我找到的信息。",
)

现在,你的智能体就能生成 UI 描述,并通过 A2A 等传输协议发送给客户端了。


🧩 核心概念速览

掌握以下三点,就能理解 A2UI 的运作逻辑:

  1. 声明式 JSON:智能体不发送 HTML 或可执行代码,而是发送描述“意图”的 JSON(例如 {"type": "Form", "props": {"fields": [...]}})。
  2. 客户端渲染:客户端(Web、Flutter、Android 等)有自己的渲染器(Renderer),它解析 JSON,并用原生的组件(如 Material Design 组件)来构建 UI。智能体不控制外观,外观由你的设计系统决定。
  3. 组件目录(Catalog):渲染器只识别预先批准的组件。智能体必须从客户端支持的组件目录(如基础的 Text, Card, Button)中选择,这保证了安全性。

🛠️ 常用工具与渲染器

  • 渲染器(Renderer):官方提供了 Lit(Web 组件)、Flutter、Angular 等实现。Android 开发者可以使用 Jetpack Compose A2UI 渲染器(当前版本 1.0.0-alpha02)。
  • A2UI Composer:一个在线工具,可以让你用自然语言描述一个 UI,然后实时查看它生成的 JSON 和渲染效果,非常适合调试和学习。
  • GitHub 仓库:所有代码、规范、示例都在 a2ui-project/a2ui。

💎 总结

上手 A2UI 的最短路径是:先跑通 5 分钟演示建立直观感受,然后参照 ADK 的代码示例,用 A2UI Agent SDK 在 Python 中创建你的第一个能“说话”并生成界面的智能体。

Logo

更多推荐