5分钟上线您的第一个 Agentic UI 应用

目标：别再只做普通的聊天机器人了。做一个能“真正做事”的应用。在本指南中，我们将把一个普通的 React 组件变成 AI 可控的交互界面。

我们要构建什么

一个 餐厅推荐 Agent。它不会用文字干巴巴地列出餐厅名字，而是会直接向您展示带有评分、菜系和照片的交互式卡片。

前置条件

• Node.js 18+
• API Key (来自 OpenAI, Anthropic, 或 Google Gemini)

1. 安装 SDK

A2UI 轻量且严格类型化。为您的框架（本例中使用 React）安装核心库。

npm install @a2ui/react @a2ui/core

2. 带上您现有的组件

A2UI 最棒的一点是：您不需要学习新的 UI 库。 直接使用您现有的 React 组件即可。

假设您有一个 RestaurantCard 组件：

// components/RestaurantCard.tsx
export const RestaurantCard = ({ name, rating, cuisine }) => (
  <div className="p-4 border rounded shadow-sm bg-white hover:shadow-md transition-shadow">
    <h3 className="text-lg font-bold">{name}</h3>
    <p className="text-gray-600">{cuisine} • {rating} ⭐</p>
  </div>
);

3. 创建注册表 (安全防火墙)

这是安全性最关键的一步。 注册表 (Registry) 充当了白名单的作用。它告诉 A2UI：“这些是 AI 唯一被允许使用的组件。” 这能有效防止 AI 产生 UI 幻觉或注入恶意代码。

// registry.ts
import { createRegistry } from '@a2ui/react';
import { RestaurantCard } from './components/RestaurantCard';

export const myRegistry = createRegistry({
  components: {
    // 映射关系：JSON 标签 'restaurant-card' -> 您的 React 组件
    'restaurant-card': RestaurantCard,
  },
});

4. 渲染 Agent 的“思考”

当您的 Agent 返回 JSON 时，直接将其喂给 AIOutput 组件。它会自动处理解析、流式传输和错误处理。

// App.tsx
import { AIOutput } from '@a2ui/react';
import { myRegistry } from './registry';

// 模拟 LLM 返回的数据
const agentResponse = {
  type: 'restaurant-card',
  data: {
    name: '寿司皇宫',
    rating: 4.8,
    cuisine: '日料'
  }
};

export default function App() {
  return (
    <div className="max-w-md mx-auto mt-10">
        <AIOutput
          registry={myRegistry}
          data={agentResponse}
        />
    </div>
  );
}

5. 教会 AI “说 UI 语言”

最后，必须要告诉您的 LLLM (GPT-4, Claude 等) 如何使用这个新协议。这通常通过 System Prompt (系统提示词) 来完成。

SYSTEM:
你是一个乐于助人的美食助手。
当推荐餐厅时，不要使用 Markdown 或纯文本。
请使用 'restaurant-card' 工具的内容。

输出格式 (JSON):
{
  "name": string, // 餐厅名称
  "rating": number, // 0-5 星级
  "cuisine": string // 例如 "川菜", "日料"
}

原理：LLM 会像调用函数一样对待您的 UI 组件。它负责生成 JSON 数据，而 A2UI 负责将其渲染为精美的像素。

下一步

运行官方 Restaurant Finder 示例应用

要沉浸式地理解 A2UI 的前后端解耦架构，最直接的方式是在本地跑通 a2ui-project/a2ui 官方仓库 里的 Restaurant Finder (餐厅查找助手) 示例。

准备环境

• Node.js (主要用于前端 Web Client)
• Python uv 包管理器 (主要用于运行后端 Agent)
• 申请一个可用的 Gemini API Key

1. 克隆代码与环境变量

git clone https://github.com/a2ui-project/a2ui.git
cd A2UI
export GEMINI_API_KEY="your_gemini_api_key"

2. 启动 Agent 后端

这里用到高速包管理工具 uv 来运转基于 Python 的餐厅预订 Agent 逻辑：

cd samples/agent/adk/restaurant_finder
uv run .

3. 构建并启动带 Lit 的渲染前端

新开一个终端窗口跑前端命令，这些命令会依次构建 Markdown 解析器、Web Core 核心层以及基于 Lit 框架渲染的测试 UI Shell。

# 安装与构建链路
cd renderers/markdown/markdown-it && npm install && npm run build
cd ../../web_core && npm install && npm run build
cd ../lit && npm install && npm run build
cd ../../samples/client/lit/shell && npm install && npm run dev