A2UI Flutter 客户端示例从环境准备到餐厅查找器全流程运行指南【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2uiA2UI 仓库在 samples/client/flutter 目录下提供了基于 Flutter 的官方客户端示例用于展示「AI Agent 动态生成 UI」这一核心能力。本文以 samples/client/flutter/README.md 为主线结合仓库内restaurant_finder完整示例的源码、依赖与测试系统讲解 Flutter 客户端示例的运行方式、端到端联调步骤以及 A2UI 消息驱动 UI 渲染的底层实现机制。读完本文你将能够独立把 Flutter 客户端与 Python A2A Agent 后端跑通并理解其工作原理。一、示例目录结构速览samples/client/flutter是 A2UI 多框架客户端示例Angular、Flutter、Lit、React中的 Flutter 实现当前包含一个完整可运行的示例samples/client/flutter/ ├── README.md # 示例总览与运行说明本文主线 └── restaurant_finder/ ├── README.md # 餐厅查找器示例说明 ├── app/ # Flutter 客户端主工程 │ ├── pubspec.yaml # 工程清单与依赖声明 │ ├── lib/ # 客户端源码 │ └── test/widget_test.dart # Widget 冒烟测试 └── e2e_test/ # 端到端测试独立流水线其中restaurant_finder是 A2UI 官方 Quickstart 中演示的「餐厅查找与订座」应用用户在 Flutter 客户端输入自然语言如「帮我找 3 家纽约中餐馆」Python 后端 Agent 调用 LLM 生成 A2UI JSON 消息客户端将其渲染为表单、搜索结果、预约确认等真实可交互界面——这些界面并非硬编码在客户端源码中而是由 LLM 实时生成的参见 docs/public/quickstart.md。二、环境准备运行 Flutter 客户端前需要准备以下环境Flutter SDK示例要求 Dart SDK3.10.0 4.0.0、Flutter3.35.7 4.0.0具体版本约束见 pubspec.yaml。安装方式参考 Flutter 官方文档flutter --version可验证是否就绪。运行目标平台仓库明确测试支持macos与web两个平台。以 Web 为目标时还需本机安装 Chrome 浏览器。后端运行环境餐厅查找器示例的 Agent 后端基于 Python需要安装 uvPython 包管理器并准备一个可用的 LLM API Key示例中使用 Gemini。注意本文所述命令均以仓库根目录为起点请先克隆并进入仓库根目录。三、运行 Flutter 示例核心命令根据 samples/client/flutter/README.md在安装好 Flutter SDK 后进入目标示例的app子目录并启动即可cd example_name/app flutter run -d web其中example_name替换为具体示例名当前仓库中即restaurant_finder。-d web指定以 Web 为目标设备运行Flutter 会启动本地开发服务器并在浏览器中打开应用。针对当前仓库的restaurant_finder示例实际命令为cd samples/client/flutter/restaurant_finder/app flutter run -d chrome支持平台说明示例已针对macos与web两个平台启用并通过测试如需在 iOS、Android、Windows、Linux 等其他平台构建运行则需要参照 Flutter 官方文档的平台集成说明为对应平台补充工程配置后再执行flutter run -d platform。四、端到端实战Flutter UI Python Agent仅仅启动客户端还不够——餐厅查找器需要后端 Agent 提供 A2UI 数据。完整联调需要两个终端分别启动后端与前端。第一步启动 A2A Agent 后端在第一个终端中进入 Agent 示例目录详见 samples/agent/adk/restaurant_finder/README.mdcd samples/agent/adk/restaurant_finder cp .env.example .env # 在 .env 中填入真实的 API Key勿提交该文件 uv run .该示例基于 Agent Development KitADK与 A2A 协议将「餐厅查找与订座」Agent 以 A2A Server 形式托管。第二步验证 Agent 服务在第二个终端中先确认 Agent 已通过 A2A 协议提供服务默认监听http://localhost:10002curl http://localhost:10002/.well-known/agent-card.json也可直接发送一条 A2A 消息验证响应curl http://localhost:10002 \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: message/send, params: { message: { role: user, parts: [{text: Find me an Italian restaurant}], messageId: 1 } } }第三步启动 Flutter 客户端确认 Agent 服务正常后在第二个终端启动 Flutter 客户端cd samples/client/flutter/restaurant_finder/app flutter run -d chrome客户端默认连接的后端地址为http://localhost:10002定义于 session.dart 的defaultServerUrl与 Agent 监听端口一致。启动后即可在页面输入提示词体验例如「Book a table for 2」—— 观察 Agent 生成预约表单「Find Italian restaurants near me」—— 查看动态搜索结果「What are your hours?」—— 体验不同意图对应的不同 UI 布局。如果浏览器打开时出现ERR_CONNECTION_REFUSED通常是客户端启动快于 Python 后端所致启动时序竞争等待几秒刷新页面即可恢复。五、客户端源码剖析A2UI 消息如何驱动界面restaurant_finder/app/lib下的源码结构清晰从三层理解 A2UI Flutter 客户端的运行机制lib/ ├── main.dart # 库导出入口 └── src/ ├── main.dart # 应用入口MaterialApp 与主题 ├── session.dart # 会话层连接 Agent、管理 Surface ├── screen.dart # 界面层表单、加载态、Surface 列表渲染 └── primitives.dart # 通用 UI 组件主题切换、错误横幅、加载文案1. 会话层连接 Agent 与维护 Surfacesession.dart 中的RestaurantSession继承自ChangeNotifier是核心枢纽其构造函数完成了三件关键装配声明目录Catalog通过BasicCatalogItems.asCatalog().copyWith(catalogId: _agentCatalogId)构造客户端支持的组件目录并将catalogId覆盖为 Agent 侧公布的 Basic Catalog 地址源码注释说明Dart 侧BasicCatalogItems.asCatalog()默认使用标准目录 ID需覆盖以与 Python 侧 BasicCatalog Provider 对齐。建立连接A2uiAgentConnector(url: Uri.parse(serverUrl))负责与 A2A Agent 建立连接。创建 Surface 控制器SurfaceController(catalogs: catalogs)负责维护 UI Surface 的生命周期与状态。随后_init()中订阅了五条关键数据流session.dart_connector.stream→ Agent 发来的 A2UI 消息转交给SurfaceController.handleMessage_connector.textStream→ Agent 的纯文本输出此处仅记日志_surfaceController.onSubmit→ 用户在 Surface 上的交互提交回传给 Agent_connector.errorStream→ 连接/解析错误_surfaceController.surfaceUpdates→ Surface 变更通知 UI 刷新。发送消息时_sendMessageToAgent客户端会先清空当前所有 Surface向控制器发送DeleteSurface再调用_connector.connectAndSend(message, clientCapabilities: _surfaceController.clientCapabilities)携带客户端能力声明发送消息从而保证每次请求都从干净的界面开始session.dart。2. 界面层表单、加载态与 Surface 渲染screen.dart 中_buildContent()依据会话状态呈现三种界面isRequesting为真 → 加载动画 轮换文案尚未发送过消息!hasSentMessage→ 输入表单标题、输入框、发送按钮、错误横幅已发送消息 → 遍历activeSurfaceIds为每个 Surface 通过Surface(surfaceContext: ...)渲染 A2UI 组件screen.dart。输入框的默认提示文本与占位文案为「Find me 3 Chinese restaurants in New York.」screen.dart。加载文案由 primitives.dart 中的LoadingTexts提供共 6 条中性文案如「Talking to your concierge...」每 2 秒轮换一次设计为同时兼容「查找餐厅」与「确认订座」两个阶段避免文案与场景不符。3. 数据流全景整个链路为用户输入 →RestaurantSession经A2uiAgentConnector发送给 Python Agent → Agent 调用 LLM 生成 A2UI JSON 消息并流式回传 → 客户端SurfaceController解析并更新 Surface →Surfacewidget 渲染为原生 Flutter 组件。完整时序可参见 docs/public/quickstart.md 中的交互序列图。六、依赖清单与渲染器定位客户端依赖声明于 pubspec.yaml核心依赖包括依赖版本作用flutterSDK基础框架使用 Material Designgenui^0.8.0Flutter 侧 Generative UI 核心框架提供SurfaceController、Surface等基础设施genui_a2a^0.8.0使 Flutter Gen UI SDK 充当 A2UI 后端 Agent 的渲染器实现与 A2UI 协议的对接提供A2uiAgentConnectordartantic_ai^3.1.0供端到端测试中直接调用 AI 模型logging^1.3.0日志输出应用入口将日志级别设为WARNINGgenui与genui_a2a即 Flutter 官方的 Gen UI SDK是 A2UI 的官方 Flutter 渲染器实现详见 renderers/flutter/README.mdgenui提供生成式 UI 的核心框架genui_a2a专门负责对接 A2UI 协议、作为后端 Agent 生成的 UI 的渲染层。这意味着 Flutter 开发者无需自己解析 A2UI JSON直接使用这两个包即可获得完整的渲染能力。七、测试策略冒烟测试与端到端测试示例工程配备了两层测试覆盖不同粒度1. Widget 冒烟测试widget_test.dart 仅校验RestaurantFinderApp能否正常构建挂载tester.pumpWidget无需后端与 API Key可随时在本地执行。2. 端到端测试restaurant_finder/e2e_test是一个独立包详见 e2e_test/README.md验证三类实体协同工作① Flutter 餐厅查找客户端、② Python 餐厅查找 Agent、③ AI 模型。其测试用例infra_test.dart依次检查能否读取 API Key、能否与 AI 模型正常对话、能否启动并验证餐厅查找 Agent 服务超时 5 分钟。由于依赖真实 API Key该测试在独立的 CI/CD 流水线中运行。八、常见问题排查API Key 缺失Agent 启动报错时先确认echo $GEMINI_API_KEY有输出且.env已正确填写并执行过cp .env.example .env。连接被拒绝浏览器出现ERR_CONNECTION_REFUSED多为后端未就绪的启动时序问题等待数秒刷新页面即可。uv命令不存在需先安装 uvcurl -LsSf https://astral.sh/uv/install.sh | sh并以python3 --version确认 Python 3.10 可用。平台编译报错确认目标平台为macos/web之外时需先参照 Flutter 官方平台集成文档补充工程配置。九、安全注意事项餐厅查找器演示中Agent 会将对话交给外部 LLM 生成 A2UI 响应任何来自 Agent 的数据都应视为不可信输入。潜在风险包括恶意 Agent 通过构造 AgentCard 字段实施提示注入、伪造 UI 界面进行钓鱼phishing、通过属性值注入脚本XSS、或生成超复杂布局造成客户端性能劣化DoS。生产环境必须落实输入清洗、Content Security PolicyCSP、对可嵌入内容iframe/WebView的严格隔离以及安全的凭据管理完整讨论见 samples/agent/adk/restaurant_finder/README.md 的 Disclaimer 章节。本示例仅用于演示 A2UI 与 A2A 协议机制不应直接用于生产。延伸阅读餐厅查找器示例完整说明包含 TL;DR 运行方式与 VS Code 运行配置指引Agent 后端示例ADK A2A 协议的后端实现与安全声明Quickstart 五分钟快速体验完整的端到端交互时序与 A2UI JSON 载荷示例Flutter 渲染器说明genui与genui_a2a包的定位与关系其他客户端示例Angular、Lit、React 等同级实现可对照学习【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 A2UI Flutter 客户端示例：从环境准备到餐厅查找器全流程运行指南
A2UI Flutter 客户端示例从环境准备到餐厅查找器全流程运行指南【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2uiA2UI 仓库在 samples/client/flutter 目录下提供了基于 Flutter 的官方客户端示例用于展示「AI Agent 动态生成 UI」这一核心能力。本文以 samples/client/flutter/README.md 为主线结合仓库内restaurant_finder完整示例的源码、依赖与测试系统讲解 Flutter 客户端示例的运行方式、端到端联调步骤以及 A2UI 消息驱动 UI 渲染的底层实现机制。读完本文你将能够独立把 Flutter 客户端与 Python A2A Agent 后端跑通并理解其工作原理。一、示例目录结构速览samples/client/flutter是 A2UI 多框架客户端示例Angular、Flutter、Lit、React中的 Flutter 实现当前包含一个完整可运行的示例samples/client/flutter/ ├── README.md # 示例总览与运行说明本文主线 └── restaurant_finder/ ├── README.md # 餐厅查找器示例说明 ├── app/ # Flutter 客户端主工程 │ ├── pubspec.yaml # 工程清单与依赖声明 │ ├── lib/ # 客户端源码 │ └── test/widget_test.dart # Widget 冒烟测试 └── e2e_test/ # 端到端测试独立流水线其中restaurant_finder是 A2UI 官方 Quickstart 中演示的「餐厅查找与订座」应用用户在 Flutter 客户端输入自然语言如「帮我找 3 家纽约中餐馆」Python 后端 Agent 调用 LLM 生成 A2UI JSON 消息客户端将其渲染为表单、搜索结果、预约确认等真实可交互界面——这些界面并非硬编码在客户端源码中而是由 LLM 实时生成的参见 docs/public/quickstart.md。二、环境准备运行 Flutter 客户端前需要准备以下环境Flutter SDK示例要求 Dart SDK3.10.0 4.0.0、Flutter3.35.7 4.0.0具体版本约束见 pubspec.yaml。安装方式参考 Flutter 官方文档flutter --version可验证是否就绪。运行目标平台仓库明确测试支持macos与web两个平台。以 Web 为目标时还需本机安装 Chrome 浏览器。后端运行环境餐厅查找器示例的 Agent 后端基于 Python需要安装 uvPython 包管理器并准备一个可用的 LLM API Key示例中使用 Gemini。注意本文所述命令均以仓库根目录为起点请先克隆并进入仓库根目录。三、运行 Flutter 示例核心命令根据 samples/client/flutter/README.md在安装好 Flutter SDK 后进入目标示例的app子目录并启动即可cd example_name/app flutter run -d web其中example_name替换为具体示例名当前仓库中即restaurant_finder。-d web指定以 Web 为目标设备运行Flutter 会启动本地开发服务器并在浏览器中打开应用。针对当前仓库的restaurant_finder示例实际命令为cd samples/client/flutter/restaurant_finder/app flutter run -d chrome支持平台说明示例已针对macos与web两个平台启用并通过测试如需在 iOS、Android、Windows、Linux 等其他平台构建运行则需要参照 Flutter 官方文档的平台集成说明为对应平台补充工程配置后再执行flutter run -d platform。四、端到端实战Flutter UI Python Agent仅仅启动客户端还不够——餐厅查找器需要后端 Agent 提供 A2UI 数据。完整联调需要两个终端分别启动后端与前端。第一步启动 A2A Agent 后端在第一个终端中进入 Agent 示例目录详见 samples/agent/adk/restaurant_finder/README.mdcd samples/agent/adk/restaurant_finder cp .env.example .env # 在 .env 中填入真实的 API Key勿提交该文件 uv run .该示例基于 Agent Development KitADK与 A2A 协议将「餐厅查找与订座」Agent 以 A2A Server 形式托管。第二步验证 Agent 服务在第二个终端中先确认 Agent 已通过 A2A 协议提供服务默认监听http://localhost:10002curl http://localhost:10002/.well-known/agent-card.json也可直接发送一条 A2A 消息验证响应curl http://localhost:10002 \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: message/send, params: { message: { role: user, parts: [{text: Find me an Italian restaurant}], messageId: 1 } } }第三步启动 Flutter 客户端确认 Agent 服务正常后在第二个终端启动 Flutter 客户端cd samples/client/flutter/restaurant_finder/app flutter run -d chrome客户端默认连接的后端地址为http://localhost:10002定义于 session.dart 的defaultServerUrl与 Agent 监听端口一致。启动后即可在页面输入提示词体验例如「Book a table for 2」—— 观察 Agent 生成预约表单「Find Italian restaurants near me」—— 查看动态搜索结果「What are your hours?」—— 体验不同意图对应的不同 UI 布局。如果浏览器打开时出现ERR_CONNECTION_REFUSED通常是客户端启动快于 Python 后端所致启动时序竞争等待几秒刷新页面即可恢复。五、客户端源码剖析A2UI 消息如何驱动界面restaurant_finder/app/lib下的源码结构清晰从三层理解 A2UI Flutter 客户端的运行机制lib/ ├── main.dart # 库导出入口 └── src/ ├── main.dart # 应用入口MaterialApp 与主题 ├── session.dart # 会话层连接 Agent、管理 Surface ├── screen.dart # 界面层表单、加载态、Surface 列表渲染 └── primitives.dart # 通用 UI 组件主题切换、错误横幅、加载文案1. 会话层连接 Agent 与维护 Surfacesession.dart 中的RestaurantSession继承自ChangeNotifier是核心枢纽其构造函数完成了三件关键装配声明目录Catalog通过BasicCatalogItems.asCatalog().copyWith(catalogId: _agentCatalogId)构造客户端支持的组件目录并将catalogId覆盖为 Agent 侧公布的 Basic Catalog 地址源码注释说明Dart 侧BasicCatalogItems.asCatalog()默认使用标准目录 ID需覆盖以与 Python 侧 BasicCatalog Provider 对齐。建立连接A2uiAgentConnector(url: Uri.parse(serverUrl))负责与 A2A Agent 建立连接。创建 Surface 控制器SurfaceController(catalogs: catalogs)负责维护 UI Surface 的生命周期与状态。随后_init()中订阅了五条关键数据流session.dart_connector.stream→ Agent 发来的 A2UI 消息转交给SurfaceController.handleMessage_connector.textStream→ Agent 的纯文本输出此处仅记日志_surfaceController.onSubmit→ 用户在 Surface 上的交互提交回传给 Agent_connector.errorStream→ 连接/解析错误_surfaceController.surfaceUpdates→ Surface 变更通知 UI 刷新。发送消息时_sendMessageToAgent客户端会先清空当前所有 Surface向控制器发送DeleteSurface再调用_connector.connectAndSend(message, clientCapabilities: _surfaceController.clientCapabilities)携带客户端能力声明发送消息从而保证每次请求都从干净的界面开始session.dart。2. 界面层表单、加载态与 Surface 渲染screen.dart 中_buildContent()依据会话状态呈现三种界面isRequesting为真 → 加载动画 轮换文案尚未发送过消息!hasSentMessage→ 输入表单标题、输入框、发送按钮、错误横幅已发送消息 → 遍历activeSurfaceIds为每个 Surface 通过Surface(surfaceContext: ...)渲染 A2UI 组件screen.dart。输入框的默认提示文本与占位文案为「Find me 3 Chinese restaurants in New York.」screen.dart。加载文案由 primitives.dart 中的LoadingTexts提供共 6 条中性文案如「Talking to your concierge...」每 2 秒轮换一次设计为同时兼容「查找餐厅」与「确认订座」两个阶段避免文案与场景不符。3. 数据流全景整个链路为用户输入 →RestaurantSession经A2uiAgentConnector发送给 Python Agent → Agent 调用 LLM 生成 A2UI JSON 消息并流式回传 → 客户端SurfaceController解析并更新 Surface →Surfacewidget 渲染为原生 Flutter 组件。完整时序可参见 docs/public/quickstart.md 中的交互序列图。六、依赖清单与渲染器定位客户端依赖声明于 pubspec.yaml核心依赖包括依赖版本作用flutterSDK基础框架使用 Material Designgenui^0.8.0Flutter 侧 Generative UI 核心框架提供SurfaceController、Surface等基础设施genui_a2a^0.8.0使 Flutter Gen UI SDK 充当 A2UI 后端 Agent 的渲染器实现与 A2UI 协议的对接提供A2uiAgentConnectordartantic_ai^3.1.0供端到端测试中直接调用 AI 模型logging^1.3.0日志输出应用入口将日志级别设为WARNINGgenui与genui_a2a即 Flutter 官方的 Gen UI SDK是 A2UI 的官方 Flutter 渲染器实现详见 renderers/flutter/README.mdgenui提供生成式 UI 的核心框架genui_a2a专门负责对接 A2UI 协议、作为后端 Agent 生成的 UI 的渲染层。这意味着 Flutter 开发者无需自己解析 A2UI JSON直接使用这两个包即可获得完整的渲染能力。七、测试策略冒烟测试与端到端测试示例工程配备了两层测试覆盖不同粒度1. Widget 冒烟测试widget_test.dart 仅校验RestaurantFinderApp能否正常构建挂载tester.pumpWidget无需后端与 API Key可随时在本地执行。2. 端到端测试restaurant_finder/e2e_test是一个独立包详见 e2e_test/README.md验证三类实体协同工作① Flutter 餐厅查找客户端、② Python 餐厅查找 Agent、③ AI 模型。其测试用例infra_test.dart依次检查能否读取 API Key、能否与 AI 模型正常对话、能否启动并验证餐厅查找 Agent 服务超时 5 分钟。由于依赖真实 API Key该测试在独立的 CI/CD 流水线中运行。八、常见问题排查API Key 缺失Agent 启动报错时先确认echo $GEMINI_API_KEY有输出且.env已正确填写并执行过cp .env.example .env。连接被拒绝浏览器出现ERR_CONNECTION_REFUSED多为后端未就绪的启动时序问题等待数秒刷新页面即可。uv命令不存在需先安装 uvcurl -LsSf https://astral.sh/uv/install.sh | sh并以python3 --version确认 Python 3.10 可用。平台编译报错确认目标平台为macos/web之外时需先参照 Flutter 官方平台集成文档补充工程配置。九、安全注意事项餐厅查找器演示中Agent 会将对话交给外部 LLM 生成 A2UI 响应任何来自 Agent 的数据都应视为不可信输入。潜在风险包括恶意 Agent 通过构造 AgentCard 字段实施提示注入、伪造 UI 界面进行钓鱼phishing、通过属性值注入脚本XSS、或生成超复杂布局造成客户端性能劣化DoS。生产环境必须落实输入清洗、Content Security PolicyCSP、对可嵌入内容iframe/WebView的严格隔离以及安全的凭据管理完整讨论见 samples/agent/adk/restaurant_finder/README.md 的 Disclaimer 章节。本示例仅用于演示 A2UI 与 A2A 协议机制不应直接用于生产。延伸阅读餐厅查找器示例完整说明包含 TL;DR 运行方式与 VS Code 运行配置指引Agent 后端示例ADK A2A 协议的后端实现与安全声明Quickstart 五分钟快速体验完整的端到端交互时序与 A2UI JSON 载荷示例Flutter 渲染器说明genui与genui_a2a包的定位与关系其他客户端示例Angular、Lit、React 等同级实现可对照学习【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考