# 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.

Ask your coding agent to follow the setup steps on this page for your selected framework and frontend.

## Prerequisites

Before you begin, you'll need the following:

- An OpenAI API key (or Anthropic/Google — see [Model Selection](/model-selection))
- Node.js 20+
- Your favorite package manager

## Getting started

<Steps>
    <Step>
        ### 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.

        ```bash
        npx create-next-app@latest my-copilot-app
        cd my-copilot-app
        ```

        <Callout type="info" title="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](/react-spa) for a client-only Vite app, or [deploy the runtime to your server framework](/runtime-server-adapter) with the React Router or TanStack Start examples.
          
          
        </Callout>
    </Step>
    <Step>
        ### Install CopilotKit packages

        ```npm
        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.
    </Step>
    <Step>
        ### Configure your environment

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

        ```plaintext title=".env"
        OPENAI_API_KEY=your_openai_api_key
        ```

        <Callout type="info" title="What about other models?">
          This example uses an OpenAI model. See [Model Selection](/model-selection) for Anthropic, Google, or custom model setup.
        </Callout>
    </Step>
    <Step>
        ### Setup Copilot Runtime

        Create an API route with the `BuiltInAgent` and `CopilotRuntime`:

        <Callout type="warn" title="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 a LangGraph, CrewAI, Mastra, ADK, Pydantic AI or
          other agent, take the frontend steps from this page but get the runtime
          wiring from **your framework's** quickstart, which registers *your*
          agent instead — for example
          [LangGraph (Python)](/langgraph-python/quickstart). Pick yours from
          [the docs landing](/).
        </Callout>

        ```ts title="app/api/copilotkit/[[...slug]]/route.ts" doctest="component"
        import {
          CopilotRuntime,
          createCopilotRuntimeHandler,
        } from "@copilotkit/runtime/v2";
        import { BuiltInAgent } from "@copilotkit/runtime/v2"; // [!code highlight]

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

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

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

        export const GET = handler;
        export const POST = handler;
        export const PATCH = handler;
        export const DELETE = handler;
        ```
    </Step>
    <Step>
        ### Configure CopilotKit Provider

        Wrap your application with the CopilotKit provider:

        ```tsx title="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>
          );
        }
        ```

        `app/layout.tsx` is a server component and cannot import the provider
        directly, so it renders your client file instead:

        ```tsx title="app/layout.tsx"
        import { Providers } from "./providers"; // [!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] */}
                <Providers>
                  {children}
                </Providers>
              </body>
            </html>
          );
        }
        ```

        <Callout type="info" title="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`. The per-frontend guides at `/react-spa`, `/vue`,
          `/angular` and `/react-native` each show that setup.
        </Callout>
    </Step>
    <Step>
        ### Add the chat interface

        Add the CopilotSidebar component to your page:

        ```tsx title="app/page.tsx"
        "use client"; // [!code highlight]

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

        export default function Page() {
          return (
            <main>
              <h1>Your App</h1>
              {/* [!code highlight:1] */}
              <CopilotSidebar />
            </main>
          );
        }
        ```
    </Step>
    <Step>
        ### Start the development server

        <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
            <Tab value="npm">
                ```bash
                npm run dev
                ```
            </Tab>
            <Tab value="pnpm">
                ```bash
                pnpm dev
                ```
            </Tab>
            <Tab value="yarn">
                ```bash
                yarn dev
                ```
            </Tab>
            <Tab value="bun">
                ```bash
                bun dev
                ```
            </Tab>
        </Tabs>
    </Step>
    <Step>
        ### 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?
        ```

        <video
          src="https://cdn.copilotkit.ai/docs/copilotkit/images/coagents/chat-example.mp4"
          className="rounded-lg shadow-xl"
          loop
          playsInline
          controls
          autoPlay
          muted
        />

        <Accordions className="mb-4">
            <Accordion title="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
            </Accordion>
        </Accordions>

    </Step>

    <Step>
        ### Open Inspector and confirm setup

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

1. Open **Agents**, then **Agent**. Your agent is listed.
2. Send a chat message. Open **Agents**, then **AG-UI Events**. Events are moving.
3. Open **Rich Threads**. The list is unlocked (Intelligence is on), or locked with Enable Intelligence (Intelligence is off).

More detail: [Inspector](/inspector).

    </Step>

</Steps>

## 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.

<QuickstartIntelligenceCta />

## What's next?

Now that your basic chat is running, explore these advanced features:

<Cards>
  <Card
    title="Server Tools"
    description="Give your agent backend capabilities with custom tools."
    href="/server-tools"
    icon={<WrenchIcon />}
  />
  <Card
    title="MCP Servers"
    description="Connect MCP servers for extended tool support."
    href="/mcp-servers"
    icon={<PlugIcon />}
  />
  <Card
    title="Model Selection"
    description="Switch to Anthropic, Google, or a custom model."
    href="/model-selection"
    icon={<CpuIcon />}
  />
  <Card
    title="Frontend Tools"
    description="Let the agent interact with your UI."
    href="/frontend-tools"
    icon={<MonitorIcon />}
  />
</Cards>