基于ADK Agents与A2UI协议的生成式UI:消息与示例
了解 A2UI 如何让智能体以 JSON 格式返回交互式用户界面,它与 AG-UI 有何不同,以及如何在本地运行 Google ADK 餐厅查找器示例。
来源: Agent to UI Protocol (A2UI) with Agent Development Kit (ADK)
当智能体被集成到实际应用中时,有四种协议会频繁出现:MCP、A2A、A2UI和AG-UI。AG-UI用于连接前端应用与智能体后端,且与谷歌的Agent Development Kit(ADK)配合得很好。此处重点介绍的是名称极为相似、容易混淆的A2UI,以及如何从ADK智能体中驱动它。
A2UI是什么
A2UI是谷歌推出的一种生成式用户界面协议。它能够让AI智能体创建丰富的交互式界面,这些界面可以展示在网页、手机和桌面设备上。例如,当用户询问“纽约有哪些不错的餐厅?”时,智能体不仅可以返回文本列表,还可以提供界面的描述,客户端上的渲染器会将该描述转化为餐厅的交互式展示。
其核心概念在a2ui.org上有详细文档,要点仅需几段文字即可说明清楚。
四种消息类型
代理发送的所有内容均为 JSON 格式,且仅有四种类型的消息:
createSurface用于创建新表面,并指定其所使用的组件目录。updateComponents用于在表面内添加或修改 UI 组件。updateDataModel用于更改应用程序状态。deleteSurface用于删除某个表面。
这四种消息共同描述了界面及其背后的数据结构:
{
"version": "v0.9",
"createSurface": {
"surfaceId": "main",
"catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
}
}
{
"version": "v0.9",
"updateComponents": {
"surfaceId": "main",
"components": [...]
}
}
{
"version": "v0.9",
"updateDataModel": {
"surfaceId": "main",
"path": "/user",
"value": { "name": "Alice" }
}
}
组件目录
A2UI 提供一个按用途分类的标准目录:
- 布局类:用于排列其他组件的行、列和列表组件
- 显示类:用于呈现信息的文本、图片、图标、视频和分隔线组件
- 交互类:用于接收输入的按钮、文本字段、复选框、日期时间输入框和滑块组件
- 容器类:用于组合内容的卡片、标签页和模态框组件
文档中的组件参考部分包含了带有示例的完整图集。
预订对话,逐条消息展示
文档中的餐厅预订示例很好地展示了整个生命周期。
首先,客服人员创建一个对话界面:
{
"version": "v0.9",
"createSurface": {
"surfaceId": "booking",
"catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
}
}
其次,它定义了用户界面的结构:
{
"version": "v0.9",
"updateComponents": {
"surfaceId": "booking",
"components": [
{
"id": "root",
"component": "Column",
"children": ["header", "guests-field", "submit-btn"]
},
{
"id": "header",
"component": "Text",
"text": "Confirm Reservation",
"variant": "h1"
},
{
"id": "guests-field",
"component": "TextField",
"label": "Guests",
"value": { "path": "/reservation/guests" }
},
{
"id": "submit-btn",
"component": "Button",
"child": "submit-text",
"variant": "primary",
"action": {
"event": {
"name": "confirm",
"context": {
"details": { "path": "/reservation" }
}
}
}
}
]
}
}
第三,它填充数据:
{
"version": "v0.9",
"updateDataModel": {
"surfaceId": "booking",
"path": "/reservation",
"value": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "2"
}
}
}
第四,用户将客人数量改为3,客户端会自动更新/reservation/guests。第五,用户点击确认后,客户端会返回操作结果:
{
"version": "v0.9",
"action": {
"name": "confirm",
"surfaceId": "booking",
"context": {
"details": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "3"
}
}
}
}
第六,代理会通过再次更新用户界面或关闭该界面来作出响应:
{
"version": "v0.9",
"deleteSurface": { "surfaceId": "booking" }
}
传输与渲染
A2UI 不关心消息的传输方式,只要能传递 JSON 即可。目前支持 A2A 和 AG-UI 作为传输方式,而 REST、WebSockets 和 SSE 则处于规划或提议阶段。文档中的传输页面列出了当前支持的方式。
当代理生成 JSON 后,渲染器会将其转换为原生组件。在网页端,有 Lit 和 Angular 渲染器;Flutter 的 GenUI SDK 则可用于移动端、桌面端和网页端。渲染器页面会更新维护中的列表。
A2UI 与 AG-UI 对比
两者名称相近,功能不同但相互补充。AG-UI 是面向用户的应用与代理后端之间的连接层;A2UI 则是一种声明式规范,供代理在响应中返回 UI 组件使用。
尝试示例
A2UI 仓库包含了可在本地生成和渲染的 ADK 代理示例。请先克隆它:
git clone https://github.com/google/a2ui.git
cd a2ui
设置 Gemini API 密钥:
export GEMINI_API_KEY="your_gemini_api_key_here"
每个示例都包含服务器端部分(即代理)和客户端部分(即渲染器),这两者都需要处于运行状态。ADK 代理示例位于 samples/agent 下的 adk 文件夹中,而客户端渲染器则位于 samples/client 中。
餐厅查找器
在 samples/client/lit 文件夹中,通过一条命令即可启动演示:
npm run demo:restaurant
打开 http://localhost:5173/?app=restaurant,然后开始提出查询,例如“纽约排名前五的中餐馆”。代理会生成用户界面,客户端则负责渲染它:
日志中显示了代理发送的原始 A2UI JSON 数据:
[REST] LiteLLM completion() model= gemini-2.5-flash; provider = gemini
[REST] INFO:agent:Event from runner: model_version='gemini-2.5-flash' content=Content(
[REST] parts=[
[REST] Part(
[REST] text="""<a2ui-json>
[REST] [
[REST] {
[REST] "beginRendering": {
[REST] "surfaceId": "default",
[REST] "root": "root-column",
[REST] "styles": {
[REST] "primaryColor": "#FF0000",
[REST] "font": "Roboto"
[REST] }
[REST] }
[REST] },
[REST] {
[REST] "surfaceUpdate": {
[REST] "surfaceId": "default",
[REST] "components": [
[REST] {
[REST] "id": "root-column",
[REST] "component": {
[REST] "Column": {
[REST] "children": {
[REST] "explicitList": [
[REST] "title-heading",
[REST] "item-list"
[REST] ]
[REST] }
[REST] }
[REST] }
[REST] },
...
内部运作机制
智能体代码位于 samples/agent/adk/restaurant_finder 中。prompt_builder.py 展示了如何构建提示语,从而使智能体以 A2UI 格式回复。角色描述开头会明确要求最终输出必须是 A2UI JSON 格式的响应:
ROLE_DESCRIPTION = (
"You are a helpful restaurant finding assistant. Your final output MUST be a a2ui"
" UI JSON response."
)
UI_DESCRIPTION = """
- If the query is for a list of restaurants, use the restaurant data you have already received from the `get_restaurants` tool to populate the `dataModelUpdate.contents` array (e.g., as a `valueMap` for the "items" key).
- If the number of restaurants is 5 or fewer, you MUST use the `SINGLE_COLUMN_LIST_EXAMPLE` template.
- If the number of restaurants is more than 5, you MUST use the `TWO_COLUMN_LIST_EXAMPLE` template.
- If the query is to book a restaurant (e.g., "USER_WANTS_TO_BOOK..."), you MUST use the `BOOKING_FORM_EXAMPLE` template.
- If the query is a booking submission (e.g., "User submitted a booking..."), you MUST use the `CONFIRMATION_EXAMPLE` template.
"""
A2uiSchemaManager 类负责加载组件目录,并生成用于指导模型理解有效 A2UI JSON 格式的系统提示。调用 generate_system_prompt 函数后,会将智能体的角色描述与架构以及若干示例结合在一起,从而为模型提供精确的格式指导:
version = VERSION_0_9
restaurant_prompt = A2uiSchemaManager(
version,
catalogs=[
BasicCatalog.get_config(
version=version,
examples_path=f"examples/{version}",
)
],
schema_modifiers=[remove_strict_validation],
).generate_system_prompt(
role_description=ROLE_DESCRIPTION,
ui_description=UI_DESCRIPTION,
include_schema=True,
include_examples=True,
validate_examples=True,
)
agent.py 会使用该系统提示语来创建智能体:
return LlmAgent(
model=LiteLlm(model=LITELLM_MODEL),
name="restaurant_agent",
description="An agent that finds restaurants and helps book tables.",
instruction=instruction,
tools=[get_restaurants],
)
在代理发出 JSON 后,应在将其流式传输给客户端之前,根据 A2UI 架构进行验证:
# --- Validation Steps ---
# Check if it validates against the A2UI_SCHEMA
# This will raise jsonschema.exceptions.ValidationError if it fails
logger.info(
"--- RestaurantAgent.stream: Validating against A2UI_SCHEMA... ---"
)
selected_catalog.validator.validate(parsed_json_data)
ADK文档中有一个A2UI集成页面,提供了更详细的说明。在客户端,renderers/lit目录中包含了Lit实现,该实现能够接收生成的JSON数据并将其渲染出来。
入门工具
CopilotKit提供了A2UI启动模板,以及用于组件实验的A2UI Composer。
值得继续阅读的资源包括A2UI协议文档和规范、GitHub仓库、Google关于代理驱动界面的公告文章、ADK集成页面、CopilotKit Composer和启动模板,还有几段关于代理实时构建UI的YouTube视频。