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.This runs in a coding agent on your computer.
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-appAlready 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/runtimeThe 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:
OPENAI_API_KEY=your_openai_api_keyWhat 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.
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:
"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:
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:
"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 devStart 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?
- The browser cannot reach
localhost:3000: openhttp://127.0.0.1:3000instead. - The agent does not reply, and the dev server log shows an OpenAI authentication error: set
OPENAI_API_KEYin.env, then restart the dev server. - Requests to
/api/copilotkitreturn 404: make sure that the route file is atapp/api/copilotkit/[[...slug]]/route.tsand thatruntimeUrlin the provider is/api/copilotkit.
Open Inspector and confirm setup
On localhost, click the Inspector button in the corner of the app.
- Open Inspect, then Agent. Your agent is listed.
- Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
- 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 IntelligenceWhat's next?
Now that your basic chat is running, explore these advanced features:
How is this guide?