Skip to main content
CopilotKit is a full-stack SDK for building agentic applications with generative UI, shared state, and human-in-the-loop workflows. This guide will help you create your first CopilotKit application from scratch.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18 or later installed
  • An OpenAI API key (or other LLM provider API key)
  • Basic knowledge of React and Next.js

​
Quick Start with CLI

The fastest way to get started is using the CopilotKit CLI:
1

Create a new project

For a brand new project, run:
npx copilotkit@latest create -f next
For an existing project, navigate to your project directory and run:
npx copilotkit@latest init
2

Set up environment variables

Create a .env.local file in your project root and add your API key:
.env.local
OPENAI_API_KEY=your_api_key_here
CopilotKit supports multiple LLM providers including OpenAI, Anthropic, and Google. You can configure your preferred provider in the runtime setup.
3

Start your development server

npm run dev
Open http://localhost:3000 in your browser to see your CopilotKit app running!

​
Manual Setup

If you prefer to set up CopilotKit manually, follow these steps:
1

Install dependencies

Install the core CopilotKit packages:
npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime
2

Set up the runtime endpoint

Create an API route at app/api/copilotkit/route.ts:
app/api/copilotkit/route.ts
import {
  CopilotRuntime,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/runtime";
import { NextRequest } from "next/server";

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

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    endpoint: "/api/copilotkit",
  });
  
  return handleRequest(req);
};
The BuiltInAgent is CopilotKit’s built-in agent that works out of the box. You can also integrate with LangGraph, CrewAI, or create custom agents.
3

Add the provider to your layout

Wrap your app with the CopilotKit provider in app/layout.tsx:
app/layout.tsx
import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <CopilotKit runtimeUrl="/api/copilotkit" agent="default">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}
4

Add the chat interface

Create your main page with a chat sidebar in app/page.tsx:
app/page.tsx
"use client";

import { CopilotSidebar } from "@copilotkit/react-ui";
import { useCopilotAction } from "@copilotkit/react-core";
import { useState } from "react";

export default function Home() {
  const [themeColor, setThemeColor] = useState("#6366f1");
  
  // Define a frontend action that the agent can call
  useCopilotAction({
    name: "setThemeColor",
    description: "Set the theme color of the page.",
    parameters: [
      {
        name: "themeColor",
        description: "The theme color to set (e.g., '#ff0000')",
        required: true,
      },
    ],
    handler({ themeColor }) {
      setThemeColor(themeColor);
    },
  });
  
  return (
    <main
      style={{
        backgroundColor: themeColor,
        transition: "background-color 0.3s ease",
      }}
      className="h-screen flex items-center justify-center"
    >
      <div className="text-white text-center">
        <h1 className="text-4xl font-bold mb-4">
          Welcome to CopilotKit
        </h1>
        <p className="text-lg">
          Try asking: "Change the theme to orange"
        </p>
      </div>
      
      <CopilotSidebar
        defaultOpen={true}
        clickOutsideToClose={false}
        labels={{
          title: "Your AI Assistant",
          initial: "Hi! I can help you interact with this page. Try asking me to change the theme color!",
        }}
      />
    </main>
  );
}

​
Understanding the Setup

​
Frontend Components

CopilotKit provides three main UI components:

CopilotSidebar

A slide-out sidebar chat interface that sits alongside your content

CopilotPopup

A popup chat bubble that floats over your content

CopilotChat

A full-featured chat component you can embed anywhere

​
Runtime Setup

The runtime is the server-side component that:
  • Connects to your LLM provider (OpenAI, Anthropic, Google, etc.)
  • Manages agent execution and state
  • Handles tool calls and generative UI rendering
  • Provides real-time streaming over Server-Sent Events (SSE)

​
Frontend Actions

Frontend actions let your agent interact with your UI. In the example above, the setThemeColor action allows the AI to change the page’s theme color. The agent automatically learns about available actions and when to use them.

​
Next Steps

Now that you have a basic CopilotKit app running, explore these key features:

Add Backend Tools

Define tools that let your agent fetch data, call APIs, or perform calculations

Implement Generative UI

Let your agent render custom UI components dynamically

Use Shared State

Synchronize state between your agent and UI in real-time

Add Human-in-the-Loop

Request user confirmation or input during agent execution

​
Examples

Check out complete working examples in our repository:

​
Troubleshooting

Make sure:
  • Your runtime endpoint is running and accessible
  • The runtimeUrl in CopilotKit provider matches your API route
  • CORS is properly configured if your frontend and backend are on different domains
Check that:
  • Your API key is correctly set in environment variables
  • The API key has sufficient credits/permissions
  • The model name is correct (e.g., “openai/gpt-4o-mini”)
Verify that:
  • Your action descriptions are clear and specific
  • Action names follow camelCase convention
  • Parameters are properly typed with descriptive descriptions
Need more help? Join our Discord community or check out the documentation.