让 Agent 直出 AI 生成 UI：A2UI v0.9.1 实践笔记-育师

让 Agent 直出 AI 生成 UI：A2UI v0.9.1 实践笔记

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

Agent 把答案算对了，却只能糊成一坨纯文本，用户还得自己从字缝里抠字段——这是接过 LLM 应用的人都会撞上的墙。A2UI 是一套 Agent 界面协议（AI 生成 UI 的开源方案）：Agent 输出声明式 JSON 描述界面，客户端用自己的原生组件库把它渲染出来。读完这篇，你能在本地跑通演示，看懂消息从 LLM 到组件的链路，并判断该不该用它。

A2UI 本地跑通：环境准备与最小命令序列

跑通官方演示只需要四样东西：

Node.js 18+（未启用 Corepack 时先跑corepack enable）
Python 包管理器 uv（uv: command not found就装 uv，并确认 Python 3.10+）
Gemini API Key（界面迟迟不响应时用echo $GEMINI_API_KEY确认已导出且有效）
yarn 工作区依赖（安装中断就回到仓库根目录重跑yarn install）

# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/a2/a2ui cd a2ui # 导出 Gemini Key（替换成你自己的） export GEMINI_API_KEY="your_key" # 启用 yarn 并安装工作区依赖 corepack enable yarn install # 一条命令同时拉起 Python Agent 与 Lit 网页客户端 cd samples/client/lit yarn demo:restaurant

浏览器里，聊天框上方先浮出一张餐厅列表卡片；敲入 Book a table for 2，几秒后一张带日期选择器和确认按钮的预订表单从流式消息里"长"出来——这一屏在源码里找不到一行硬编码，下面画廊里全是 LLM 现场生成的界面。

A2UI 消息结构拆解：一条消息如何变成原生组件

把 Agent 想成出施工图纸的设计院，客户端是施工队：图纸只写"此处要一面承重墙、两樘双开门"，砌法工艺全由施工队自己的标准决定，设计院进不了工地。

对应到协议里的四个角色：

渲染画布（Surface）：对话里的一个卡片区域，Agent 可寻址的一块画布
组件（Component）：按钮、文本、输入框等基本单元
数据状态库（Data Model）：应用状态仓库，组件按路径绑定数据，改数据即改界面
组件白名单（Catalog）：客户端预先批准的组件集合，Agent 只能从里面挑

一条典型的天气卡片消息长这样：

{ "version": "v0.9.1", "updateComponents": { "surfaceId": "weather", "components": [ { "id": "title", "component": "Text", "text": "# 北京 · 晴", "variant": "h2" }, { "id": "temp", "component": "Text", "text": { "path": "/weather/temp" } }, { "id": "desc", "component": "Text", "text": { "path": "/weather/summary" } } ] } }

结构是"扁平列表 + id 引用"：组件互指只靠 id，无深嵌套，增量更新就是往数组里补一个对象——这正是 LLM 训练语料里最常见的 JSON 形态，所以它生成起来又快又稳。

消息流式到达：客户端先缓冲组件定义与数据更新，收到渲染信号后才从根节点建树、解析绑定、到注册表查本地实现，界面因此可以渐进更新而非整页重画。

A2UI MCP 集成实战：用文件系统浏览器走通业务闭环

换一个不依赖 LLM 的场景：samples/community/mcp/a2ui-over-mcp-filesystem/ 把标准 filesystem MCP 工具直接变成可浏览的目录界面。

# 进入社区样本目录安装依赖 cd samples/community yarn install # 一条命令同时拉起 MCP 代理与网页端 yarn workspace a2ui-over-mcp-filesystem run dev

你操作什么：页面加载后当前目录的文件列表已在左侧就位——载荷在挂载时自触发了一次列目录；接下来点一个文件夹行，或在搜索框输一个 glob 后点搜索
系统发生什么：每行的按钮触发一条callMcpTool链，调 filesystem MCP 工具，返回的纯文本被逐行切开、正则提取字段、JMESPath 整形，再写进数据模型
你看到什么：左侧列表刷新一组带图标和大小标注的新行，右侧预览栏以 Markdown 显示文件内容

界面状态全住在数据模型里：当前目录、搜索词、每一行（名字、大小、图标、该行该调的工具名）各占一个路径，点击只触发工具调用并写回这些路径，界面跟着重算——客户端没有一行业务代码。

调试侧，用 MCP Inspector 连上这类社区样本的 MCP 服务，Resources 与 Tools 面板里能直接看到a2ui://模板资源和挂在工具上的_meta.ui元数据，整条链路一目了然。

A2UI 安全边界：组件白名单与自定义目录

Agent 交出去的永远只是一份"图纸"，进不了客户端的施工现场——那它要是点了一扇白名单上不存在的门呢？客户端直接拒收，未注册组件渲染不出来，任意代码执行的风险被结构挡在门外。

注册表是开放的：任何现有组件、甚至套着安全 iframe 的遗留内容都能封装成 A2UI 组件，也可以定义自己的组件白名单来收紧生成边界 (docs/public/guides/defining-your-own-catalog.md)。传输层兼容 A2A 与 AG-UI，MCP 应用可随工具一起携带界面，拖拽搭界面并导出 JSON 的可视化构建工具也已就绪 (samples/community/mcp/, tools/composer/)。