你的 React 应用还在让 AI 只输出文字？CopilotKit 可以让它直接渲染组件

可能很多人都注意到了这样一个场景：当你问AI天气时，它只给你一段文字；问数据时，给你一个Markdown表格。但你精心设计的组件——有动画、有图标、有交互——它却连碰都碰不到，只能在旁边说话。

这就是大多数“AI接入React应用”教程的终点。能用，但跟你精心打磨的组件比起来，差了一个维度。

CopilotKit要解决的，正是这个核心矛盾。

先说清楚问题在哪

跟LLM API打过交道的人都清楚，模型返回的是文字流。你拿到文字，渲染成Markdown，最多高亮一下代码块——这基本就是99%的AI聊天接入方案的底子了。

但这个方案的上限很低：

，你能返回一段描述，或者一个纯文本表格。但你没办法直接弹出一个带筛选、排序、图表的组件——因为AI根本不知道你有这么个组件，更搞不清楚怎么调它。

本质上，AI只是在你的应用旁边唠嗑，并没有真正进入你的应用。

：把你的React组件注册成AI可以调用的“工具”。AI负责决定什么时候调用、传什么数据，你的组件则专心负责渲染。

Generative UI的三种模式

在聊具体代码前，先把概念理清楚。如今“Generative UI”这个词几乎被用烂了，不同地方说的压根不是一回事。

按CopilotKit官方仓库的分类，目前有三种模式：

模式	控制权	代表协议
Controlled（受控）	开发者写组件，AI选何时渲染	AG-UI
Declarative（声明式）	AI生成组件描述，客户端渲染	A2UI
Open-ended（开放式）	AI生成完整UI（HTML/代码）	MCP Apps

这三种模式实际上是一个“控制权 vs 自由度”的光谱。

自由度最高，AI生成什么就渲染什么，但风险高、样式不可控、安全边界模糊——就像让AI直接写你的前端代码，想想就有点头大。

则最稳：你写好自己的所有组件，AI只是决定“现在该渲染哪个、传什么数据”。布局、样式、交互全在你掌控里。

这篇重点说

，对应CopilotKit的useFrontendTool hook。这是最适合生产环境的用法，也是上手最快的起点。

useFrontendTool：核心API

useFrontendTool做的事很纯粹：把一个React组件注册成AI可以触发的工具。

npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime

import { useFrontendTool } from "@copilotkit/react-core";
import { z } from "zod";

function WeatherWidget() {
  useFrontendTool({
    name: "get_weather",
    description: "获取某个城市的当前天气，并以卡片形式展示",
    parameters: z.object({
      location: z.string().describe("城市名称，例如：北京、上海"),
    }),
    handler: async ({ location }) => {
      // 这里调你自己的天气 API
      const data = await fetchWeather(location);
      return data;
    },
    render: ({ status, args, result }) => {
      // inProgress：AI 正在调用中
      if (status === "inProgress" || status === "executing") {
        return ;
      }
      // complete：有结果了，渲染真实组件
      if (status === "complete" && result) {
        return ;
      }
      return null;
    },
  });

  return null; // 这个组件本身不渲染任何东西
}

三个关键字段：

• handler：AI调用工具时执行的逻辑，运行在

（不是服务端），可以直接访问前端状态
• render：根据执行状态渲染不同的UI，status有inProgress/executing/complete三种
• description：AI靠这个判断什么时候该调这个工具，写清楚，别写废话

完整流程走一遍

光看API还不够，把整个链路串起来就清晰了。

// app/layout.tsx（Next.js 示例）
import { CopilotKit } from "@copilotkit/react-core";

export default function RootLayout({ children }) {
  return (
    
      {children}
    
  );
}

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

const runtime = new CopilotRuntime();

export const POST = async (req: Request) => {
  const { handleRequest } = runtime.process({
    serviceAdapter: new GoogleGenerativeAIAdapter({
      model: "gemini-2.0-flash",
    }),
  });
  return handleRequest(req);
};

CopilotKit支持OpenAI、Anthropic、Google等主流模型，换adapter就行。

// components/ChatPanel.tsx
import { CopilotChat } from "@copilotkit/react-ui";
import "@copilotkit/react-ui/styles.css";

export function ChatPanel() {
  // 注册天气工具
  useFrontendTool({ /* 上面的配置 */ });

  return (
    
  );
}

就这三步。用户在聊天框输入“北京今天天气怎么样”，AI识别到意图 → 调get_weather工具 → handler取数据 → render拿到数据渲染。用户看到的不是一段文字，是一个真实的天气组件。

render的状态机值得重点理解

render接收的status是整个体验质量的关键。很多人只用了complete就收工了，其实inProgress阶段更重要。

render: ({ status, args, result }) => {
  // 工具调用中：args 已有，result 还没有
  // 这时候 args.location 已经可以用了，可以先渲染 loading 态
  if (status === "inProgress") {
    return 
正在获取 {args?.location} 的天气...
;
  }

  // 工具执行中（handler 在跑）
  if (status === "executing") {
    return ;
  }

  // 完成
  if (status === "complete" && result) {
    return ;
  }

  return null;
},

inProgress阶段，AI已经决定要调这个工具、参数也知道了，但handler还没执行完。这时候你可以先把城市名展示出来，让用户感觉响应很快——这和普通loading转圈比起来，体验差距是肉眼可见的。

和你现有组件库完全兼容

这点是useFrontendTool被低估的优点：你现有的组件一行都不用改。

你已经有的、、——只要把它们包进useFrontendTool的render里，AI就能调用。不需要专门为AI重写一套组件，更不用改变组件的props结构。

// 你已有的组件，不用改
function SalesChart({ data, period, region }) { /* ... */ }

// 只需要在 useFrontendTool 里引用它
useFrontendTool({
  name: "show_sales_chart",
  description: "显示销售数据图表，支持按时间段和地区筛选",
  parameters: z.object({
    period: z.enum(["day", "week", "month"]),
    region: z.string().optional(),
  }),
  handler: async ({ period, region }) => fetchSalesData(period, region),
  render: ({ status, result }) =>
    status === "complete" ?  : ,
});

一个容易踩的坑

handler运行在浏览器端，这当然是好事，但也意味着它能访问你的前端state——你得想清楚哪些state该暴露、哪些不该。

如果你的handler里写了const { user } = useAuthStore()这样的调用，它读到的是当前登录用户的数据。这当然可以用，但如果你同时在description写了“可以查看任意用户的数据”，那问题就来了——AI可能被诱导调用本不该调的逻辑。

：handler里的逻辑要像普通React事件处理一样对待，该鉴权的鉴权，该边界检查的检查，别因为是“AI调的”就放松警惕。

适合用CopilotKit的场景

不是所有React应用都需要CopilotKit，这点必须说实话。

• 数据密集型后台（报表、仪表盘），用户经常需要“帮我看看XX数据”
• 有大量表单的应用，AI可以帮用户填写、校验
• 项目管理类工具，AI可以直接创建、修改任务卡片
• 任何“用户用自然语言描述需求，系统操作UI响应”的场景

• 简单的问答类产品，文字返回足够
• UI结构极简的工具，没什么值得渲染的组件
• 对bundle size极敏感的场景（CopilotKit有一定体积）

现在的生态位置

CopilotKit在2026年完成了$2700万融资（据行业报道），AG-UI协议也在Vercel、LangChain等生态里逐步被采用。它背后的AG-UI和Google主导的A2UI是同一个问题的不同解法：AI如何和前端界面安全地双向通信。

就目前来看，CopilotKit的Controlled模式（useFrontendTool）是最成熟、最适合生产落地的方案，因为控制权在开发者手里。如果想探索更开放的模式（AI直接生成组件描述），可以看他们的A2UI集成——不过那个还在早期，暂时不建议用到生产环境里。

总结

核心就一句话：

上手只需三步：

1. 用 Provider包裹应用
2. 建后端runtime路由（换个adapter就能换模型）
3. 用useFrontendTool注册组件，写好handler和render

如果你的React应用现在的AI能力还停在“聊天框里显示文字”，CopilotKit这方案值得认真评估一下。