企业官网建设流程全解析

A2UI 快速上手：从零到跑通 AI 生成 UI 的完整实战

【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui

你的 Agent 只会回一段纯文字，用户只能盯着聊天框干等？A2UI 就是为这个痛点而来的：一个开源协议加渲染器套件，让 Agent 用声明式 JSON 描述界面，由客户端用自己的原生组件库渲染。接下来带你从零把官方演示跑起来。

🏗 A2UI 怎么分工：像看施工图纸一样理解它

把 A2UI 想象成建筑施工。设计方（Agent）交出的是一张图纸：承重墙在哪、插座留几个、数据接口接哪根线。施工队（客户端）拿着图纸，用自己的建材和工艺把房子盖出来。图纸写得再具体，也指挥不了施工队去搬别人的砖——这就是这套协议的安全边界。

落到协议里，四个角色各管一摊：

• 表面（Surface）：一块独立的渲染区域，对话里的一张卡片就是其中一块
• 组件（Component）：按钮、文本、日期选择器这类最小构件
• 数据模型（Data Model）：应用的状态仓库，组件通过路径绑定数据，数据一变，界面跟着变
• 组件目录（Catalog）：客户端预先批准的构件白名单，Agent 生成的每个组件都得能对上号

一条典型的A2UI消息长这样：

{ "version": "v0.9.1", "updateComponents": { "surfaceId": "main", "components": [ { "id": "date", "component": "DateTimeInput", "value": { "path": "/reservation/date" } } ] } }

它有两个值得琢磨的特点。第一，组件是一个扁平列表，成员之间靠id互相引用，不用层层嵌套。大模型按顺序吐 token，平铺结构天然好生成、好校验。第二，改界面不用整页重画：Agent 只发增量修改，哪块变了更新哪块，界面随之渐进刷新。

安全边界则来自"消息是数据，不是代码"。整条消息里没有任何可执行内容，客户端只需守住一道口子：组件名必须在白名单里。对不上的名字直接拒收，任意代码执行的风险被结构性堵死。

消息是流式到达的：客户端先缓冲组件定义和数据更新，收到渲染信号后从根节点构建组件树、解析数据绑定，再到注册表里找本地实现。

💻 三步跑通 A2UI 官方演示

动手之前，把四样东西备齐：

• Node.js 18+（启用 Corepack）
• Python 3.10+
• Python 包管理器uv
• 一个 Gemini API Key

# 1. 克隆 A2UI 仓库 git clone https://gitcode.com/GitHub_Trending/a2/a2ui cd a2ui # 2. 导出 Gemini API Key（替换成你自己的 Key） export GEMINI_API_KEY="your_key" # 3. 安装依赖并启动演示：同时拉起 Python 智能体与 Lit 网页客户端 corepack enable yarn install cd samples/client/lit yarn demo:restaurant

第一条命令把整个项目落到本地。第二条把 Key 放进环境变量，Agent 靠它调 Gemini。第三条先装好工作区依赖，再一条命令把 Python Agent 和网页端一起拉起来。

浏览器打开http://localhost:5173，在输入框敲 "Book a table for 2"。几秒后，一张带日期选择器和确认按钮的预订表单出现。关键在这：这个表单不是源码里硬编码的，是 Gemini 现场生成的 A2UI 消息渲染出来的。换一句问法，比如 "Find Italian restaurants near me"，长出来的就是另一套界面。

🔁 MCP 闭环：从选口味到出菜谱卡

换一个业务场景，看Agent 渲染界面在 MCP 应用里怎么完整跑一圈。示例在 samples/community/mcp/a2ui-over-mcp-recipe/，一个"按口味生成菜谱卡"的 MCP 工具。

# 启动 MCP 服务（SSE 传输，默认 8000 端口） cd samples/community/mcp/a2ui-over-mcp-recipe uv run . # 再开一个终端，启动配套网页客户端 cd client yarn dev

打开http://localhost:5173，走一遍闭环：左侧表单让你选烹饪方式（烤/煎/慢炖）和蛋白质（鸡/牛/鱼），这本身也是 Agent 生成的 A2UI 表单。选"烤 + 鸡"，点 Get Recipe，客户端调用 MCP 工具get_recipe_a2ui，工具返回 A2UI JSON，客户端随即渲染出一张"Zesty Herb Grilled Chicken Breast"菜谱卡，带图片、评分、烹饪时长。

这个示例的巧味在于结构与数据分离。静态的界面模板以资源形式存放，比如a2ui://recipe-card；工具调用只回动态数据，即一条updateDataModel消息。工具描述上挂着一段元数据，告诉客户端去哪取模板：

{ "_meta": { "ui": { "resourceUri": "a2ui://recipe-card", "mimeType": "application/a2ui+json" } } }

客户端检查_meta.ui.resourceUri，拉取并缓存模板，再拿工具返回的动态数据往上填。模板只取一次，数据随取随换，链路干净利落。

📦 生态：一份 JSON，多端原生渲染

renderers/ 下已有多端实现：web_core 核心库，外加 Lit、React、Angular 渲染器，以及 Dart 和 Swift 版本。同一份 A2UI JSON，Web 端和移动端各用各的原生组件画出来。

传输层兼容 A2A 与 AG-UI 协议。你已经在用 ADK、LangGraph、CrewAI 之类的框架？跑一条脚手架命令再挂上 A2UI 渲染就行：

npx create-ag-ui-app@latest

不想手写 JSON 的话，还有可视化构建工具 A2UI Composer：拖拽组件搭界面，导出 A2UI JSON，直接粘进 Agent 提示词，见 tools/composer/。

🧭 该不该用，以及四个新手坑

如果你的产品需要 Agent 产出表单、卡片或仪表盘，或者同一套 UI 逻辑要跨 Web 和移动端复用，A2UI 值得排进试错清单。如果你要的是像素级定制视觉且没有扩展预算，直接写原生更快。如果只是一次性静态页面，手写更快。如果是毫秒级实时交互，比如在线游戏主循环，先别碰。

新手最常碰壁的地方，按"现象 → 原因 → 一句话解法"列给你：

• 首启报ERR_CONNECTION_REFUSED→ 网页端比 Python Agent 先启动完，时序问题 → 先别慌，等几秒刷新页面即可
• uv: command not found→ 本机没装 uv → 先装 uv，并确认 Python 3.10+
• 界面不更新→GEMINI_API_KEY没导出或 Key 无效 → 用echo $GEMINI_API_KEY确认 Key 存在且可用
• 写代码时对不上消息格式→ 版本混淆了 → v0.9.1 是当前稳定版，v1.0 是候选版，v0.8 已列为遗留版，动手前先翻 docs/public/ 里对应版本的规范

最后留一份入口清单：

• 官方文档：docs/public/
• 5 分钟快速上手：docs/public/quickstart.md
• Agent 示例合集：samples/agent/adk/
• 各框架渲染器：renderers/
• 可视化构建工具：tools/composer/
• 贡献指南：CONTRIBUTING.md

【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui