CopilotKit + Mastra

Bring your Mastra agentsinto any app

CopilotKit is an open-source framework that connects your app to Mastra agents. Give your agents chat, generative UI, human-in-the-loop, AG-UI Streams, Automatic Learning and more.

Quickstart
Chat

Waking up the demo

Talk to your agent in a ready-made chat interface. Open in the showcase

Mastra and CopilotKit running together, in the React frontend. Every demo below is the same integration with one capability turned on.

Build with Mastra

Mastra gives you agents, tools, workflows and working memory in TypeScript, and a server that runs them. What it does not give you is the surface. Your users need a place to talk to the agent, a view of what it does as it works, and a way to step in. Each capability below builds on something Mastra already does.

Generative UI

Your agent keeps working memory across the session. CopilotKit renders that state as your own React components, so users watch the draft take shape instead of waiting for a final answer.

Human-in-the-loop

A Mastra tool can call suspend() to wait for a person. CopilotKit renders your UI for that decision with useInterrupt and resumes the run with the answer.

Shared state

Working memory lives on the server, scoped by resourceId. The useAgent hook mirrors it into your app and back, so user changes and agent changes go to the same working memory.

Chat surfaces, headless UI, frontend tools and background tasks work with Mastra too. And more

Start building

Scaffold a new app with the CLI, or follow the quickstart to connect the Mastra agent you already run.

npx copilotkit@latest init
Read the quickstart

Connect your agent

Your Mastra service stays where it runs today. CopilotKit reaches it over HTTP through AG-UI and leaves it exactly where it is, so nothing inside Mastra changes.

app/api/copilotkit/[[...slug]]/route.ts
import { CopilotRuntime, createCopilotRuntimeHandler, InMemoryAgentRunner } 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({
  agents: () =>
    MastraAgent.getRemoteAgents({
      mastraClient,
      // Local demo only. Use your authenticated user ID in a multi-user app.
      resourceId: "local-demo-user",
    }),
  runner: new InMemoryAgentRunner(),
});

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

export const GET = handler;
export const POST = handler;
export const PATCH = handler;
export const DELETE = handler;
Read the setup guide

How is this guide?