Skip to Content
DocsFrameworksAgentic UIsWith CopilotKit

Using with CopilotKit in React

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.

Create a Mastra Project

npx create-mastra@latest

Select the agent example when scaffolding your project. This will give you a weather agent.

For detailed setup instructions, see the installation guide.

Basic Setup

Integrating Mastra with CopilotKit involves two main steps: setting up the backend runtime and configuring your frontend components.

npm install @copilotkit/runtime

Set up the runtime

You can leverage Mastra’s custom API routes to add CopilotKit’s runtime to your Mastra server.

The current version of the integration leverages MastraClient to format Mastra agents into the AGUI format of CopilotKit.

npm install @ag-ui/mastra

Next, let’s update the Mastra instance with a custom API route for CopilotKit.

src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
import { PinoLogger } from "@mastra/loggers";
import { LibSQLStore } from "@mastra/libsql";
import { CopilotRuntime, copilotRuntimeNodeHttpEndpoint, ExperimentalEmptyAdapter } from "@copilotkit/runtime";
import { registerCopilotKit } from "@ag-ui/mastra";
import { weatherAgent } from "./agents/weather-agent";
 
const serviceAdapter = new ExperimentalEmptyAdapter();
 
export const mastra = new Mastra({
  agents: { weatherAgent },
  storage: new LibSQLStore({
    // stores telemetry, evals, ... into memory storage,
    // if you need to persist, change to file:../mastra.db
    url: ":memory:"
  }),
  logger: new PinoLogger({
    name: "Mastra",
    level: "info"
  }),
  server: {
    // We will be calling this from a Vite App. Allow CORS
    cors: {
      origin: "*",
      allowMethods: ["*"],
      allowHeaders: ["*"]
    },
    apiRoutes: [
      registerCopilotKit({
        path: "/copilotkit",
        resourceId: "weatherAgent",
        setContext: (c, runtimeContext) => {
          // Add whatever you need to the runtimeContext
          runtimeContext.set("user-id", c.req.header("X-User-ID"));
          runtimeContext.set("temperature-scale", "celsius");
        }
      })
    ]
  }
});

With this setup you now have CopilotKit running on your Mastra server. You can start your Mastra server with mastra dev.

Set up the UI

Install CopilotKit’s React components:

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

Next, add CopilotKit’s React components to your frontend.

import { CopilotChat } from "@copilotkit/react-ui";
import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";
 
export function CopilotKitComponent() {
  return (
    <CopilotKit
      runtimeUrl="http://localhost:4111/copilotkit"
      agent="weatherAgent"
    >
      <CopilotChat
        labels={{
          title: "Your Assistant",
          initial: "Hi! 👋 How can I assist you today?",
        }}
      />
    </CopilotKit>
  );
}

Render the component and start building the future!


CopilotKit output

Using with other frameworks (NextJS)

You can still leverage AGUI without going through Mastra Server.

// import your mastra instance from dir
import { mastra } from "../path/to/mastra";
import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { NextRequest } from "next/server";
import { MastraAgent } from "@ag-ui/mastra";
 
export const POST = async (req: NextRequest) => {
  // Clone the request before reading the body
  const clonedReq = req.clone();
  const body = await clonedReq.json();
  const resourceId = body.resourceId || "TEST";
 
  const mastraAgents = MastraAgent.getLocalAgents({
    resourceId,
    mastra,
    runtimeContext,
  });
 
  const runtime = new CopilotRuntime({
    agents: mastraAgents,
  });
 
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter: new ExperimentalEmptyAdapter(),
    endpoint: "/api/copilotkit",
  });
 
  // Use the original request for handleRequest
  return handleRequest(req);
};

Using with Mastra Client SDK

import { MastraClient } from "@mastra/client-js";
import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { NextRequest } from "next/server";
import { MastraAgent } from "@ag-ui/mastra";
 
export const POST = async (req: NextRequest) => {
  // Clone the request before reading the body
  const clonedReq = req.clone();
  const body = await clonedReq.json();
  const resourceId = body.resourceId || "TEST";
 
  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",
  });
 
  // Use the original request for handleRequest
  return handleRequest(req);
};

Using Typed Runtime Context

For better type safety, you can specify the type of your runtime context:

src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
import { PinoLogger } from "@mastra/loggers";
import { LibSQLStore } from "@mastra/libsql";
import { registerCopilotKit } from "@ag-ui/mastra";
import { weatherAgent } from "./agents";
 
// Define your runtime context type
type WeatherRuntimeContext = {
  "user-id": string;
  "temperature-scale": "celsius" | "fahrenheit";
  "api-key": string;
};
 
export const mastra = new Mastra({
  agents: { weatherAgent },
  storage: new LibSQLStore({
    url: ":memory:",
  }),
  logger: new PinoLogger({
    name: "Mastra",
    level: "info",
  }),
  server: {
    cors: {
      origin: "*",
      allowMethods: ["*"],
      allowHeaders: ["*"],
    },
    apiRoutes: [
      registerCopilotKit<WeatherRuntimeContext>({
        path: "/copilotkit",
        resourceId: "weatherAgent",
        setContext: (c, runtimeContext) => {
          // TypeScript will enforce the correct types here
          runtimeContext.set("user-id", c.req.header("X-User-ID") || "anonymous");
          runtimeContext.set("temperature-scale", "celsius"); // Only "celsius" | "fahrenheit" allowed
          runtimeContext.set("api-key", process.env.WEATHER_API_KEY || "");
 
          // This would cause a TypeScript error:
          // runtimeContext.set("invalid-key", "value"); // ❌ Error: invalid key
          // runtimeContext.set("temperature-scale", "kelvin"); // ❌ Error: invalid value
        }
      }),
    ],
  },
});

Further Reading

With Vercel AI SDKWith Assistant UI