前言

AI Agent的热度持续飙升，但很多开发者在构建Agent应用时都遇到了同一个难题：如何设计一个既灵活又用户友好的前端界面？

传统的聊天UI已经无法满足需求------我们需要的是一种能根据任务动态生成UI组件的能力。比如：当用户问"帮我分析这份销售数据"时，Agent不仅要给出文字回复，还要能实时生成数据可视化图表、交互式表格，甚至是一个可操作的控制面板。

这就是生成式UI（Generative UI）的核心价值。而今天我们要深入研究的 CopilotKit，正是目前GitHub上最火的生成式UI框架，今天更是冲上了GitHub趋势榜第一名。

什么是CopilotKit？

CopilotKit 是一个开源的前端Agent开发框架，官方定位为：

"The Frontend Stack for Agents & Generative UI"

简单来说，它为你提供了构建AI Agent应用所需的所有前端基础设施，包括：

• 🤖 Agent运行时：管理AI对话状态、工具调用、上下文记忆

• 🎨 生成式UI组件：根据Agent回复动态渲染交互组件

• 🔄 实时流式传输：支持打字机效果、流式输出

• 🔌 多平台支持：React、Angular、Next.js、移动端、Slack等

核心特性一览

特性说明

AG-UI Protocol 开源的Agent UI通信协议，支持跨框架互操作

Generative UI 根据AI输出动态生成React组件

Tool Calling 内置工具调用框架，支持函数定义、参数验证

Streaming 完整的流式传输支持，包括文字和UI组件

Multi-model 支持OpenAI、Anthropic、Google等主流LLM

环境准备

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

系统要求

Node.js >= 18.0.0

npm >= 9.0.0 或 yarn >= 1.22.0

安装方式

方式一：通过Create Next App快速创建

bash 复制代码

npx create-next-app@latest my-copilot-app --typescript
cd my-copilot-app
npm install copilotkit @copilotkit/react-core @copilotkit/react-ui

方式二：手动添加到现有项目

bash 复制代码

# 核心包
npm install @copilotkit/react-core @copilotkit/react-ui

可选：Agent运行时（如果使用自定义后端）

bash 复制代码

npm install @copilotkit/runtime

项目结构建议

my-copilot-app/

├── app/

│ ├── page.tsx # 主页面

│ └── layout.tsx # 布局文件

├── components/

│ └── CopilotChat.tsx # 自定义聊天组件

├── lib/

│ └── copilot.ts # CopilotKit配置

└── package.json

实战：从零构建AI Agent聊天应用

第一步：初始化CopilotKit

在 lib/copilot.ts 中配置CopilotKit：

TypeScript 复制代码

// lib/copilot.ts
import { CopilotKit } from "@copilotkit/react-core";

export function CopilotProvider({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKit
      // 使用OpenAI作为默认模型
      runtimeURL="https://runtime.copilotkit.ai"
      defaultModel="gpt-4o"
      // 可选：自定义API密钥（生产环境建议使用环境变量）
      // apiKey={process.env.OPENAI_API_KEY}
    >
      {children}
    </CopilotKit>
  );
}

第二步：定义Agent工具

工具是Agent能力的核心。让我们定义一个天气查询工具：

TypeScript 复制代码

// lib/tools.ts
import { tool } from "@copilotkit/react-core";
import { z } from "zod";

export const weatherTools = [
  tool({
    name: "get_weather",
    description: "查询指定城市的天气信息",
    parameters: z.object({
      city: z.string().describe("城市名称，如'北京'、'Shanghai'"),
      unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
    }),
    execute: async ({ city, unit }) => {
      // 实际应用中调用天气API
      // 这里用模拟数据演示
      const mockWeather = {
        city,
        temperature: unit === "celsius" ? 25 : 77,
        condition: "晴朗",
        humidity: "65%",
        wind: "东北风 3级",
      };
      return mockWeather;
    },
  }),
  tool({
    name: "search_web",
    description: "搜索互联网获取最新信息",
    parameters: z.object({
      query: z.string().describe("搜索关键词"),
    }),
    execute: async ({ query }) => {
      // 实际调用搜索API
      return { results: [`关于"${query}"的搜索结果...`] };
    },
  }),
];

第三步：创建生成式UI组件

这是CopilotKit的杀手级功能------根据AI回复动态生成UI：

TypeScript 复制代码

// components/WeatherCard.tsx
import { CopilotKit } from "@copilotkit/react-core";

interface WeatherData {
  city: string;
  temperature: number;
  condition: string;
  humidity: string;
  wind: string;
}

export function WeatherCard({ data }: { data: WeatherData }) {
  return (
    <div className="weather-card">
      <h3>🌤️ {data.city} 天气</h3>
      <div className="temp">{data.temperature}°{data.temperature === 25 ? 'C' : 'F'}</div>
      <p>{data.condition}</p >
      <div className="details">
        <span>湿度: {data.humidity}</span>
        <span>风向: {data.wind}</span>
      </div>
    </div>
  );
}

// 注册为生成式UI组件
CopilotKit.registerComponent({
  name: "weather-card",
  component: WeatherCard,
  schema: {
    city: { type: "string" },
    temperature: { type: "number" },
    condition: { type: "string" },
    humidity: { type: "string" },
    wind: { type: "string" },
  },
});

第四步：组装聊天界面

TypeScript 复制代码

// app/page.tsx
"use client";

import { CopilotKit } from "@copilotKit/react-core";
import { CopilotPopup } from "@copilotKit/react-ui";
import { weatherTools } from "@/lib/tools";
import { WeatherCard } from "@/components/WeatherCard";

export default function Home() {
  return (
    <main className="home-container">
      <h1>🚀 AI Agent 助手</h1>
      <p>点击右下角按钮开始对话</p >
      
      <CopilotKit
        tools={weatherTools}
        // 自定义UI组件映射
        components={{
          "weather-card": WeatherCard,
        }}
      >
        <CopilotPopup
          defaultOpen={false}
          labels={{
            title: "智能助手",
            placeholder: "问我任何问题...",
          }}
        />
      </CopilotKit>
    </main>
  );
}

第五步：运行项目

npm run dev

访问 http://localhost:3000，点击右下角的聊天按钮，开始与你的AI Agent对话！

使用指南：进阶技巧

自定义Agent行为

<CopilotKit

instructions={`

你是一个专业的数据分析助手。

当用户询问数据时，优先使用数据可视化工具。

保持回答简洁明了，多用表格和图表。

model="xxx"

流式UI更新

// 在工具执行中返回流式更新

execute: async function* ({ query }) {

yield { status: "loading", message: "正在搜索..." };

// 模拟耗时操作

await new Promise(r => setTimeout(r, 1000));

yield { status: "partial", results: $"结果1", "结果2"$ };

await new Promise(r => setTimeout(r, 500));

yield { status: "complete", results: $"结果1", "结果2", "结果3"$ };

}

对比：CopilotKit vs 其他方案

特性 CopilotKit Vercel AI SDK LangChain UI

生成式UI ✅ 原生支持 ⚠️ 需手动实现 ❌ 不支持

AG-UI协议 ✅ 开源标准 ❌ ❌

框架支持 React/Angular/Next React/Next React

学习曲线中等较低较高

社区规模 33,203⭐ 45,000+⭐ 88,000+⭐

文档质量 ⭐⭐⭐⭐ ⭐⭐⭐⭐⭐ ⭐⭐⭐

关键要点总结

CopilotKit 是构建AI Agent前端的首选框架，尤其适合需要动态UI的场景
生成式UI是其核心竞争力，让Agent能根据任务实时渲染交互组件
AG-UI协议是开源标准，未来可能成为Agent UI的通用协议
工具定义使用Zod，类型安全且易于验证
支持流式更新，用户体验更接近原生应用

结语

CopilotKit 的出现，标志着AI Agent开发从"能对话"向"能交互"的重要转变。随着生成式UI的普及，未来的AI应用将不再是简单的聊天窗口，而是能够根据任务需求动态生成复杂界面的智能助手。

CopilotKit实战：用生成式UI打造智能Agent前端

前言

什么是CopilotKit？

环境准备

可选：Agent运行时（如果使用自定义后端）

实战：从零构建AI Agent聊天应用

结语