A2UI + CopilotKit 集成指南

**版本说明：**集成 API 会变化。使用示例前，应在 CopilotKit 与 A2UI 官方文档中确认包版本和当前配置。

本指南将演示如何构建一个全栈 餐厅预订 Agent。

后端：Python Agent (使用 Google Gen AI SDK)。
前端：React + CopilotKit。
协议：基于标准 HTTP 流式传输 A2UI。

架构：经典 “三明治”

顶层面包 (UI)：CopilotKit 负责聊天窗口、状态管理和消息历史。
中间肉饼 (协议)：A2UI 定义 JSON 组件 (<RestaurantCard />)。
底层面包 (大脑)：Python Agent 决定何时展示这些卡片。

第一步：定义你的 “UI 词汇表”

首先，告诉系统有哪些 UI 组件可用。在 Python 后端定义 Schema，这教会了 LLM 如何用 restaurant-card 对象来“说话”。

# agent/restaurant_finder/prompt_builder.py

A2UI_SCHEMA = r'''
{
  "title": "A2UI 消息定义",
  "properties": {
    "createSurface": { ... },
    "updateComponents": {
      "description": "显示一个组件 (例如卡片、图表)",
      ...
    },
    "updateDataModel": { ... },
    "deleteSurface": { ... }
  }
}
'''

第二步：配置 Agent

将 Schema 绑定到 Agent 的系统指令 (System Instruction) 中。

# agent/restaurant_finder/agent.py

class RestaurantAgent:
    def __init__(self, base_url: str):
        # 1. 加载基础指令 ("你是一个乐于助人的助手...")
        self.instruction = BASE_INSTRUCTION
        # 2. 追加 A2UI 语法 ("这是你绘制卡片的方式...")
        self.instruction += get_ui_prompt(base_url, A2UI_SCHEMA)

第三步：前端渲染

在 React 端，您不需要手动编写流解析器。CopilotKit 已经为您处理好了一切。

// page.tsx (Next.js)
import { CopilotKit } from "@copilotkit/react-core";
import { CopilotSidebar } from "@copilotkit/react-ui";
import { RestaurantCard } from "./components/RestaurantCard";

export default function BookingPage() {
  return (
    <CopilotKit url="/api/copilotkit">
      <CopilotSidebar
        defaultOpen={true}
        labels={{ title: "餐厅预订助手" }}
      >
        {/* 您的主应用内容 */}
        <div className="p-10">
           <h1>欢迎来到美食搜索</h1>
        </div>
      </CopilotSidebar>
    </CopilotKit>
  );
}

注意：您需要在 CopilotKit 配置中注册 RestaurantCard 组件。

效果演示

下一步

想构建更多组件？ 查看组件库。
需要可视化工具？ 试试 A2UI Composer 自动生成 Schema。