Quickstart

WrenchIcon, PlugIcon, CpuIcon, MonitorIcon, } from "lucide-react";

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 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:

OPENAI_API_KEY=your_openai_api_key
Info

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:

  CopilotRuntime,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";

const builtInAgent = new BuiltInAgent({ // [!code highlight:3]
  model: "openai:gpt-5.2",
});

const runtime = new CopilotRuntime({
  agents: { default: builtInAgent }, // [!code highlight]
});

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:


// ...

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

Add the chat interface

Add the CopilotSidebar component to your page:


export default function Page() {
  return (
    <main>
      <h1>Your App</h1>
      {/* [!code highlight:1] */}
      <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.
2087950ee