Integrate CopilotKit with Mastra

CopilotKit provides React components to quickly integrate customizable AI copilots into your application. Combined with Mastra, you can build sophisticated AI apps featuring bidirectional state synchronization and interactive UIs.

Visit the CopilotKit documentation to learn more about CopilotKit concepts, components, and advanced usage patterns.

This guide shows two distinct integration approaches:

Integrate CopilotKit in your Mastra server with a separate React frontend.
Integrate CopilotKit in your Next.js app

Mastra Server
Next.js

In your React frontend, install the required CopilotKit packages:

npm
yarn
pnpm

npm install @copilotkit/react-core @copilotkit/react-ui

yarn add @copilotkit/react-core @copilotkit/react-ui

pnpm add @copilotkit/react-core @copilotkit/react-ui

Create a CopilotKit component in your React frontend:

components/copilotkit-component.tsx
import { CopilotChat } from "@copilotkit/react-ui";
import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export function CopilotKitComponent({ runtimeUrl }: { runtimeUrl: string }) {
  return (
    <CopilotKit runtimeUrl={runtimeUrl} agent="weatherAgent">
      <CopilotChat
        labels={{
          title: "Your Assistant",
          initial: "Hi! 👋 How can I assist you today?",
        }}
      />
    </CopilotKit>
  );
}

If you have not yet set up your Mastra server, follow the getting started guide to set up a new Mastra project.
In your Mastra server, install additional packages for CopilotKit integration:
- npm
- yarn
- pnpm
npm install @copilotkit/runtime @ag-ui/mastra
yarn add @copilotkit/runtime @ag-ui/mastra
pnpm add @copilotkit/runtime @ag-ui/mastra

Configure your Mastra instance to include CopilotKit's runtime endpoint:

src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
import { registerCopilotKit } from "@ag-ui/mastra/copilotkit";
import { weatherAgent } from "./agents/weather-agent";

type WeatherRuntimeContext = {
  "user-id": string;
  "temperature-scale": "celsius" | "fahrenheit";
};

export const mastra = new Mastra({
  agents: { weatherAgent },
  server: {
    cors: {
      origin: "*",
      allowMethods: ["*"],
      allowHeaders: ["*"],
    },
    apiRoutes: [
      registerCopilotKit<WeatherRuntimeContext>({
        path: "/copilotkit",
        resourceId: "weatherAgent",
        setContext: (c, runtimeContext) => {
          runtimeContext.set(
            "user-id",
            c.req.header("X-User-ID") || "anonymous",
          );
          runtimeContext.set("temperature-scale", "celsius");
        },
      }),
    ],
  },
});

Use the component in your React app with your Mastra server URL:

App.tsx
import { CopilotKitComponent } from "./components/copilotkit-component";

function App() {
  return <CopilotKitComponent runtimeUrl="http://localhost:4111/copilotkit" />;
}

export default App;

Now start both the Mastra server and your frontend.

In your Next.js app, install the required packages:

npm
yarn
pnpm

npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/mastra

yarn add @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/mastra

pnpm add @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/mastra

Create a CopilotKit component:

components/copilotkit-component.tsx
'use client';
import { CopilotChat } from "@copilotkit/react-ui";
import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export function CopilotKitComponent({ runtimeUrl }: { runtimeUrl: string}) {
  return (
    <CopilotKit
      runtimeUrl={runtimeUrl}
      agent="weatherAgent"
    >
      <CopilotChat
        labels={{
          title: "Your Assistant",
          initial: "Hi! 👋 How can I assist you today?",
        }}
      />
    </CopilotKit>
  );
}

There are two approaches for the API route determined by how you're integrating Mastra in your Next.js application.

For a full-stack Next.js app with an instance of Mastra integrated into the app.
For a Next.js app with a separate Mastra server and the Mastra Client SDK.

With a Mastra instance
With the Mastra Client SDK

Create an API route that connects to local Mastra agents.

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

export const POST = async (req: NextRequest) => {
  const mastraAgents = MastraAgent.getLocalAgents({
    mastra,
    agentId: "weatherAgent",
  });

  const runtime = new CopilotRuntime({
    agents: mastraAgents,
  });

  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter: new ExperimentalEmptyAdapter(),
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

Install the Mastra Client SDK.

npm
yarn
pnpm

npm install @mastra/client-js

yarn add @mastra/client-js

pnpm add @mastra/client-js

Create an API route that connects to remote Mastra agents:

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

export const POST = async (req: NextRequest) => {
  const baseUrl = process.env.MASTRA_BASE_URL || "http://localhost:4111";
  const mastraClient = new MastraClient({ baseUrl });

  const mastraAgents = await MastraAgent.getRemoteAgents({ mastraClient });

  const runtime = new CopilotRuntime({
    agents: mastraAgents,
  });

  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter: new ExperimentalEmptyAdapter(),
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

Use the component with the local API endpoint:

App.tsx
import { CopilotKitComponent } from "./components/copilotkit-component";

function App() {
  return <CopilotKitComponent runtimeUrl="/api/copilotkit" />;
}

export default App;

Start building the future!

Next Steps

CopilotKit Documentation - Complete CopilotKit reference
React Hooks with CopilotKit - Advanced React integration patterns
Next.js Integration with Mastra - Full-stack Next.js setup guide

Next Steps​

Next Steps