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

你有没有注意到一件事:大多数「AI 接入 React 应用」的教程,最终都止步于同一个地方——对话框里显示一段文字。

问天气,返回「北京今天晴,气温23度」。

问数据,返回一段 Markdown 表格。

问任务状态,返回一坨 JSON。

这没什么问题,能用。但跟你精心设计的 React 组件比起来,差了一个维度。你的 <WeatherCard> 有动画、有图标、有交互——AI 却连碰都碰不到,只能在旁边说话。

CopilotKit 要解决的,就是这个问题。


先说清楚问题在哪

接过 LLM API 的都知道,模型返回的是文字流。你拿到文字,渲染成 Markdown,最多高亮一下代码块,这就是 99% 的 AI 聊天接入方案。

这个方案的上限很低:

用户问「帮我看下销售数据」,你能返回一段描述,或者一个纯文本表格。但你不能直接弹出一个带筛选、排序、图表的 <SalesDashboard> 组件——因为 AI 不知道你有这个组件,更不知道怎么调它。

本质上,AI 只是在你应用的旁边说话,没有真正进入你的应用。

CopilotKit 换了一个思路:把你的 React 组件注册成 AI 可以调用的「工具」,AI 决定什么时候调、传什么数据,你的组件负责渲染。


Generative UI 的三种模式

在讲具体代码之前,先把概念理清楚,因为「Generative UI」这个词现在被用烂了,不同地方说的其实是不同的东西。

根据 CopilotKit 官方的分类(来自其 generative-ui 仓库),有三种模式:

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

这三种模式是一个「控制权 vs 自由度」的光谱。

最右边(Open-ended) 自由度最高,AI 生成什么就渲染什么,但风险高、样式不可控、安全边界模糊。

最左边(Controlled) 最稳,你写好所有组件,AI 只是决定「现在该渲染哪个、传什么数据」——布局、样式、交互全在你掌控里。

这篇聚焦 Controlled 模式,对应 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 <WeatherSkeleton location={args?.location} />; } // complete:有结果了,渲染真实组件 if (status === "complete" && result) { return <WeatherCard {...result} />; } return null; }, });
return null; // 这个组件本身不渲染任何东西}

三个关键字段:

•handler:AI 调用工具时执行的逻辑,运行在浏览器里(不是服务端),可以直接访问前端状态•render:根据执行状态渲染不同的 UI,status 有 inProgress / executing / complete 三种•description:AI 靠这个判断什么时候该调这个工具,写清楚,别写废话

完整流程走一遍

光看 API 不够,把整个链路串起来:

第一步:Provider 包裹应用

// app/layout.tsx(Next.js 示例)import { CopilotKit } from "@copilot…
— 以上为试看内容(约 40%),开通会员后阅读全文 —