Quickstart

    <SignupLink surface="docs_built_in_agent_quickstart_step1">Sign up for a free developer account</SignupLink> on our Enterprise Intelligence Platform to get a license key. You'll use it later to enable persistent threads and the inspector.
</Step>

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

    <Callout type="info" title="Already have an app?">
      Skip this step and install CopilotKit into your existing React or Next.js project. The CopilotKit CLI (`npx copilotkit@latest create`, aliased as `init`) scaffolds a brand-new project in its own directory — it does not add CopilotKit to an app you already have.
    </Callout>
</Step>
<Step>
    ### Install CopilotKit packages

    ```npm
    npm install @copilotkit/react-core @copilotkit/runtime
    ```

    The components used below (`CopilotKit`, `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 OpenAI's GPT-4o. 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,
      InMemoryAgentRunner,
    } 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],
      runner: new InMemoryAgentRunner(),
    });

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

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

    Wrap your application with the CopilotKit provider:

    <Callout type="info" title="Which provider goes with which handler?">
      `<CopilotKit>` here is the backward-compatible wrapper, and every released
      version pins it to the single-route transport — which is why it needs the
      explicit `useSingleEndpoint={false}` below to reach the multi-route
      `createCopilotRuntimeHandler` route above. `<CopilotKitProvider>` is the v2
      provider from the same package and detects the transport from `/info` on
      its own. They are not aliases — see
      [Provider and handler pairs](/backend/runtime-endpoints#provider-and-handler-pairs).
    </Callout>

    ```tsx title="app/layout.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>
            <CopilotKit runtimeUrl="/api/copilotkit" useSingleEndpoint={false}>
              {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?
    ```

    <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>
    <OpenInspectorStep components={props.components} />
</Step>