Quickstart

Get started with CopilotKit's Built-in Agent in minutes.

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/runtime

Configure your environment#

Create a .env file and add your OpenAI API key:

.env

plaintext

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"; // [!code highlight]
import { NextRequest } from "next/server";

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

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:

app/layout.tsx

tsx

import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
import "@copilotkit/react-core/v2/styles.css"; // [!code highlight]
import './globals.css';

// ...

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:

app/page.tsx

tsx

import { CopilotSidebar } from "@copilotkit/react-core/v2"; // [!code highlight]

export default function Page() {
  return (
    <main>
      <h1>Your App</h1>
      {/* [!code highlight:1] */}
      <CopilotSidebar />
    </main>
  );
}

Start the development server#

npm run 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.

Quickstart

Get started with CopilotKit's Built-in Agent in minutes.

Ship the Built-in Agent to production

Add persistent threads, observability, and the inspector with the Enterprise Intelligence Platform.

Create a free account

Ship the Built-in Agent to production

Add persistent threads, observability, and the inspector with the Enterprise Intelligence Platform.

Create a free account

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/runtime

Configure your environment#

Create a .env file and add your OpenAI API key:

.env

plaintext

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"; // [!code highlight]
import { NextRequest } from "next/server";

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

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:

app/layout.tsx

tsx

import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
import "@copilotkit/react-core/v2/styles.css"; // [!code highlight]
import './globals.css';

// ...

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:

app/page.tsx

tsx

import { CopilotSidebar } from "@copilotkit/react-core/v2"; // [!code highlight]

export default function Page() {
  return (
    <main>
      <h1>Your App</h1>
      {/* [!code highlight:1] */}
      <CopilotSidebar />
    </main>
  );
}

Start the development server#

npm run 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.