生成式UI资源

• 什么是生成式UI？

• 生成式UI的三种类型

  • 受控生成式UI (AG-UI)
  • 声明式生成式UI (A2UI + Open-JSON-UI)
  • 开放式生成式UI (MCP应用)
    • 真实案例：Excalidraw MCP应用
  • 开放生成式UI (useComponent)

• 生成式UI Playground

• 博客

• 视频

• 其他资源

• 贡献

https://github.com/user-attachments/assets/ed28c734-e54e-4412-873f-4801da544a7f

本仓库将介绍智能体UI协议（AG-UI、A2UI、MCP应用）如何实现生成式UI模式（受控、声明式、开放式），以及如何使用CopilotKit来实现这些模式。

👉 OpenGenerativeUI —— 用于在智能体应用中构建生成式UI的开源框架

👉 生成式UI指南 (PDF) —— 对生成式UI的概念性概述，重点关注权衡、UI界面以及智能体UI协议之间的协作方式。

---

什么是生成式UI？

生成式UI是一种模式，在这种模式下，用户界面的部分内容不是由开发者完全预先定义的，而是在运行时由AI智能体生成、选择或控制。

智能体不仅可以生成文本，还可以发送UI状态、结构化的UI规范或交互式UI组件，由前端实时渲染。这使得UI从固定的、由开发者定义的界面转变为能够随着智能体的工作和上下文变化而动态调整的界面。

在CopilotKit生态系统中，生成式UI被划分为三种实用模式，分别通过不同的智能体UI协议和规范来实现，这些协议和规范定义了智能体如何向应用程序传递UI更新：

• 受控生成式UI（高控制、低自由度）→ AG-UI
• 声明式生成式UI（共享控制）→ A2UI、Open-JSON-UI
• 开放式生成式UI（低控制、高自由度）→ MCP应用 / 自定义UI

AG-UI（智能体-用户交互协议）作为这些模式之下的双向运行时交互层，提供了智能体与应用程序之间的连接，从而实现生成式UI，并且能够在A2UI、MCP应用、Open-JSON-UI以及自定义UI规范之间统一工作。

本仓库的其余部分将从最受限到最开放的模式逐一介绍，并展示如何使用CopilotKit来实现它们。

---

生成式UI的三种类型

1. 受控生成式UI (AG-UI)

受控生成式UI意味着你预先构建好UI组件，而智能体则决定显示哪个组件，并为其传递所需的数据。

这是控制程度最高的方式：布局、样式和交互模式都由你掌控，而智能体则控制何时以及显示哪个UI组件。

在CopilotKit中，这种模式是通过useFrontendTool钩子实现的，它允许应用程序注册get_weather工具，并定义在该工具执行生命周期的每个阶段如何渲染预定义的React UI。

// 天气工具——一个可调用的工具，以样式化的卡片形式显示天气数据
useFrontendTool({
  name: "get_weather",
  description: "获取某个地点的当前天气信息",
  parameters: z.object({ location: z.string().describe("要查询天气的城市或地点") }),
  handler: async ({ location }) => {
    await new Promise((r) => setTimeout(r, 500));
    return getMockWeather(location);
  },
  render: ({ status, args, result }) => {
    if (status === "inProgress" || status === "executing") {
      return <WeatherLoadingState location={args?.location} />;
    }
    if (status === "complete" && result) {
      const data = JSON.parse(result) as WeatherData;
      return (
        <WeatherCard
          location={data.location}
          temperature={data.temperature}
          conditions={data.conditions}
          humidity={data.humidity}
          windSpeed={data.windSpeed}
        />
      );
    }
    return <></>;
  },
});

• 试一试：go.copilotkit.ai/gen-ui-demo
• 文档：docs.copilotkit.ai/generative-ui
• 规范中心（概览）：docs.copilotkit.ai/learn/generative-ui/specs
• 生态系统（规范与运行时如何配合）：copilotkit.ai/generative-ui

---

2. 声明式生成式 UI（A2UI + Open‑JSON‑UI）

声明式生成式 UI 处于受控与开放式方法之间。在此模式下，代理会返回结构化的 UI 描述（卡片、列表、表单、小部件），前端则负责渲染这些内容。

用于生成式 UI 的两种常见声明式规范是 A2UI 和 Open-JSON-UI。

1. A2UI → 来自 Google 的声明式生成式 UI 规范，基于 JSONL 并支持流式传输，旨在实现跨平台的渲染兼容性。

2. Open‑JSON‑UI → OpenAI 内部声明式生成式 UI 架构的开放标准化方案。

我们首先来了解如何实现 A2UI 的基本流程。

与其手动编写 A2UI JSON，不如使用 A2UI Composer 自动生成规范。将生成的输出复制并粘贴到代理的提示中，作为参考模板。

在 prompt_builder.py 中，添加一个 A2UI JSONL 示例，使代理能够学习 A2UI 所期望的三种消息封装：surfaceUpdate（组件）、dataModelUpdate（状态），以及 beginRendering（渲染信号）。

UI_EXAMPLES = """
---BEGIN FORM_EXAMPLE---
{"surfaceUpdate":{"surfaceId":"form-surface","components":[ ... ]}}
{"dataModelUpdate":{"surfaceId":"form-surface","path":"/","contents":[ ... ]}}
{"beginRendering":{"surfaceId":"form-surface","root":"form-column","styles":{ ... }}}
---END FORM_EXAMPLE---
"""

将 UI_EXAMPLES 注入代理指令中，使其在请求 UI 时能够输出有效的 A2UI 消息行。

instruction = AGENT_INSTRUCTION + get_ui_prompt(self.base_url, UI_EXAMPLES)

return LlmAgent(
    model=LiteLlm(model=LITELLM_MODEL),
    name="ui_generator_agent",
    description="通过 A2UI 声明式 JSON 生成动态 UI。",
    instruction=instruction,
    tools=[],
)

最后一步：在前端，将 createA2UIMessageRenderer(...) 传递给 renderActivityMessages，以便 CopilotKit 能够将流式传输的 A2UI 输出渲染为 UI，并将 UI 操作反馈回代理。

import { CopilotKitProvider, CopilotSidebar } from "@copilotkitnext/react";
import { createA2UIMessageRenderer } from "@copilotkit/a2ui-renderer";
import { a2uiTheme } from "../theme";

const A2UIRenderer = createA2UIMessageRenderer({ theme: a2uiTheme });

export function A2UIPage({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider
      runtimeUrl="/api/copilotkit-a2ui"
      renderActivityMessages={[A2UIRenderer]}   // ← 将 A2UI 渲染器挂载进来
    >
      {children}
      <CopilotSidebar defaultOpen labels={{ modalHeaderTitle: "A2UI 助手" }} />
    </CopilotKitProvider>
  );
}

以下是一个使用 A2UI 和 Agent Spec 的日历演示：

https://github.com/user-attachments/assets/48158b9d-188d-42d1-835b-32d7425cc43a

对于 Open‑JSON‑UI，模式相同。代理可以响应一个 Open‑JSON‑UI 负载，以 JSON 格式描述一个 UI“卡片”，而前端则负责渲染它。

// 示例（示意性）：代理返回声明式 Open-JSON-UI 风格的规范
{
  type: "open-json-ui",
  spec: {
    components: [
      {
        type: "card",
        properties: {
          title: "数据可视化",
          content: { ... }
        }
      }
    ]
  }
}

• 试用：go.copilotkit.ai/gen-ui-demo
• 文档：docs.copilotkit.ai/generative-ui
• Open‑JSON‑UI 规范（CopilotKit 文档）：docs.copilotkit.ai/learn/generative-ui/specs/open-json-ui
• A2UI 规范（CopilotKit 文档）：docs.copilotkit.ai/learn/generative-ui/specs/a2ui
• 示例（A2UI + Agent Spec）：github.com/CopilotKit/with-agent-spec
• 生态系统（规范与运行时的配合）：copilotkit.ai/generative-ui
• AG‑UI 与 A2UI 的结合方式：copilotkit.ai/ag-ui-and-a2ui

---

3. 开放式生成式 UI（MCP 应用）

https://github.com/user-attachments/assets/48eeab8d-7845-4d06-83ef-d518a807da03

开放式生成式 UI 是指代理返回完整的 UI 界面（通常是 HTML/iframes/自由格式内容），而前端主要充当展示该界面的容器。

这种方式的权衡较高：渲染任意内容可能带来安全和性能方面的顾虑，样式一致性难以保证，且在 Web 之外的可移植性较差。

这种模式常用于 MCP 应用。在 CopilotKit 中，可以通过将 MCPAppsMiddleware 添加到代理中来启用对 MCP 应用的支持，从而使运行时能够连接到一个或多个 MCP 应用服务器。

import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";

const agent = new BuiltInAgent({
  model: "openai/gpt-5.2",
  prompt: "您是一位乐于助人的助手。",
}).use(
  new MCPAppsMiddleware({
    mcpServers: [
      {
        type: "http",
        url: "https://mcp.excalidraw.com/mcp", // 或者您的本地服务器：http://localhost:3001/mcp
        serverId: "my-server",
      },
    ],
  }),
);

• 试用：go.copilotkit.ai/gen-ui-demo
• 实验室仓库：examples/showcases/mcp-apps
• 文档：docs.copilotkit.ai/generative-ui
• MCP 应用规范：docs.copilotkit.ai/learn/generative-ui/specs/mcp-apps
• 实用指南（完整集成流程）：使用 CopilotKit 和 AG‑UI 将 MCP 应用引入您的应用

现实世界案例：Excalidraw MCP 应用

我们使用 CopilotKit 和一个经过修改的 Excalidraw MCP 服务器，构建了一款由 MCP 提供支持的 AI 绘图应用。只需在聊天中描述任何内容，几秒钟内即可获得一个完全可编辑的 Excalidraw 图表。

src/app/api/copilotkit/route.ts 中完整的 CopilotKit 运行时设置如下：

import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { NextRequest } from "next/server";
import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";

const agent = new BuiltInAgent({
  model: "openai/gpt-5",
  prompt: `You are an AI diagramming assistant powered by Excalidraw...`, // 完整提示词见仓库
}).use(
  new MCPAppsMiddleware({
    mcpServers: [
      {
        type: "http",
        url: process.env.MCP_SERVER_URL ?? "http://localhost:3001/mcp",
        serverId: "excalidraw",
      },
    ],
  }),
);

const serviceAdapter = new ExperimentalEmptyAdapter();

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
});

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

该代理会向 MCP 服务器发送包含 Excalidraw 元素的 JSON 数组，并调用 create_view 方法；CopilotKit 则通过 MCP Apps 协议直接在聊天界面中渲染出相应的 iframe。我们还对原始的 Excalidraw MCP 服务器进行了扩展，增加了检查点存储、REST 工作区端点、流式传输以及小部件按钮等功能。每个图表都会自动保存到磁盘，并以完整可编辑画布的形式打开。只需点击一下，即可将任意图表从聊天中直接发布到 Excalidraw 上。

• 仓库：github.com/CopilotKit/excalidraw-studio
• Excalidraw MCP 服务器：github.com/excalidraw/excalidraw-mcp

https://github.com/user-attachments/assets/18dd56de-6f14-4a1d-b743-52fccf145bbe

---

4. 开放式生成式 UI（useComponent）

OpenGenerativeUI 是一个开源示例项目，展示了如何使用 CopilotKit 和 LangGraph 构建丰富且交互式的用户界面。它采用了与 MCP Apps 相同的开放性理念，但架构有所不同。

不同于连接外部 MCP 服务器的方式，LangGraph 代理可以直接生成原始的 HTML/SVG/Canvas 内容，而前端的 useComponent 则会将其作为命名工具调用接收，并在一个带有主题的沙盒 iframe 中渲染出来。该代理可以生成算法可视化、3D 动画（Three.js、WebGL）、图表、交互式模拟、数学绘图、D3 力布局等任何可以用自包含 HTML 表达的内容。

import { useComponent } from "@copilotkit/react-core/v2";
import {
  WidgetRenderer,
  WidgetRendererProps,
} from "@/components/generative-ui/widget-renderer;

// 注册一个命名组件：代理会调用 "widgetRenderer"，传入
// { title, description, html } 参数，前端则会在沙盒 iframe 中渲染
useComponent({
  name: "widgetRenderer",
  description:
    "在沙盒 iframe 中渲染交互式 HTML/SVG 可视化内容。" +
    "适用于算法可视化、图表、小部件和模拟场景。",
  parameters: WidgetRendererProps,
  render: WidgetRenderer,
});

useComponent 与 MCP Apps 的区别：在 MCP Apps 中，代理会调用远程服务器上的工具，然后由服务器返回一个 iframe 的 URL，主要的工作负载都在服务器端完成。而在 useComponent 中，代理直接生成内容（HTML 字符串），并通过工具调用本身传递给前端。无需服务器往返，也没有 URL，只有结构化的输出，由前端组件按需渲染。

• 仓库：github.com/CopilotKit/OpenGenerativeUI

https://github.com/user-attachments/assets/ed28c734-e54e-4412-873f-4801da544a7f

---

生成式 UI 演示平台

生成式 UI 演示平台是一个实践环境，用于探索这三种模式的实际运作方式，并实时观察代理输出如何映射到 UI 上。

• 体验地址：go.copilotkit.ai/gen-ui-demo
• 仓库：go.copilotkit.ai/gen-ui-repo-playground

https://github.com/user-attachments/assets/f2f52fae-c9c6-4da5-8d29-dc99b202a7ad

相关博客文章

• 2026 年开发者指南：生成式 UI - CopilotKit
• Agent Factory：智能体 AI 新时代——常见用例与设计模式 - 微软 Azure
• 智能体 AI 与 AI 智能体：深度解析 - UI Bakery
• 引入智能体 UI 界面：战术执行指南 - AKF Partners
• 推出 A2UI：面向智能体驱动界面的开放项目 - Google Developers
• 从产品到系统：智能体 AI 的转变 - UX Collective
• 生成式 UI：为任何提示提供丰富、定制化、可视化的交互式用户体验 - Google Research
• 智能体 UI 现状：AG-UI、MCP-UI 和 A2UI 协议对比 - CopilotKit
• 生成式 UI 的三种类型：受控式、声明式与完全生成式 - CopilotKit
• 2025 年生成式 UI 指南：15 条最佳实践与示例 - Mockplus
• 开发者指南：AI 智能体协议 - Google Developers

视频

• AI 代理现在可以实时构建属于自己的 UI（个性化定制）
• 用通俗易懂的方式解释代理式 AI，人人都能看懂！
• 生成式 vs 代理式 AI：塑造 AI 协作的未来
• 生成式 UI：规范、模式及其背后的协议（MCP Apps、A2UI、AG-UI）
• ASP.NET 社区站立会议——使用 AG-UI 和 Blazor 构建代理式 UI
• The Dojo：为你的 UI 打造的代理式构建模块
• 什么是代理式 AI？给所有人的简单解释
• 什么是代理式 AI？它又是如何工作的？

其他资源

• 代理式协议全景图
• 生成式 UI PDF 下载
• 构建代理式应用的 12 条注意事项与禁忌

---

🤝 欢迎贡献

欢迎贡献：可通过 PR 添加示例（受控式、声明式、开放式）、改进说明或增加素材。

如需帮助或讨论，请加入 Discord。如需贡献代码，请访问 GitHub。关注 @CopilotKit 获取最新动态。

项目	预览	描述	链接
开放式生成式 UI		开放式的生成式 UI：代理生成 HTML/SVG 视觉内容，并在沙盒 iframe 中渲染，无需 MCP 服务器。	仓库
生成式 UI 演示平台		展示三种生成式 UI 模式，并提供可运行的端到端示例。	仓库 演示
Excalidraw MCP 应用		描述任何内容，即可通过 MCP 应用在聊天中获得一个完全可编辑的 Excalidraw 流程图。	仓库

你构建了什么吗？请 打开 PR 或在 Discord 上分享吧。

关于 AI/LLM 代理：docs.copilotkit.ai/llms.txt

---

注： 本项目已整合至 CopilotKit 单体仓库。 最新版本位于 examples/showcases/generative-ui。 请在 主 CopilotKit 仓库 中提交问题和拉取请求。

Generative UI 快速上手指南

Generative UI 是一种由 AI 代理在运行时动态生成、选择或控制部分用户界面的模式。本指南基于 CopilotKit 生态，帮助你快速构建适应性强、能随上下文变化的智能应用界面。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• Node.js: 版本 18.0 或更高（推荐 v20+）。
• 包管理器: npm, yarn, pnpm 或 bun。
• 前端框架: React (Next.js, Vite 等)。
• 后端环境: 支持 Node.js 或 Python 的后端服务（用于运行 Agent）。
• API Key: 准备好 OpenAI 或其他大模型服务商的 API Key。

提示：国内开发者若遇到 npm 安装缓慢问题，建议使用国内镜像源：

npm config set registry https://registry.npmmirror.com

安装步骤

1. 初始化项目

如果你还没有项目，可以快速创建一个 Next.js 示例项目：

npx create-next-app@latest my-generative-ui-app --typescript --tailwind --eslint
cd my-generative-ui-app

2. 安装 CopilotKit 核心依赖

安装 React 客户端 SDK 和运行时库：

npm install @copilotkit/react @copilotkit/runtime

3. 安装特定协议渲染器（可选）

根据你选择的 Generative UI 类型，可能需要安装额外的渲染器：

• 声明式 UI (A2UI):

  npm install @copilotkit/a2ui-renderer
  

• MCP Apps:

  npm install @ag-ui/mcp-apps-middleware
  

基本使用

Generative UI 主要有三种实现模式，以下展示最常用且易于上手的 受控式 Generative UI (Controlled Generative UI) 的最小化实现流程。

场景：创建一个天气查询工具

当用户询问天气时，Agent 不仅返回文本，还会触发一个预定义的 React 组件来展示结构化数据。

第一步：配置 Provider

在应用的根组件（如 layout.tsx 或 App.tsx）中包裹 CopilotKitProvider。

// app/layout.tsx 或 src/App.tsx
import { CopilotKitProvider } from "@copilotkit/react";
import { CopilotSidebar } from "@copilotkit/react-ui";
import "@copilotkit/react-ui/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      {children}
      <CopilotSidebar 
        defaultOpen 
        labels={{ modalHeaderTitle: "AI 助手" }} 
      />
    </CopilotKitProvider>
  );
}

第二步：定义前端工具 (Frontend Tool)

在你的页面组件或自定义 Hook 中，使用 useFrontendTool 注册工具。这将告诉 Agent 何时调用该工具，并定义不同状态下的 UI 渲染逻辑。

// components/WeatherTool.tsx
import { useFrontendTool } from "@copilotkit/react";
import { z } from "zod";

// 模拟获取天气数据
const getMockWeather = (location: string) => ({
  location,
  temperature: 24,
  conditions: "晴朗",
  humidity: 45,
  windSpeed: 12
});

export function WeatherTool() {
  useFrontendTool({
    name: "get_weather",
    description: "Get current weather information for a location",
    parameters: z.object({ 
      location: z.string().describe("The city or location to get weather for") 
    }),
    handler: async ({ location }) => {
      // 模拟延迟
      await new Promise((r) => setTimeout(r, 500));
      return JSON.stringify(getMockWeather(location));
    },
    render: ({ status, args, result }) => {
      // 1. 加载中状态
      if (status === "inProgress" || status === "executing") {
        return <div className="p-4 bg-blue-50 rounded">正在查询 {args?.location} 的天气...</div>;
      }
      
      // 2. 完成状态：渲染自定义卡片
      if (status === "complete" && result) {
        const data = JSON.parse(result);
        return (
          <div className="p-6 border rounded-lg shadow-sm bg-white max-w-sm">
            <h3 className="text-xl font-bold">{data.location}</h3>
            <p className="text-3xl my-2">{data.temperature}°C</p>
            <div className="text-gray-600 flex justify-between">
              <span>{data.conditions}</span>
              <span>湿度：{data.humidity}%</span>
            </div>
          </div>
        );
      }
      return null;
    },
  });

  return null;
}

第三步：创建后端路由

设置 API 路由以连接 Agent 运行时。

// app/api/copilotkit/route.ts
import { CopilotRuntime, OpenAIAdapter } from "@copilotkit/runtime";

export const POST = async (req: Request) => {
  const runtime = new CopilotRuntime();
  
  const adapter = new OpenAIAdapter({
    model: "gpt-4o", // 或你使用的其他模型
  });

  return runtime.handleRequest(req, adapter);
};

第四步：运行与测试

启动开发服务器：

npm run dev

打开浏览器访问应用，在侧边栏输入：“帮我查一下北京的天气”。 预期结果：Agent 将识别意图，调用 get_weather 工具，并在聊天界面中直接渲染出你在 render 函数中定义的天气卡片组件，而不仅仅是纯文本回复。

---

进阶提示：

• 若需更灵活的动态布局，可探索 Declarative Generative UI (A2UI)，通过 JSON 描述让 Agent 动态组合组件。
• 若需嵌入完整的第三方应用（如 Excalidraw），可使用 Open-ended Generative UI (MCP Apps) 模式。