# Quickstart

> Build a working AI chat with CopilotKit in minutes.

## Start with your coding agent [#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.

<PageAgentPrompt />

## Prerequisites [#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 [#getting-started]

<Steps>
    <Step>
        ### Create your frontend [#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 [#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.

        <Callout type="info" title="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`.
        </Callout>
    </Step>
    <Step>
        ### Configure your environment [#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>
        ### Add the Copilot Runtime route [#add-the-copilot-runtime-route]

        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 an agent, keep the frontend steps from this page.
          Take the runtime step from **your framework's** quickstart, 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-6-luna",
        });

        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 [#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>
          );
        }
        ```

        Render `Providers` around your app in `app/layout.tsx`:

        ```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`. See the [React SPA](/react-spa), [Vue](/vue),
          [Angular](/angular), and [React Native](/react-native) guides for that setup.
        </Callout>
    </Step>
    <Step>
        ### Add the chat interface [#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 [#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 [#start-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?

        <Accordions className="mb-4">
            <Accordion title="Troubleshooting">
                - **The browser cannot reach `localhost:3000`:** open `http://127.0.0.1:3000` instead.
                - **The agent does not reply, and the dev server log shows an OpenAI authentication error:** set `OPENAI_API_KEY` in `.env`, then restart the dev server.
                - **Requests to `/api/copilotkit` return 404:** make sure that the route file is at `app/api/copilotkit/[[...slug]]/route.ts` and that `runtimeUrl` in the provider is `/api/copilotkit`.
            </Accordion>
        </Accordions>

    </Step>

    <Step>
        ### Open Inspector and confirm setup [#open-inspector-and-confirm-setup]

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

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

        More detail: [Inspector](/inspector).
    </Step>

</Steps>

## Keep conversations between visits [#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? [#whats-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>
