A2UI快速入门-编程阁

A2UI快速入门

A2UI, a streaming protocol for Agent-Driven User Interfaces

quickstart快速开始

通过运行餐厅查找器演示程序，亲身体验 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 的实际应用，可以开始：

学习核心概念：理解表面、组件和数据绑定
设置您自己的客户端：将 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 应用程序中。

A2UI快速入门