CopilotKit: 31K+ Stars — 为任何 React 或 Angular 应用添加 AI Copilot — 2026 完整安装教程

# React 核心 + UI 组件 + 运行时
npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime

# LangChain 集成（可选）
npm install @copilotkit/runtime-langchain

# Groq 适配器（可选）
npm install @copilotkit/runtime groq-sdk

# .env.local
OPENAI_API_KEY=sk-your-openai-key
GROQ_API_KEY=gsk-your-groq-key
COPILOTKIT_API_KEY=ck-your-copilot-cloud-key  # 可选，用于云功能

import {
  CopilotRuntime,
  OpenAIAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { NextRequest } from "next/server";
import OpenAI from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const runtime = new CopilotRuntime({
  actions: [],
});

const serviceAdapter = new OpenAIAdapter({ openai, model: "gpt-4o" });

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

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

import { CopilotKit } from "@copilotkit/react-core";
import { CopilotSidebar } from "@copilotkit/react-ui";
import "@copilotkit/react-ui/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit">
      <CopilotSidebar
        defaultOpen={false}
        labels={{
          title: "AI 助手",
          initial: "你好！有什么可以帮你的？",
          placeholder: "输入消息...",
        }}
      >
        {children}
      </CopilotSidebar>
    </CopilotKit>
  );
}

npm run dev
# 打开 http://localhost:3000
# 点击 Copilot 按钮——你的 AI 助手已上线

// app/api/copilotkit/route.ts — OpenAI 版本
import { CopilotRuntime, OpenAIAdapter } from "@copilotkit/runtime";
import { copilotRuntimeNextJSAppRouterEndpoint } from "@copilotkit/runtime";
import OpenAI from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const runtime = new CopilotRuntime({ actions: [] });
const serviceAdapter = new OpenAIAdapter({ openai, model: "gpt-4o" });

export const POST = (req: NextRequest) =>
  copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  }).handleRequest(req);

// app/api/copilotkit/route.ts — LangChain 版本
import { CopilotRuntime, LangChainAdapter } from "@copilotkit/runtime";
import { ChatOpenAI } from "@langchain/openai";
import { NextRequest } from "next/server";

const runtime = new CopilotRuntime({ actions: [] });

export const POST = async (req: NextRequest) => {
  const model = new ChatOpenAI({
    modelName: "gpt-4o",
    openAIApiKey: process.env.OPENAI_API_KEY,
  });
  const serviceAdapter = new LangChainAdapter({ model });

  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

// app/api/copilotkit/route.ts — LangGraph 版本
import {
  CopilotRuntime,
  LangGraphHttpAgent,
} from "@copilotkit/runtime";
import { NextRequest } from "next/server";

const runtime = new CopilotRuntime({
  agents: {
    myAgent: new LangGraphHttpAgent({
      url: "http://localhost:8000/agent",
    }),
  },
});

const serviceAdapter = new OpenAIAdapter({
  openai: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
});

export const POST = (req: NextRequest) =>
  copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  }).handleRequest(req);

import {
  CopilotRuntime,
  GroqAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import Groq from "groq-sdk";
import { NextRequest } from "next/server";

const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });
const copilotKit = new CopilotRuntime();
const serviceAdapter = new GroqAdapter({
  groq,
  model: "llama3-groq-8b-8192-tool-use-preview",
});

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime: copilotKit,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });
  return handleRequest(req);
};

// app/components/TaskManager.tsx
"use client";

import { useState } from "react";
import { useCopilotReadable, useCopilotAction } from "@copilotkit/react-core";

interface Task {
  id: string;
  title: string;
  completed: boolean;
  priority: "low" | "medium" | "high";
}

export function TaskManager() {
  const [tasks, setTasks] = useState<Task[]>([
    { id: "1", title: "审查 PR #42", completed: false, priority: "high" },
    { id: "2", title: "更新 API 文档", completed: true, priority: "medium" },
  ]);

  // 向 LLM 暴露任务状态
  useCopilotReadable({
    description: "用户当前的任务列表，包括完成状态和优先级",
    value: tasks,
  });

  // 操作：添加新任务
  useCopilotAction({
    name: "addTask",
    description: "向任务列表添加新任务",
    parameters: [
      {
        name: "title",
        type: "string",
        description: "要添加的任务标题",
        required: true,
      },
      {
        name: "priority",
        type: "string",
        description: "优先级：low、medium 或 high",
        required: false,
      },
    ],
    handler: ({ title, priority = "medium" }) => {
      const newTask: Task = {
        id: Date.now().toString(),
        title,
        completed: false,
        priority: priority as Task["priority"],
      };
      setTasks((prev) => [...prev, newTask]);
      return `已添加任务："${title}"，优先级 ${priority}`;
    },
  });

  // 操作：将任务标记为完成
  useCopilotAction({
    name: "completeTask",
    description: "按标题或 ID 将任务标记为已完成",
    parameters: [
      {
        name: "taskId",
        type: "string",
        description: "要标记为完成的任务 ID",
        required: true,
      },
    ],
    handler: ({ taskId }) => {
      setTasks((prev) =>
        prev.map((t) => (t.id === taskId ? { ...t, completed: true } : t))
      );
      return `已将任务 ${taskId} 标记为已完成`;
    },
  });

  // 操作：删除任务
  useCopilotAction({
    name: "deleteTask",
    description: "从列表中删除任务",
    parameters: [
      {
        name: "taskId",
        type: "string",
        description: "要删除的任务 ID",
        required: true,
      },
    ],
    handler: ({ taskId }) => {
      setTasks((prev) => prev.filter((t) => t.id !== taskId));
      return `已删除任务 ${taskId}`;
    },
  });

  return (
    <div className="task-manager">
      <h2>我的任务 ({tasks.filter((t) => !t.completed).length} 待处理)</h2>
      <ul>
        {tasks.map((task) => (
          <li key={task.id} className={task.completed ? "done" : ""}>
            <span>[{task.priority}] {task.title}</span>
            {task.completed && <span className="badge">已完成</span>}
          </li>
        ))}
      </ul>
    </div>
  );
}

// 在 Copilot 聊天中渲染任务卡片
useCopilotAction({
  name: "showTaskDetails",
  description: "在聊天中显示详细的任务卡片",
  parameters: [
    { name: "taskId", type: "string", description: "要显示的任务 ID", required: true },
  ],
  render: ({ taskId }) => {
    const task = tasks.find((t) => t.id === taskId);
    if (!task) return <div>未找到任务</div>;
    return (
      <div className="task-card">
        <h4>{task.title}</h4>
        <span className={`priority-${task.priority}`}>{task.priority}</span>
        <p>状态：{task.completed ? "已完成" : "进行中"}</p>
      </div>
    );
  },
  handler: ({ taskId }) => `已显示任务 ${taskId} 的详情`,
});

# Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
ENV NODE_ENV=production
ENV PORT=3000
CMD ["npm", "start"]

# docker-compose.yml
version: "3.8"
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - COPILOTKIT_API_KEY=${COPILOTKIT_API_KEY}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3

// lib/copilot-config.ts
export const copilotConfig = {
  runtimeUrl: process.env.NEXT_PUBLIC_COPILOT_RUNTIME_URL || "/api/copilotkit",
  model: process.env.COPILOT_MODEL || "gpt-4o",
  maxTokens: parseInt(process.env.COPILOT_MAX_TOKENS || "4096"),
  temperature: parseFloat(process.env.COPILOT_TEMPERATURE || "0.7"),
  threadRetention: parseInt(process.env.COPILOT_THREAD_RETENTION || "3"), // 天
};

// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(20, "1 m"), // 每分钟 20 个请求
});

export async function middleware(req: NextRequest) {
  if (req.nextUrl.pathname === "/api/copilotkit") {
    const ip = req.ip ?? "127.0.0.1";
    const { success } = await ratelimit.limit(ip);
    if (!success) {
      return NextResponse.json({ error: "请求过于频繁" }, { status: 429 });
    }
  }
  return NextResponse.next();
}

// 将 LangSmith 追踪添加到运行时
import { Client } from "langsmith";

const langsmith = new Client({
  apiKey: process.env.LANGSMITH_API_KEY,
  projectName: "copilotkit-production",
});

const runtime = new CopilotRuntime({
  actions: [],
  middleware: [
    async (ctx, next) => {
      const trace = await langsmith.createRun({ name: "copilot-request" });
      try {
        const result = await next();
        await langsmith.updateRun(trace.id, { error: null });
        return result;
      } catch (err) {
        await langsmith.updateRun(trace.id, { error: String(err) });
        throw err;
      }
    },
  ],
});