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;
      }
    },
  ],
});