Quickstart - Copilotkit

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

<Steps> <Step> ### Create your frontend
    CopilotKit works with any React-based frontend. We'll use Next.js for this example.

    ```bash
    npx create-next-app@latest my-copilot-app
    cd my-copilot-app
    ```
</Step>
<Step>
    ### Install CopilotKit packages

    ```npm
    npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime
    ```
</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 OpenAI's GPT-4o. See [Model Selection](/built-in-agent/model-selection) for Anthropic, Google, or custom model setup.
    </Callout>
</Step>
<Step>
    ### Setup Copilot Runtime

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

    ```ts title="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);
    };
    ```
</Step>
<Step>
    ### Configure CopilotKit Provider

    Wrap your application with the CopilotKit provider:

    ```tsx title="app/layout.tsx"
    import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
    import "@copilotkit/react-ui/v2/styles.css"; // [!code highlight]
    import './globals.css';

    // ...

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

    Add the CopilotSidebar component to your page:

    ```tsx title="app/page.tsx"
    import { CopilotSidebar } from "@copilotkit/react-core/v2"; // [!code highlight]

    export default function Page() {
      return (
        <main>
          <h1>Your App</h1>
          <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?
    ```

    <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>
</Steps>
What's next?

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