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 on our Enterprise Intelligence Platform to get a license key. You'll use it later to enable persistent threads, observability, 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

Install CopilotKit packages#

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

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:

app/api/copilotkit/route.ts

import {
  CopilotRuntime,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/runtime/v2"; 
import { NextRequest } from "next/server";

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

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

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

Configure CopilotKit Provider#

Wrap your application with the CopilotKit provider:

app/layout.tsx

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

// ...

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

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

What's next?#

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

Server Tools

Give your agent backend capabilities with custom tools.

MCP Servers

Connect MCP servers for extended tool support.

Model Selection

Switch to Anthropic, Google, or a custom model.

Frontend Tools

Let the agent interact with your UI.