企业官网建设流程全解析

A2UI 完整教程：5 分钟在本地跑通 AI 生成 UI

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

AI 对话常常只剩一长段文字，用户只能干读。A2UI 是开源的声明式 UI 协议加渲染器套件：Agent 用 JSON「描述」界面，客户端拿自家原生组件库渲染，AI 生成 UI 从此是可落地的工程能力，而不只是演示。本文先用 3 条命令把本地演示跑起来，再逐节拆核心机制。

AI 生成 UI 的安全逻辑：一张图看懂声明式协议

本节用一个比喻加一张图，回答 A2UI 为什么安全、协议里谁负责什么。

把 Agent 当编剧，客户端组件库当演员：编剧交出的剧本是纯 JSON 的结构描述，演员只能按剧本里写好的角色上台，剧本无法让演员做戏外动作——这就是 A2UI 的安全根基。协议里有四个固定角色：

• Surface：一块渲染画布，对话里的一张卡片区域
• Component：按钮、文本、日期选择器这类基本单元
• Data Model：状态仓库，组件按路径绑定数据，改数据即改界面
• Catalog：客户端预先批准的组件白名单，Agent 只能从中选取

一条消息长这样，字段都很短：

// 最小消息：声明一个文本组件并绑定数据路径 { "version": "v0.9.1", "updateComponents": { "surfaceId": "main", "components": [ { "id": "title", "component": "Text", "text": { "path": "/reservation/title" }, "variant": "h3" } ] } }

消息以流式方式陆续到达：客户端先缓存组件定义与数据更新，拿到渲染信号后从根节点组装组件树、解析数据绑定，再到注册表里找本地实现。结构是扁平的 ID 引用列表，所以 Agent 只需发增量，界面就能渐进式更新，不必整页重画。

A2UI 快速上手：3 条命令跑出第一个动态界面

本节交付：5 分钟跑起本地演示，3 条核心命令加 3 个成功标志。

前置三样：Node.js 18+（启用 Corepack）、uv（需 Python 3.10+）、一个 Gemini API Key。

git clone https://gitcode.com/GitHub_Trending/a2/a2ui && cd a2ui # ① 克隆仓库 export GEMINI_API_KEY="your_gemini_key" # 先导出 Key，替换为你自己的 corepack enable && yarn install # ② 启用包管理器并安装依赖 cd samples/client/lit && yarn demo:restaurant # ③ 一键启动：Agent + 网页客户端

yarn demo:restaurant会先构建渲染器，再把 Python 智能体与 Lit 网页客户端并行拉起，终端日志分 SHELL 与 REST 两路。

跑完打开http://localhost:5173，对照 3 个成功标志：

1. 页面出现输入框，两路终端日志都在滚动
2. 敲入 "Book a table for 2"，几秒内生成带日期选择器与确认按钮的预订表单
3. 表单不在源码里写死，它是 LLM 现场生成的 A2UI 消息渲染出来的——换个请求再发，表单随之变化

实战闭环：从口味表单到菜谱卡片

本节用真实 MCP 示例走完 输入 → 调用 → 返回 → 渲染 全链路，位置在 samples/community/mcp/a2ui-over-mcp-recipe/。

cd samples/community/mcp/a2ui-over-mcp-recipe uv run . # 启动 MCP 服务，SSE 传输，默认 8000 端口 cd client yarn dev # 启动网页客户端

打开http://localhost:5173，按 4 步走：

1. 输入：左侧表单（烹饪方式、蛋白质选择）是get_recipe_form_a2ui返回的 A2UI 表单
2. 操作：选「烤 + 鸡」点 Get Recipe 后，客户端经 8000 端口的 SSE 通道向 MCP 服务端发出对get_recipe_a2ui的调用
3. 返回：工具不吐整套界面，只携带动态数据 updateDataModel（状态更新消息）。模板地址则挂在工具的元数据上：

// 工具上挂的 UI 元数据：告诉客户端静态模板在哪取 { "_meta": { "ui": { "resourceUri": "a2ui://recipe-card", "mimeType": "application/a2ui+json" } } }

4. 渲染：客户端拉取并缓存a2ui://recipe-card模板，注入动态数据，出一张含图片、评分、烹饪时长的菜谱卡

静态模板走资源、工具调用只带数据的分拆，是这套闭环的核心设计。想核对链路，可用 MCP Inspector 连接（命令见示例 README）：Resources 下应出现a2ui://recipe-form与a2ui://recipe-card两个资源，Tools 下两个工具各带一段_meta.ui链接。

进阶指南：安全边界、自定义组件与生态接入

跑通之后看这里：安全、自定义组件、生态接入，三个话题各给几句话结论。

• 🔒安全边界：Agent 只发声明式数据，可执行代码被结构性挡在门外，客户端守住组件白名单即可；外部消息与 AgentCard 描述字段仍要按不可信输入校验清理，防提示注入
• 🧩自定义组件：开放注册表模式，可把现有组件（含遗留 iframe 内容）封装成 A2UI 组件并接上数据绑定与事件；自定义组件目录能进一步限定生成范围
• 📦生态接入：传输层兼容 A2A 与 AG-UI，可给 ADK、LangGraph 等框架生成脚手架后挂 A2UI 渲染；Composer 拖拽搭界面、直接导出 A2UI JSON

选型自测：A2UI 适合你的三个问题

回答下面 3 个问题即可判断，不需要读完全部文档：

1. 问：界面是否随用户输入或业务状态动态生成？是（动态表单、预约、审批面板）则高度匹配；否，属于一次性静态页面，直接写原生更快
2. 问：同一套交互逻辑是否要在 Web 和移动端复用？是，则一份 JSON 多端原生渲染，省下多端开发成本；否，单端页面收益有限
3. 问：合规是否要求「Agent 只能碰白名单组件」？是，A2UI 提供结构级保证；若客户端完全无法注册组件，此方案不可用

另有两个场景建议直接放弃：像素级定制视觉且无扩展预算、毫秒级实时交互（在线游戏主循环）。

避坑速查：新手高频报错一次讲清

新手最常碰到的 4 种现象，一张表讲清原因和解法：

一句话结论：Agent 负责描述，客户端负责实现——你用声明式 JSON 换来了生成式 UI，安全边界仍握在自己手里。入口清单：

• 官方文档
• 5 分钟快速上手
• Agent 示例合集
• 各框架渲染器
• 可视化构建工具 Composer
• 贡献指南

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