A2UI 完整教程5 分钟在本地跑通 AI 生成 UI【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2uiAI 对话常常只剩一长段文字用户只能干读。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_KEYyour_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 个成功标志页面出现输入框两路终端日志都在滚动敲入 Book a table for 2几秒内生成带日期选择器与确认按钮的预订表单表单不在源码里写死它是 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 步走输入左侧表单烹饪方式、蛋白质选择是get_recipe_form_a2ui返回的 A2UI 表单操作选「烤 鸡」点 Get Recipe 后客户端经 8000 端口的 SSE 通道向 MCP 服务端发出对get_recipe_a2ui的调用返回工具不吐整套界面只携带动态数据 updateDataModel状态更新消息。模板地址则挂在工具的元数据上// 工具上挂的 UI 元数据告诉客户端静态模板在哪取 { _meta: { ui: { resourceUri: a2ui://recipe-card, mimeType: application/a2uijson } } }渲染客户端拉取并缓存a2ui://recipe-card模板注入动态数据出一张含图片、评分、烹饪时长的菜谱卡静态模板走资源、工具调用只带数据的分拆是这套闭环的核心设计。想核对链路可用 MCP Inspector 连接命令见示例 READMEResources 下应出现a2ui://recipe-form与a2ui://recipe-card两个资源Tools 下两个工具各带一段_meta.ui链接。进阶指南安全边界、自定义组件与生态接入跑通之后看这里安全、自定义组件、生态接入三个话题各给几句话结论。安全边界Agent 只发声明式数据可执行代码被结构性挡在门外客户端守住组件白名单即可外部消息与 AgentCard 描述字段仍要按不可信输入校验清理防提示注入自定义组件开放注册表模式可把现有组件含遗留 iframe 内容封装成 A2UI 组件并接上数据绑定与事件自定义组件目录能进一步限定生成范围生态接入传输层兼容 A2A 与 AG-UI可给 ADK、LangGraph 等框架生成脚手架后挂 A2UI 渲染Composer 拖拽搭界面、直接导出 A2UI JSON选型自测A2UI 适合你的三个问题回答下面 3 个问题即可判断不需要读完全部文档问界面是否随用户输入或业务状态动态生成是动态表单、预约、审批面板则高度匹配否属于一次性静态页面直接写原生更快问同一套交互逻辑是否要在 Web 和移动端复用是则一份 JSON 多端原生渲染省下多端开发成本否单端页面收益有限问合规是否要求「Agent 只能碰白名单组件」是A2UI 提供结构级保证若客户端完全无法注册组件此方案不可用另有两个场景建议直接放弃像素级定制视觉且无扩展预算、毫秒级实时交互在线游戏主循环。避坑速查新手高频报错一次讲清新手最常碰到的 4 种现象一张表讲清原因和解法现象原因一句话解法浏览器报ERR_CONNECTION_REFUSED网页比 Python Agent 先起来属启动时序问题等几秒刷新即可不是故障uv: command not founduv 未安装或 Python 低于 3.10先装 uv再确认 Python 版本达标界面不更新、无 UI 生成GEMINI_API_KEY未导出或 Key 失效用echo $GEMINI_API_KEY检查后重启演示代码行为与文档对不上版本混淆稳定版 v0.9.1v1.0 候选v0.8 遗留写码前先查 docs/public/ 对应版本规范一句话结论Agent 负责描述客户端负责实现——你用声明式 JSON 换来了生成式 UI安全边界仍握在自己手里。入口清单官方文档5 分钟快速上手Agent 示例合集各框架渲染器可视化构建工具 Composer贡献指南【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
