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 your frontend#

CopilotKit's React components work with Next.js, React Router, Remix, TanStack Start, Vite, and other React apps. This walkthrough uses Next.js because it can host the frontend and runtime in one project.

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

Already have an app?

Keep your current setup and install CopilotKit there. Use the React SPA guide for a client-only Vite app, or deploy the runtime to your server framework with the React Router or TanStack Start examples. The CopilotKit CLI (npx copilotkit@latest create, aliased as init) creates a separate project; it does not modify an existing app.

Install CopilotKit packages#

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

The components used below (CopilotKitProvider, 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 an OpenAI model. 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 {
  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 }, //,
});

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

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

Configure CopilotKit Provider#

Wrap your application with the CopilotKit provider:

app/layout.tsx

import { CopilotKitProvider } 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>
        <CopilotKitProvider runtimeUrl="/api/copilotkit">
          {children}
        </CopilotKitProvider>
      </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.

Keep conversations between visits#

Your sample chat is running. When you need production conversation history, CopilotKit Intelligence can keep each user's messages, generated interfaces, and tool activity available across sessions and devices.

Your sample chat is runningAdd persistent threads, analytics, inspection, and learning when your app is ready for them.Explore Intelligence

What's next?#

Now that your basic chat is running, explore these advanced features:

🔧