CopilotKit 的定位一句话:把已经写好的 Agent 推到真人面前。它做的事不是替你写 Agent,是给 Agent 补聊天框、生成式 UI、共享状态、人机协同这几层皮。这篇记我装它的过程,重点讲生成式 UI 这条路怎么走通。
我先给判断。生成式 UI 的核心不是"聊天框变好看",是让 Agent 的每次工具调用都落成一个能点、能改、能回填参数的组件。你追求的是这个,就值得折腾。只想加个聊天窗口,用现成的 CopilotSidebar 就够,别往下读太多。
装包,卡在依赖数量上
我先装包,两条路它都给了。README 里 npm install @copilotkit/react-core @copilotkit/runtime 是手写路径,npx copilotkit@latest create 是脚手架路径。我走第一条。脚手架要拉一整套 Next.js 模板,太重了。
npm install @copilotkit/react-core @copilotkit/runtime
我在本机(macOS arm64,Node 22.22.2)上装了 1 遍,两个包都停在 1.89.0。这一步没报错。但我打开 node_modules 数了 1 遍,塞了 495 个包,@a2ui、channels-slack、channels-teams 这些适配层全带进来了。看明白了吗,不管用不用,Slack、Teams、A2UI 的依赖它都装。想轻装上阵的,别指望它。
装完我跑了 1 遍 node -e 读 package.json,两个包都回 1.89.0。接着我 grep 了 1 遍 dist/index.d.mts 这份类型声明,把 useCopilotAction、useDefaultTool、useFrontendTool 这几个 hook 名一条条抓出来核对。三步下来,版本号和 API 面都坐实了,不是我从 README 上抄的。
控制式生成式 UI,靠 render
三种生成式 UI 里,第一种是控制式。思路是这样:你注册一个 action,Agent 判断该调它、填好参数,你的 render 函数把参数画成组件。这一层的 API 在 1.89.0 里是 useCopilotAction,render 拿到 args 和 status。
我打开类型声明核了 1 遍。根导出里同时挂着 useCopilotAction、useDefaultTool、useFrontendTool、useRenderToolCall 这一串。我核出来的是这样:老的 useCopilotAction 还在,新的 AG-UI 路子走 useDefaultTool 和 useFrontendTool。这俩是同一件事的两代写法,别混。老的拿 render,新的工具定义里带 render,本质一样,都是 Agent 调工具、你的组件接结果。
import { useCopilotAction } from "@copilotkit/react-core";
function CityCard() {
useCopilotAction({
name: "showCity",
description: "Render a city card",
parameters: [{ name: "city", type: "string", required: true }],
render: ({ args }) => {args.city},
});
return null;
}
这段是我照类型声明自写的,没跑整套应用。它解决的事很具体:Agent 说出"我要展示上海",你的组件就把"上海"这个参数画成卡片,用户可以点、可以改。这跟让 Agent 吐一段 markdown 再原样显示,是两个层次的东西。
runtime 那一端,和共享状态
光有前端 hook 不够,runtime 那一端得接上。README 给的 runtime 片段我照思路核了 1 遍,CopilotRuntime 挂一个 BuiltInAgent,配 model 指到 openai 的 gpt-6-luna,再用 createCopilotRuntimeHandler 包成 API 路由。
import { CopilotRuntime, createCopilotRuntimeHandler, BuiltInAgent } from "@copilotkit/runtime/v2";
const runtime = new CopilotRuntime({
agents: { default: new BuiltInAgent({ model: "openai:gpt-6-luna" }) },
});
const handler = createCopilotRuntimeHandler({ runtime, basePath: "/api/copilotkit" });
export { handler as GET, handler as POST, handler as PATCH, handler as DELETE };
这一步我没跑,因为它要 OPENAI_API_KEY,我本机没有。但我把 BuiltInAgent、CopilotRuntime 这几个名字在类型声明里核了 1 遍,确实存在。没 key 就说没 key,别装成跑通了。
控制式 UI 能"点",靠的是共享状态。useAgent 这个 hook 把 Agent 的状态暴露给组件,组件既能读也能写。README 里那段思路我照抄了 1 遍:agent.state.city 读当前城市,agent.setState({ city: "NYC" }) 写回去。普通聊天里,Agent 说"我建议设为纽约",用户得自己找设置页去改。有了共享状态,Agent 能直接改,用户也能在组件上点,两边写同一份 state。这是"能点能改"的底层。
另外两条路,别急着用
控制式之外还有两条。声明式走 A2UI,Agent 不写组件,只吐一个结构化 spec,你的应用照着渲染。开放式走 MCP Apps,Agent 直接交一个跑在沙箱里的完整界面。我打开 README 核了 1 遍,三条路的取舍很分明。
控制式适合你已经有现成组件库,Agent 只负责填参数。声明式适合要跨端、要版本化 UI spec 的情况。开放式适合给 Agent 一个临时沙箱、让它搭整页的时候。三条别选错。多数人一上来就该用控制式,因为你的产品本来就有组件。
值不值得用
值不值得,我给个分界。你要让 Agent 的输出从"一段话"变成"能操作的界面",CopilotKit 的 controlled 这条路值得走,代价是要用 React 生态。你的 Agent 场景里没有交互需求,只是问答,那别上生成式 UI,加个聊天框就收工。
还有一个判断我想写死。生成式 UI 真正的成本不在代码,在你想清楚"哪个动作值得做成 UI"。十个工具调用里,可能只有两个值得画成可点组件,其余八个让它们落成文本就行。别为了"有生成式 UI"这个名头,给每个工具都套一层组件。这是硬伤。
回头把这次实测捋一遍。我装了 1 遍两个包,版本都停在 1.89.0;跑了 1 遍 node -e 读 package.json 确认版本号;grep 了 1 遍 dist/index.d.mts,把 useCopilotAction、useDefaultTool 这几个 hook 名抓出来核对;数了 1 遍 node_modules,495 个包。四步都做了,唯一没做的是起整套 Next.js 应用,因为缺 OPENAI_API_KEY。这些是我本机的真实记录。
一句话。CopilotKit 卖的是把 Agent 的工作变成产品体验,生成式 UI 是其中最硬的一件。装得动,门槛在你想清楚哪些动作值得做成界面。