Quickstart

Prerequisites#

Before you begin, you'll need the following:

An OpenAI API key (or Anthropic/Google — see Model Selection)
Node.js 20+
Your favorite package manager

Getting started#

Create a free account#

Sign up for a free developer account for CopilotKit Intelligence to get a license key. You'll use it later to enable persistent threads and the inspector.

Create your frontend#

CopilotKit works with any React-based frontend. We'll use Next.js for this example.

npx create-next-app@latest my-copilot-app
cd my-copilot-app

Already have an app?

Skip this step and install CopilotKit into your existing React or Next.js project. The CopilotKit CLI (npx copilotkit@latest create, aliased as init) scaffolds a brand-new project in its own directory — it does not add CopilotKit to an app you already have.

Install CopilotKit packages#

npm install @copilotkit/react-core @copilotkit/runtime

The components used below (CopilotKit, CopilotSidebar) and the stylesheet all come from @copilotkit/react-core/v2, so @copilotkit/react-ui is not needed for this setup.

Configure your environment#

Create a .env file and add your OpenAI API key:

.env

OPENAI_API_KEY=your_openai_api_key

What about other models?

This example uses OpenAI's GPT-4o. See Model Selection for Anthropic, Google, or custom model setup.

Setup Copilot Runtime#

Create an API route with the BuiltInAgent and CopilotRuntime:

Already have an agent? Do not use BuiltInAgent

BuiltInAgent is CopilotKit's own agent — it calls the model directly. Registering it as default means chat talks to it, not to any agent you already wrote. It replaces your agent rather than connecting to it.

If you already have a LangGraph, CrewAI, Mastra, ADK, Pydantic AI or other agent, take the frontend steps from this page but get the runtime wiring from your framework's quickstart, which registers your agent instead — for example LangGraph (Python). Pick yours from the docs landing.

app/api/copilotkit/[[...slug]]/route.ts

import {
  CopilotKitIntelligence,
  CopilotRuntime,
  createCopilotRuntimeHandler,
} from "@copilotkit/runtime/v2";
import { BuiltInAgent } from "@copilotkit/runtime/v2"; 

const builtInAgent = new BuiltInAgent({ 
  model: "openai:gpt-5.4-mini",
});

const runtime = new CopilotRuntime({
  agents: { default: builtInAgent }, //,
  intelligence: new CopilotKitIntelligence({
    apiKey: process.env.INTELLIGENCE_API_KEY!,
  }),
  // Threads are per-user. Without this, every visitor shares one history.
  identifyUser: (request) => ({
    id: request.headers.get("x-user-id") ?? "anonymous",
    name: request.headers.get("x-user-name") ?? "Anonymous",
  }),
});

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handler;
export const POST = handler;

The runtime reads the license key from step 1. Add it to the app that serves this route:

.env.local

INTELLIGENCE_API_KEY=your_license_key

Running without the Intelligence Platform?

Drop the intelligence and identifyUser options and the runtime falls back to SSE mode with an in-memory runner. Chat still works, but Threads and the Inspector stay locked and the key is never read. See Connect your runtime to Intelligence for the full constructor and how to confirm the key is in use.

Configure CopilotKit Provider#

Wrap your application with the CopilotKit provider:

Which provider goes with which handler?

<CopilotKit> here is the backward-compatible wrapper, and every released version pins it to the single-route transport — which is why it needs the explicit useSingleEndpoint={false} below to reach the multi-route createCopilotRuntimeHandler route above. <CopilotKitProvider> is the v2 provider from the same package and detects the transport from /info on its own. They are not aliases — see Provider and handler pairs.

app/layout.tsx

import { CopilotKit } from "@copilotkit/react-core/v2"; 
import "@copilotkit/react-core/v2/styles.css"; 
import './globals.css';

// ...

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

This relative runtimeUrl assumes Next.js serves the runtime

/api/copilotkit resolves only because Next.js serves your app and the runtime from the same origin. A client-only frontend has no shared origin, so it needs a standalone runtime server of its own and an absolute runtimeUrl such as http://localhost:8200/api/copilotkit. The per-frontend guides at /react-spa, /vue, /angular and /react-native each show that setup.

Add the chat interface#

Add the CopilotSidebar component to your page:

app/page.tsx

import { CopilotSidebar } from "@copilotkit/react-core/v2"; 

export default function Page() {
  return (
    <main>
      <h1>Your App</h1>
      <CopilotSidebar />
    </main>
  );
}

Start the development server#

npm run dev

pnpm dev

yarn dev

bun dev

🎉 Start chatting!#

Your AI agent is now ready to use! Try asking it some questions:

Can you tell me a joke?

Can you help me understand AI?

What do you think about React?

Troubleshooting

If you're having connection issues, try using 0.0.0.0 or 127.0.0.1 instead of localhost
Check that your API key is correctly set in the .env file
Make sure the runtime endpoint path matches the runtimeUrl in your CopilotKit provider

Open Inspector and confirm setup#

On localhost, click the Inspector button in the corner of the app.

Open Agents, then Agent. Your agent is listed.
Send a chat message. Open Agents, then AG-UI Events. Events are moving.
Open Threads. The list is unlocked (Intelligence is on), or locked with Enable Intelligence (Intelligence is off).

More detail: Inspector.

What's next?#

Now that you have your basic agent setup, explore these advanced features: