快速入门：5 分钟运行 A2UI¶

通过运行餐厅查找演示亲身体验 A2UI。本指南将让您在不到 5 分钟的时间内体验代理生成的 UI。

您将构建什么¶

在本快速入门结束时，您将拥有：

✅ 一个运行中的带有 A2UI Lit 渲染器的 Web 应用程序
✅ 一个由 Gemini 驱动的生成动态 UI 的代理
✅ 一个交互式的餐厅查找器，具有表单生成、时间选择和确认流程
✅ 了解 A2UI 消息如何从代理流向 UI

先决条件¶

在开始之前，请确保您拥有：

Node.js (v18 或更高版本) - 在此下载
Gemini API 密钥 - 从 Google AI Studio 免费获取

安全提示

此演示运行一个使用 Gemini 生成 A2UI 响应的 A2A 代理。该代理有权访问您的 API 密钥，并将向 Google 的 Gemini API 发出请求。在生产环境中运行之前，请务必审查代理代码。

第 1 步：克隆仓库¶

git clone https://github.com/google/a2ui.git
cd a2ui

第 2 步：设置您的 API 密钥¶

将您的 Gemini API 密钥导出为环境变量：

export GEMINI_API_KEY="your_gemini_api_key_here"

第 3 步：导航到 Lit 客户端¶

cd samples/client/lit

第 4 步：安装并运行¶

运行一键演示启动器：

npm install
npm run demo:all

此命令将：

安装所有依赖项
构建 A2UI 渲染器
启动 A2A 餐厅查找代理（Python 后端）
启动开发服务器
在浏览器中打开 http://localhost:5173

演示正在运行

如果一切正常，您应该在浏览器中看到 Web 应用程序。代理现在已准备好生成 UI！

第 5 步：试用¶

在 Web 应用程序中，尝试这些提示：

"Book a table for 2" - 观看代理生成预订表单
"Find Italian restaurants near me" - 查看动态搜索结果
"What are your hours?" - 体验针对不同意图的不同 UI 布局

幕后发生了什么¶

┌─────────────┐         ┌──────────────┐         ┌────────────────┐
│  您输入消息  │────────>│   A2A 代理   │────────>│   Gemini API   │
│             │         │   (Python)   │         │     (LLM)      │
└─────────────┘         └──────────────┘         └────────────────┘
                               │                         │
                               │ 生成 A2UI JSON           │
                               │<────────────────────────┘
                               │
                               │ 流式传输 JSONL 消息
                               v
                        ┌──────────────┐
                        │   Web 应用   │
                        │ (A2UI Lit    │
                        │   渲染器)    │
                        └──────────────┘
                               │
                               │ 渲染原生组件
                               v
                        ┌──────────────┐
                        │   您的 UI    │
                        └──────────────┘

您发送消息通过 Web UI
A2A 代理接收消息并将对话发送给 Gemini
Gemini 生成描述 UI 的 A2UI JSON 消息
A2A 代理流式传输这些消息回 Web 应用程序
A2UI 渲染器将它们转换为原生 Web 组件
您看到 UI在您的浏览器中渲染

A2UI 消息剖析¶

让我们看看代理发送了什么。这是 JSON 消息的简化示例：

定义 UI¶

{
  "surfaceUpdate": {
    "surfaceId": "main",
    "components": [
      {
        "id": "header",
        "component": {
          "Text": {
            "text": {"literalString": "Book Your Table"},
            "usageHint": "h1"
          }
        }
      },
      {
        "id": "date-picker",
        "component": {
          "DateTimeInput": {
            "label": {"literalString": "Select Date"},
            "value": {"path": "/reservation/date"},
            "enableDate": true
          }
        }
      },
      {
        "id": "submit-btn",
        "component": {
          "Button": {
            "child": "submit-text",
            "action": {"name": "confirm_booking"}
          }
        }
      },
      {
        "id": "submit-text",
        "component": {
          "Text": {"text": {"literalString": "Confirm Reservation"}}
        }
      }
    ]
  }
}

这定义了表面的 UI 组件：文本标题、日期选择器和按钮。

填充数据¶

{
  "dataModelUpdate": {
    "surfaceId": "main",
    "contents": [
      {
        "key": "reservation",
        "valueMap": [
          {"key": "date", "valueString": "2025-12-15"},
          {"key": "time", "valueString": "19:00"},
          {"key": "guests", "valueInt": 2}
        ]
      }
    ]
  }
}

这填充了组件可以绑定的数据模型。

信号渲染¶

{"beginRendering": {"surfaceId": "main", "root": "header"}}

这告诉客户端它有足够的信息来渲染 UI。

只是 JSON

注意它是多么易读和结构化？LLM 可以轻松生成它，并且传输和渲染是安全的——无需代码执行。

探索其他演示¶

仓库包含其他几个演示：

组件库（无需代理）¶

查看所有可用的 A2UI 组件：

npm start -- gallery

这运行一个仅客户端的演示，展示每个标准组件（卡片、按钮、文本字段、时间轴等），并带有实时示例和代码示例。

联系人查找演示¶

尝试不同的代理用例：

npm run demo:contact

这演示了一个生成搜索表单和结果列表的联系人查找代理。

下一步是什么？¶

现在您已经看到了 A2UI 的实际应用，您可以准备：

学习核心概念：了解表面、组件和数据绑定
设置您自己的客户端：将 A2UI 集成到您自己的应用中
构建代理：创建生成 A2UI 响应的代理
探索协议：深入了解技术规范

故障排除¶

端口已被占用¶

如果端口 5173 已被占用，开发服务器将自动尝试下一个可用端口。检查终端输出以获取实际 URL。

API 密钥问题¶

如果您看到有关缺少 API 密钥的错误：

验证密钥已导出：echo $GEMINI_API_KEY
确保它是来自 Google AI Studio 的有效 Gemini API 密钥
尝试重新导出：export GEMINI_API_KEY="your_key"

Python 依赖项¶

演示使用 Python 作为 A2A 代理。如果您遇到 Python 错误：

# 确保已安装 Python 3.10+
python3 --version

# 演示应通过 npm 脚本自动安装依赖项
# 如果没有，请手动安装：
cd ../../agent/adk/restaurant_finder
pip install -r requirements.txt

仍有问题？¶

查看 GitHub Issues
查看 samples/client/lit/README.md
加入社区讨论

理解演示代码¶

想看看它是如何工作的？查看：

代理代码：samples/agent/adk/restaurant_finder/ - Python A2A 代理
客户端代码：samples/client/lit/ - 带有 A2UI 渲染器的 Lit Web 客户端
A2UI 渲染器：web-lib/ - Web 渲染器实现

每个目录都有自己的 README，其中包含详细文档。

恭喜！ 您已成功运行第一个 A2UI 应用程序。您已经看到了 AI 代理如何生成丰富、交互式的 UI，并在 Web 应用程序中原生渲染——所有这些都通过安全、声明式的 JSON 消息实现。