A2UI快速入门
A2UI, a streaming protocol for Agent-Driven User Interfaces
通过运行餐厅查找器演示程序，亲身体验 A2UI。本指南将帮助您在 5 分钟内体验到智能代理生成的用户界面。
你将建造什么
完成本快速入门指南后，您将掌握：
- ✅ 一个正在运行的带有 A2UI Lit 渲染器的 Web 应用程序
- ✅ 一款基于 Gemini 的代理，可生成动态用户界面
- ✅ 具有表单生成、时间选择和确认流程的交互式餐厅查找器
- ✅ 了解 A2UI 消息如何从代理流向用户界面
先决条件
开始之前，请确保您已准备好：
- Node.js （版本 18 或更高版本） -点击此处下载
- Gemini API 密钥 -可从 Google AI Studio 免费获取。
安全通知
此演示运行一个使用 Gemini 生成 A2UI 响应的 A2A 代理。该代理可以访问您的 API 密钥，并将向 Google 的 Gemini API 发送请求。在生产环境中运行代理代码之前，请务必先进行审查。
第一步：克隆代码库
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 Client
步骤 4：安装并运行
运行单命令演示启动器：
npm install
npm run demo:all此命令将：
- 安装所有依赖项
- 构建 A2UI 渲染器
- 启动 A2A 餐厅查找代理（Python 后端）
- 启动开发服务器
- 打开浏览器
http://localhost:5173
演示运行
如果一切正常，您应该能在浏览器中看到网页应用。代理程序现在已准备好生成用户界面！
第五步：尝试一下
在网页应用中，尝试以下提示：
- "预订一张两人桌" ------观看客服人员生成预订表格
- "查找附近的意大利餐厅" - 查看动态搜索结果
- "你们的工作时间是什么时候？" - 体验针对不同意图的不同用户界面布局。
幕后发生了什么
┌─────────────┐ ┌──────────────┐ ┌────────────────┐
│ You Type │────────>│ A2A Agent │────────>│ Gemini API │
│ a Message │ │ (Python) │ │ (LLM) │
└─────────────┘ └──────────────┘ └────────────────┘
│ │
│ Generates A2UI JSON │
│<────────────────────────┘
│
│ Streams JSONL messages
v
┌──────────────┐
│ Web App │
│ (A2UI Lit │
│ Renderer) │
└──────────────┘
│
│ Renders native components
v
┌──────────────┐
│ Your UI │
└──────────────┘- 您可以通过网页用户界面发送消息。
- A2A代理收到对话后，会将对话内容发送给Gemini。
- Gemini 生成描述用户界面的 A2UI JSON 消息。
- A2A代理会将这些消息流式传输回Web应用程序。
- A2UI渲染器将它们转换为原生Web组件
- 您可以在浏览器中看到渲染后的用户界面。
A2UI消息剖析
我们来看看代理发送了什么。以下是一个简化的 JSON 消息示例：
定义用户界面
{
"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"}}这告诉客户端它有足够的信息来渲染用户界面。
这只是 JSON
注意看，这代码多么易读、结构多么清晰？LLM 可以轻松生成这样的代码，而且传输和渲染都是安全的------无需执行任何代码。
探索其他演示
该代码库还包含其他几个演示：
组件库（无需代理）
查看所有可用的 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 错误：
# Make sure Python 3.10+ is installed
python3 --version
# The demo should auto-install dependencies via the npm script
# If not, manually install them:
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/- Lit Web 客户端，带有 A2UI 渲染器 - A2UI渲染器 ：
web-lib/- Web渲染器实现
每个目录都有自己的 README 文件，其中包含详细文档。
**恭喜！**您已成功运行您的第一个 A2UI 应用程序。您已经了解了 AI 代理如何通过安全、声明式的 JSON 消息生成丰富的交互式用户界面，并将其原生渲染到 Web 应用程序中。