首页 / 文章

基于ADK Agents与A2UI协议的生成式UI:消息与示例

了解 A2UI 如何让智能体以 JSON 格式返回交互式用户界面,它与 AG-UI 有何不同,以及如何在本地运行 Google ADK 餐厅查找器示例。

发布者:REACTAPP.TOP阅读约 6 分钟1361 词

来源: 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视频。