CopilotKit: 31K+ Stars — Add AI Copilots to Any React or Angular App — Complete Setup Guide for 2026

# React core + UI components + runtime
npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime

# For LangChain integration (optional)
npm install @copilotkit/runtime-langchain

# For Groq adapter (optional)
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  # Optional, for cloud features

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 or 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 Assistant",
          initial: "Hi! How can I help you today?",
          placeholder: "Type a message...",
        }}
      >
        {children}
      </CopilotSidebar>
    </CopilotKit>
  );
}

npm run dev
# Open http://localhost:3000
# Click the copilot button — your AI assistant is live

// app/api/copilotkit/route.ts — OpenAI variant
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 variant
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 variant
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: "Review pull request #42", completed: false, priority: "high" },
    { id: "2", title: "Update API documentation", completed: true, priority: "medium" },
  ]);

  // Expose task state to the LLM
  useCopilotReadable({
    description: "The user's current task list with completion status and priorities",
    value: tasks,
  });

  // Action: Add a new task
  useCopilotAction({
    name: "addTask",
    description: "Add a new task to the task list",
    parameters: [
      {
        name: "title",
        type: "string",
        description: "The title of the task to add",
        required: true,
      },
      {
        name: "priority",
        type: "string",
        description: "Priority level: low, medium, or 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 `Added task: "${title}" with ${priority} priority`;
    },
  });

  // Action: Mark task as complete
  useCopilotAction({
    name: "completeTask",
    description: "Mark a task as completed by its title or ID",
    parameters: [
      {
        name: "taskId",
        type: "string",
        description: "The ID of the task to mark complete",
        required: true,
      },
    ],
    handler: ({ taskId }) => {
      setTasks((prev) =>
        prev.map((t) => (t.id === taskId ? { ...t, completed: true } : t))
      );
      return `Marked task ${taskId} as completed`;
    },
  });

  // Action: Delete a task
  useCopilotAction({
    name: "deleteTask",
    description: "Remove a task from the list",
    parameters: [
      {
        name: "taskId",
        type: "string",
        description: "The ID of the task to delete",
        required: true,
      },
    ],
    handler: ({ taskId }) => {
      setTasks((prev) => prev.filter((t) => t.id !== taskId));
      return `Deleted task ${taskId}`;
    },
  });

  return (
    <div className="task-manager">
      <h2>My Tasks ({tasks.filter((t) => !t.completed).length} pending)</h2>
      <ul>
        {tasks.map((task) => (
          <li key={task.id} className={task.completed ? "done" : ""}>
            <span>[{task.priority}] {task.title}</span>
            {task.completed && <span className="badge">Done</span>}
          </li>
        ))}
      </ul>
    </div>
  );
}

// Render a task card inside the copilot chat
useCopilotAction({
  name: "showTaskDetails",
  description: "Display a detailed task card in the chat",
  parameters: [
    { name: "taskId", type: "string", description: "Task ID to display", required: true },
  ],
  render: ({ taskId }) => {
    const task = tasks.find((t) => t.id === taskId);
    if (!task) return <div>Task not found</div>;
    return (
      <div className="task-card">
        <h4>{task.title}</h4>
        <span className={`priority-${task.priority}`}>{task.priority}</span>
        <p>Status: {task.completed ? "Completed" : "In Progress"}</p>
      </div>
    );
  },
  handler: ({ taskId }) => `Displayed details for task ${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"), // days
};

// 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 requests per minute
});

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: "Rate limited" }, { status: 429 });
    }
  }
  return NextResponse.next();
}

// Add LangSmith tracing to your runtime
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;
      }
    },
  ],
});