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.
QuickstartMastra 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 initConnect 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.
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;How is this guide?