Quickstart

Build a working AI chat with CopilotKit in minutes.

Start with your coding agent

Use this prompt to build a working chat with CopilotKit's built-in agent. Your coding agent will follow this guide in your project, or you can work through the manual steps below.

Open your coding agent in your project's folder, or in an empty folder for a new app.

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. The CopilotKit CLI (npx copilotkit@latest create, aliased as init) creates a separate project; it does not modify an existing app.

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.

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.

TypeScript: use bundler module resolution

CopilotKit's /v2 subpaths are published through the package exports map, which TypeScript's "moduleResolution": "node" (node10) setting ignores. Under that setting, type checking fails with Cannot find module '@copilotkit/react-core/v2' even though the app runs. Set "moduleResolution": "bundler" in tsconfig.json; if module is commonjs or unset, also set "module": "esnext". create-next-app already uses bundler.

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.

Add the Copilot Runtime route

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 an agent, keep the frontend steps from this page. Take the runtime step from your framework's quickstart, 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-6-luna",
});

const runtime = new CopilotRuntime({
  agents: { default: builtInAgent },
});

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

export const GET = handler;
export const POST = handler;
export const PATCH = handler;
export const DELETE = handler;

Configure CopilotKit Provider

Wrap your application with the CopilotKit provider:

app/providers.tsx
"use client";

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

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      {children}
    </CopilotKitProvider>
  );
}

Render Providers around your app in app/layout.tsx:

app/layout.tsx
import { Providers } from "./providers";
import "@copilotkit/react-core/v2/styles.css";
import './globals.css';

// ...

export default function RootLayout({ children }: {children: React.ReactNode}) {
  return (
    <html lang="en">
      <body>
        <Providers>
          {children}
        </Providers>
      </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. See the React SPA, Vue, Angular, and React Native guides for that setup.

Add the chat interface

Add the CopilotSidebar component to your page:

app/page.tsx
"use client";

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

Start chatting

Open http://localhost:3000 and open the sidebar. Send one of these messages, and the agent replies in the sidebar:

  • Can you tell me a joke?
  • Can you help me understand AI?
  • What do you think about React?

Open Inspector and confirm setup

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

  1. Open Inspect, then Agent. Your agent is listed.
  2. Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
  3. Open Rich Threads. The list is unlocked (Intelligence is on), or locked with Copy setup prompt (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:

How is this guide?