快速开始：5 分钟运行 A2UI¶

通过运行餐厅查找器演示来亲手体验 A2UI。本指南将让你在不到 5 分钟内体验智能体生成的 UI。

你将构建什么¶

在本快速开始结束时，你将拥有：

✅ 一个运行中的带有 A2UI Lit 渲染器的 Web 应用
✅ 一个生成动态 UI 的 Gemini 驱动智能体
✅ 一个具有表单生成、时间选择和确认流程的交互式餐厅查找器
✅ 理解 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 应用中，尝试这些提示：

“预订 2 人桌” - 观看智能体生成预订表单
“在我附近找意大利餐厅” - 查看动态搜索结果
“你们的营业时间是什么？” - 体验不同意图的不同 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

这运行一个仅限客户端的演示，展示每个标准组件（Card、Button、TextField、Timeline 等）及其实时示例和代码样本。

联系人查找演示¶

尝试不同的智能体用例：

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 .

仍然有问题？¶

检查 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，这些 UI 在 Web 应用中原生渲染——所有这些都通过安全的声明式 JSON 消息实现。