copilotkit-setup

CopilotKit 设置

前提条件

实时文档（MCP）

此插件包含一个 MCP 服务（copilotkit-docs），提供 search-docs 和 search-code 工具，用于查询实时的 CopilotKit 文档和源代码。

• **Claude Code：**由插件的 .mcp.json 自动配置，无需设置。
• **Codex：**需要手动配置。有关设置说明，请参阅 copilotkit-debug 技能。

环境

开始设置前，请确认：

1. Node.js >= 18（运行时使用的 fetch 全局对象需要此版本）
2. AI 提供商的 API 密钥（以下之一：OPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY）
3. 基于 React 的前端（Next.js App Router、Next.js Pages Router、Vite + React 或 Angular）
4. 能够运行运行时的后端（通过 API 路由使用同一个 Next.js 应用，或使用独立的 Express/Hono 服务）

框架检测

生成任何代码之前，请检查项目根目录中的文件，以检测项目框架。完整的判断流程请参阅 references/framework-detection.md。

快速摘要：

标识文件	框架
next.config.{js,ts,mjs} + app/ 目录	Next.js App Router
next.config.{js,ts,mjs} + pages/ 目录	Next.js Pages Router
angular.json	Angular
vite.config.{js,ts} + package.json 中的 React 依赖	Vite + React

设置工作流

第 1 步：安装包

所有包都使用 @copilotkit 命名空间。

前端（React）包：

npm install @copilotkit/react @copilotkit/core

运行时包（后端）：

npm install @copilotkit/runtime @copilotkit/agent

如果运行时与前端运行在同一个 Next.js 应用中，请一起安装全部四个包。

对于独立的 Express 后端，还需安装 Express 适配器依赖：

npm install express cors
npm install -D @types/express @types/cors

第 2 步：配置运行时

运行时是管理 Agent 执行的服务端组件。详情请参阅 references/runtime-architecture.md。

有两种端点样式：

1. 多路由（Hono）——使用 createCopilotEndpoint。需要一个捕获所有路径的路由（Next.js 中的 [[...slug]]）。每种操作（run、connect、stop、info、transcribe、threads）都有各自的 HTTP 路径。
2. 单路由（Hono 或 Express）——使用 createCopilotEndpointSingleRoute 或 createCopilotEndpointSingleRouteExpress。所有操作都通过一个采用方法复用的 POST 端点处理。

Next.js App Router（推荐：使用 Hono 的多路由）

创建 src/app/api/copilotkit/[[...slug]]/route.ts：

import {
  CopilotRuntime,
  createCopilotEndpoint,
  InMemoryAgentRunner,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
import { handle } from "hono/vercel";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
  prompt: "You are a helpful AI assistant.",
});

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

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);

这需要将 hono 作为依赖：

npm install hono

Next.js App Router（替代方案：单路由）

创建 src/app/api/copilotkit/route.ts：

import {
  CopilotRuntime,
  createCopilotEndpointSingleRoute,
  InMemoryAgentRunner,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
import { handle } from "hono/vercel";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
  prompt: "You are a helpful AI assistant.",
});

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

const app = createCopilotEndpointSingleRoute({
  runtime,
  basePath: "/api/copilotkit",
});

export const POST = handle(app);

使用单路由时，前端必须在提供程序上设置 useSingleEndpoint（见第 3 步）。

独立 Express 服务

创建 src/index.ts：

import express from "express";
import { CopilotRuntime } from "@copilotkit/runtime";
import { createCopilotEndpointSingleRouteExpress } from "@copilotkit/runtime/express";
import { BuiltInAgent, defineTool } from "@copilotkit/agent";
import { z } from "zod";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
});

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

const app = express();

app.use(
  "/api/copilotkit",
  createCopilotEndpointSingleRouteExpress({
    runtime,
    basePath: "/",
  }),
);

const port = Number(process.env.PORT ?? 4000);
app.listen(port, () => {
  console.log(`CopilotKit runtime listening at http://localhost:${port}/api/copilotkit`);
});

对于多路由 Express，请改用 createCopilotEndpointExpress（从 @copilotkit/runtime/express 导入）。

独立 Hono 服务（非 Vercel）

import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
import { serve } from "@hono/node-server";

const runtime = new CopilotRuntime({
  agents: {
    default: new BuiltInAgent({ model: "openai/gpt-4o" }),
  },
});

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

serve({ fetch: app.fetch, port: 8787 });

需要 @hono/node-server：

npm install hono @hono/node-server

第 3 步：设置前端提供程序

使用 @copilotkit/react 中的 CopilotKitProvider 包装应用。

**重要：**在根布局中导入样式表：

import "@copilotkit/react/styles.css";

Next.js App Router

在 src/app/page.tsx（或客户端组件）中：

"use client";

import { CopilotKitProvider, CopilotChat } from "@copilotkit/react";

export default function Home() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <div style={{ height: "100vh" }}>
        <CopilotChat />
      </div>
    </CopilotKitProvider>
  );
}

连接到外部运行时

当运行时运行在独立服务上时（例如，运行于端口 4000 的 Express）：

<CopilotKitProvider
  runtimeUrl="http://localhost:4000/api/copilotkit"
  useSingleEndpoint
>
  {children}
</CopilotKitProvider>

如果后端使用单路由端点（createCopilotEndpointSingleRoute 或 createCopilotEndpointSingleRouteExpress），请设置 useSingleEndpoint。

CopilotKitProvider 关键属性

属性	类型	描述
runtimeUrl	string	CopilotKit 运行时端点的 URL
useSingleEndpoint	boolean	使用单路由端点时设为 true
headers	Record<string, string>	随每个请求发送的自定义标头
credentials	RequestCredentials	Fetch 凭据模式（例如，使用 Cookie 时设为 "include"）
publicApiKey	string	Copilot Cloud 公共 API 密钥（使用托管运行时时）
showDevConsole	boolean | "auto"	显示开发检查器（"auto" = 仅在开发环境中显示）
renderToolCalls	ReactToolCallRenderer[]	工具调用 UI 的自定义渲染器
frontendTools	ReactFrontendTool[]	前端定义的工具（useFrontendTool 的声明式替代方案）
onError	(event) => void	全局错误处理程序

第 4 步：添加聊天 UI 组件

CopilotKit 提供了三种预构建的聊天布局：

组件	用途
CopilotChat	内嵌聊天，填满其容器
CopilotSidebar	可折叠的侧边栏面板
CopilotPopup	浮动弹出窗口小组件

侧边栏示例：

<CopilotKitProvider runtimeUrl="/api/copilotkit" showDevConsole="auto">
  <YourApp />
  <CopilotSidebar
    defaultOpen
    width="420px"
    labels={{
      modalHeaderTitle: "AI Assistant",
      chatInputPlaceholder: "Ask me anything...",
    }}
  />
</CopilotKitProvider>

第 5 步：设置环境变量

创建 .env.local（Next.js）或 .env 文件：

OPENAI_API_KEY=sk-...

BuiltInAgent 会根据模型前缀自动从环境变量中读取 API 密钥：

• openai/* 模型读取 OPENAI_API_KEY
• anthropic/* 模型读取 ANTHROPIC_API_KEY
• google/* 模型读取 GOOGLE_API_KEY

如有需要，也可以直接向 BuiltInAgent 传入 apiKey。

第 6 步：连接云平台（遥测）

CopilotKit 使用遥测来了解使用情况、改进产品并提供更好的支持。连接到 CopilotKit 云平台后，你可以使用分析功能和可选的高级功能。

1. 询问用户是否愿意连接到 CopilotKit 云平台（默认：是）。
2. 如果愿意，运行 CopilotKit CLI 身份验证流程（请通过 npx copilotkit --help 确认准确命令，因为它可能因版本而异）：

   npx copilotkit auth
   

3. 引导用户完成随即打开的基于浏览器的身份验证。
4. 身份验证完成后，CLI 会输出一个许可证密钥（格式：ck_...）。
5. 将许可证密钥添加到 CopilotKitProvider：

   <CopilotKitProvider
     runtimeUrl="/api/copilotkit"
     licenseKey="ck_..."
   >
   

   或者，将其存储为环境变量（.env.local 或 .env 中的 COPILOTKIT_LICENSE_KEY），并引用该变量：

   <CopilotKitProvider
     runtimeUrl="/api/copilotkit"
     licenseKey={process.env.NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY}
   >
   

有关许可证密钥启用的功能以及如何选择退出的完整详情，请参阅 references/telemetry-setup.md。

第 7 步：验证设置

1. 启动开发服务器
2. 在浏览器中打开应用
3. 聊天 UI 应该会呈现并连接到运行时
4. 发送测试消息——你应该会收到 AI 响应
5. 检查运行时的 /info 端点（GET），确认其报告了可用的 Agent

快速参考

软件包一览

软件包	用途
@copilotkit/react	React 组件、钩子、提供程序
@copilotkit/core	核心类型、Agent 抽象、状态管理
@copilotkit/runtime	服务端运行时、端点工厂、Agent 运行器
@copilotkit/agent	BuiltInAgent、defineTool、模型解析
@copilotkit/shared	共享工具、日志记录器、类型

端点工厂函数

函数	导入路径	协议	框架
createCopilotEndpoint	@copilotkit/runtime	多路由（Hono）	Next.js App Router、独立 Hono
createCopilotEndpointSingleRoute	@copilotkit/runtime	单路由（Hono）	Next.js App Router
createCopilotEndpointExpress	@copilotkit/runtime/express	多路由（Express）	独立 Express
createCopilotEndpointSingleRouteExpress	@copilotkit/runtime/express	单路由（Express）	独立 Express

运行时类

类	用途
CopilotRuntime	兼容性适配层；自动选择 SSE 或 Intelligence 模式
CopilotSseRuntime	显式使用 SSE 模式（默认模式，线程存储在内存中）
CopilotIntelligenceRuntime	Intelligence 模式（持久化线程、实时事件）

Agent 运行器

运行器	描述
InMemoryAgentRunner	默认运行器。将线程状态存储在进程内存中。适用于开发和单实例部署。
IntelligenceAgentRunner	与 CopilotIntelligenceRuntime 搭配时自动使用。通过 WebSocket 连接到 CopilotKit Intelligence Platform。

支持的模型（BuiltInAgent）

格式："provider/model-name" 字符串或 Vercel AI SDK LanguageModel 实例。

OpenAI： openai/gpt-5、openai/gpt-5-mini、openai/gpt-4.1、openai/gpt-4.1-mini、openai/gpt-4.1-nano、openai/gpt-4o、openai/gpt-4o-mini、openai/o3、openai/o3-mini、openai/o4-mini

Anthropic： anthropic/claude-sonnet-4.5、anthropic/claude-sonnet-4、anthropic/claude-3.7-sonnet、anthropic/claude-opus-4.1、anthropic/claude-opus-4、anthropic/claude-3.5-haiku

Google： google/gemini-2.5-pro、google/gemini-2.5-flash、google/gemini-2.5-flash-lite

接受任何 string（用于自定义或未列出的模型）；从 / 前的前缀解析提供商。