Quickstart

            First, we'll use our CLI to create a new project for us.

            ```bash
            npx copilotkit@latest create -f mastra
            ```
        </Step>
        <Step>
            ### Install dependencies

            ```npm
            npm install
            ```
        </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?">
              The starter template is configured to use OpenAI's GPT-4o by default, but you can modify it to use any language model supported by Mastra.
            </Callout>
        </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>

            This will start both the UI and agent servers concurrently.
        </Step>
    </TailoredContentOption>
    <TailoredContentOption
        id="bring-your-own"
        title="Use an existing agent"
        description="I already have a Mastra Agent and want to add CopilotKit."
    >
        <Step>
            ### Initialize your Mastra project

            If you don't already have a Mastra project set up, create one:

            ```bash
            npx create-mastra@latest my-agent
            cd my-agent
            ```
        </Step>
        <Step>
            ### Create your Mastra agent

            Create a new agent file in your Mastra project:

            ```ts title="src/mastra/agents/index.ts"

            export const myAgent = new Agent({
              name: "My Agent",
              instructions: "You are a helpful assistant!",
              model: openai("gpt-5.4"),
            });
            ```

            Then export it from your Mastra instance:

            ```ts title="src/mastra/index.ts"

            export const mastra = new Mastra({
              agents: { myAgent },
            });
            ```

            <Callout type="info" title="What about other models?">
              This example uses OpenAI's GPT-4o, but you can modify it to use any language model supported by Mastra.
            </Callout>
        </Step>
        <Step>
            ### Configure your environment

            Set your OpenAI API key as an environment variable:

            ```bash
            export OPENAI_API_KEY=your_openai_api_key
            ```
        </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
            ```
        </Step>
        <Step>
            ### Install CopilotKit packages

            ```npm
            npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/mastra @ag-ui/core @ag-ui/client @mastra/client-js @ai-sdk/openai
            ```
        </Step>
        <Step>
            ### Setup Copilot Runtime

            Create an API route to connect CopilotKit to your Mastra agent:

            ```ts title="app/api/copilotkit/route.ts"
            import {
              CopilotRuntime,
              ExperimentalEmptyAdapter,
              copilotRuntimeNextJSAppRouterEndpoint,
            } from "@copilotkit/runtime";
            import { MastraAgent } from "@ag-ui/mastra";
            import { mastra } from "@/mastra";
            import { NextRequest } from "next/server";

            const serviceAdapter = new ExperimentalEmptyAdapter();

            const runtime = new CopilotRuntime({
              agents: MastraAgent.getLocalAgents({ mastra }),
            });

            export const POST = async (req: NextRequest) => {
              const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
                runtime,
                serviceAdapter,
                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" agent="myAgent">
                      {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 your UI

            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>
    </TailoredContentOption>
</TailoredContent>
<Step>
    ### 🎉 Start chatting!

    Your AI agent is now ready to use! Try asking it some questions:

    ```
    What tools do you have access to?
    ```

    ```
    What do you think about React?
    ```

    ```
    Show me some cool things you can do!
    ```

    <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`
            - Make sure your Mastra agent is running on port 4111
            - Check that your OpenAI API key is correctly set in the `.env` file
        </Accordion>
    </Accordions>
</Step>