# Quickstart

> Turn your Mastra Agents into an agent-native application in 10 minutes.

## Start with your coding agent [#start-with-your-coding-agent]

Use this prompt to connect your Mastra agent to CopilotKit and verify a working conversation. 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 an Anthropic API key if you run the agent on Claude
- Node.js 20+
- Your favorite package manager

## Getting started [#getting-started]

<Steps>
    <Step>
        ### Set up CopilotKit Intelligence [#set-up-copilotkit-intelligence]

        <SignupLink surface="docs_mastra_quickstart_step1">Sign in to cloud-hosted Intelligence</SignupLink>. Cloud-hosted setup uses a server-side project API key and does not issue `COPILOTKIT_LICENSE_TOKEN`. You will connect the app after you create it below.
    </Step>

    <Step>
        ### Choose your starting point [#choose-your-starting-point]

        You can either start fresh with our starter template or integrate CopilotKit into your existing Mastra Agent.

        <TailoredContent
            className="step"
            id="agent"
        >
        <TailoredContentOption
            id="starter"
            title="Start from scratch"
            description="Get started quickly with our ready-to-go starter application."
        >
            <Step>
                ### Run our CLI [#run-our-cli]

                ```bash
                npx copilotkit@latest create
                ```

                The CLI walks you through:

                - **Project name**
                - **CopilotKit Intelligence**: persistent threads and the inspector. Choose **Yes** to scaffold a project pre-wired for the platform (the CLI walks you through sign-up, or you can [create an account](https://dashboard.operations.copilotkit.ai/?utm_source=docs&utm_medium=cta&utm_campaign=intelligence&utm_content=docs_cli_prompt) first), or **No** for a standard Mastra setup.
                - **Framework**: pick **Mastra** when prompted.
            </Step>
            <Step>
                ### Install dependencies [#install-dependencies]

                ```npm
                npm install
                ```
            </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
                ```

                <ApiKeyHint provider="openai" />

                <Callout type="info" title="Running the agent on Anthropic instead">
                  The starter template runs on an OpenAI model, which is why the step
                  above sets `OPENAI_API_KEY`. The starter reads its model from
                  `COPILOTKIT_AGENT_MODEL`. To run it on Claude, add these lines to the same `.env`:

                  ```plaintext title=".env"
                  ANTHROPIC_API_KEY=your_anthropic_api_key
                  COPILOTKIT_AGENT_MODEL=anthropic:claude-sonnet-4-6
                  ```

                  <ApiKeyHint provider="anthropic" />

                  For Gemini, set `COPILOTKIT_AGENT_MODEL=google:<model>` and `GOOGLE_API_KEY`.
                </Callout>
            </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>

                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 [#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-your-mastra-agent]

                Create a new agent file in your Mastra project:

                ```ts title="src/mastra/agents/index.ts"
                import { openai } from "@ai-sdk/openai";
                import { Agent } from "@mastra/core/agent";

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

                Then export it from your Mastra instance:

                ```ts title="src/mastra/index.ts"
                import { Mastra } from "@mastra/core";
                import { myAgent } from "./agents";

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

                <Callout type="warn" title="The record key is the agent's name, not its `id`">
                  Mastra names each agent by the key you register it under, here `myAgent`. The
                  runtime and the provider's `agent` prop use that key. The `name` and the `id` are
                  not used for routing.
                </Callout>

                <Callout type="info" title="Running this agent on Anthropic instead">
                  This example uses OpenAI's `gpt-6-luna`. For Claude, install
                  `@ai-sdk/anthropic`, then swap the import and the `model` setting:

                  ```ts title="src/mastra/agents/index.ts"
                  import { anthropic } from "@ai-sdk/anthropic";
                  // model: anthropic("claude-sonnet-4-6"),
                  ```

                  The credential variable changes with the vendor. Anthropic's provider
                  reads `ANTHROPIC_API_KEY`, so export that instead of
                  `OPENAI_API_KEY` in the next step.

                  <ApiKeyHint provider="anthropic" />
                </Callout>
            </Step>
            <Step>
                ### Configure your environment [#configure-your-environment-1]

                Set your OpenAI API key as an environment variable:

                ```bash
                export OPENAI_API_KEY=your_openai_api_key
                ```

                <ApiKeyHint provider="openai" />
            </Step>
            <Step>
                ### Start your agent [#start-your-agent]

                Leave the Mastra server running in its own terminal:

                ```bash
                npx mastra dev
                ```

                Note the port it prints. `mastra dev` takes 4111 when it is free and walks
                up to 4131 when it is not, and the frontend you build next reaches this
                agent over HTTP at that address.

                Confirm it is serving your agent before you wire the frontend to it:

                ```bash
                curl http://127.0.0.1:4111/api/agents
                ```

                <Callout type="warn" title="A bare `GET /` is not a liveness check">
                  `GET /` returns `200` even when no agent is registered. Look for your agent in `/api/agents`.
                </Callout>
            </Step>
            <Step>
                ### Create your frontend [#create-your-frontend]

                CopilotKit works with any React-based frontend. We'll use Next.js for this example.

                Create it *beside* your Mastra project, not inside it:

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

                <Callout type="warn" title="Keep `next dev` out of your Mastra project root">
                  On its first run, Next.js rewrites the `tsconfig.json` in its root. A sibling folder keeps the build config of your agent as it is.
                </Callout>
            </Step>
            <Step>
                ### Install CopilotKit packages [#install-copilotkit-packages]

                ```npm
                npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/mastra @ag-ui/core@1.0.2 @ag-ui/client@1.0.2 @mastra/client-js
                ```
            </Step>
            <Step>
                ### Setup Copilot Runtime [#setup-copilot-runtime]

                Create an API route that connects CopilotKit to the Mastra server you
                started above. `MastraAgent.getRemoteAgents` asks that server which agents
                it has and bridges each one over HTTP, so your agent keeps running as its
                own process:

                ```ts title="app/api/copilotkit/[[...slug]]/route.ts" doctest="component"
                import {
                  CopilotKitIntelligence,
                  CopilotRuntime,
                  createCopilotRuntimeHandler,
                } from "@copilotkit/runtime/v2";
                import { MastraAgent } from "@ag-ui/mastra";
                import { MastraClient } from "@mastra/client-js";

                const mastraClient = new MastraClient({
                  baseUrl: process.env.MASTRA_BASE_URL ?? "http://127.0.0.1:4111",
                });

                const runtime = new CopilotRuntime({
                  // A factory, so the agent list is fetched per request rather than at
                  // module load — the route survives an agent server that is not up yet.
                  agents: ({ request }) =>
                    MastraAgent.getRemoteAgents({
                      mastraClient,
                      // Scopes Mastra's own memory to the same user identified below.
                      resourceId: request.headers.get("x-user-id") ?? "anonymous",
                    }),
                  // [!code highlight:8]
                  intelligence: new CopilotKitIntelligence({
                    apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
                  }),
                  // Threads are per-user. Without this, every visitor shares one history.
                  identifyUser: (request) => ({
                    id: request.headers.get("x-user-id") ?? "anonymous",
                    name: request.headers.get("x-user-name") ?? "Anonymous",
                  }),
                });

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

                export const GET = handler;
                export const POST = handler;
                export const PATCH = handler;
                export const DELETE = handler;
                ```

                From this frontend app directory, connect the runtime to an Intelligence project:

                ```bash title="Terminal"
                npx copilotkit@latest project select
                ```

                The command writes the server-side project API key to `.env`. Add the address of
                the agent server to the same file; the frontend runtime reads both values here,
                not in the Mastra project:

                ```plaintext title=".env"
                CPK_INTELLIGENCE_API_KEY=cpk-...
                MASTRA_BASE_URL=http://127.0.0.1:4111
                ```

                `MASTRA_BASE_URL` defaults to `http://127.0.0.1:4111`, so you only need it
                if your agent server took a different port or you are pointing at a
                deployed Mastra service.

                <Callout type="info" title="Embedding Mastra instead">
                  If your Mastra instance lives inside this Next.js app rather than in its
                  own process, swap `getRemoteAgents` for
                  `MastraAgent.getLocalAgents({ mastra, resourceId })` and drop the client.
                  See [local vs remote agents](/mastra/backend/copilot-runtime#local-vs-remote-agents)
                  for which one to choose.
                </Callout>

                <Callout type="info" title="Running without the Intelligence Platform?">
                  Drop the `intelligence` and `identifyUser` options and the runtime falls back
                  to SSE mode with an in-memory runner. Chat and the Inspector still work.
                  Threads, including the Rich Threads view of the Inspector, stay locked, and
                  the key is never read. See
                  [Connect your runtime to Intelligence](/mastra/intelligence/quickstart) for the
                  full constructor and how to confirm the key is in use.
                </Callout>
            </Step>
            <Step>
                ### Configure CopilotKit Provider [#configure-copilotkit-provider]

                Put the provider in a client file of your own:

                ```tsx title="app/providers.tsx"
                "use client";

                import { CopilotKit } from "@copilotkit/react-core/v2";

                export function Providers({ children }: { children: React.ReactNode }) {
                  return (
                    <CopilotKit runtimeUrl="/api/copilotkit" agent="myAgent" useSingleEndpoint={false}>
                      {children}
                    </CopilotKit>
                  );
                }
                ```

                Then wrap your application with that file:

                ```tsx title="app/layout.tsx"
                import { Providers } from "./providers"; // [!code highlight]
                import "@copilotkit/react-core/v2/styles.css";
                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">
                  For a client-only frontend, see the guides at `/react-spa`, `/vue`, `/angular`, and `/react-native`.
                </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:1]

              export default function Page() {
                return (
                  <main>
                    <h1>Your App</h1>
                    {/* [!code highlight:1] */}
                    <CopilotSidebar />
                  </main>
                );
              }
              ```
            </Step>
            <Step>
                ### Start your UI [#start-your-ui]

                With the agent still running from earlier, start the frontend in a second
                terminal:

                <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>
    <Step>
        ### Start chatting [#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, and that `MASTRA_BASE_URL` points at it
                - `curl http://127.0.0.1:4111/api/agents` should list your agent by name
                - Check that your OpenAI API key is correctly set in the `.env` file
            </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](/mastra/inspector).
    </Step>

</Steps>

## What's next? [#whats-next]

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

<Cards>
  <Card
    title="Implement Human in the Loop"
    description="Allow your users and agents to collaborate together on tasks."
    href="/mastra/human-in-the-loop"
    icon={<UserIcon />}
  />
  <Card
    title="Add some generative UI"
    description="Render your agent's progress and output in the UI."
    href="/mastra/generative-ui/tool-rendering"
    icon={<PaintbrushIcon />}
  />
  <Card
    title="Setup frontend actions"
    description="Give your agent the ability to call frontend tools, directly updating your application."
    href="/mastra/frontend-tools"
    icon={<WrenchIcon />}
  />
</Cards>

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