Quickstart

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

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.

Open your coding agent in your project's folder, or in an empty folder for a new app.

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

Set up CopilotKit Intelligence

Sign in to cloud-hosted Intelligence. 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.

Choose your starting point

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

Run our CLI

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 first), or No for a standard Mastra setup.
  • Framework: pick Mastra when prompted.

Install dependencies

npm install

Configure your environment

Create a .env file and add your OpenAI API key:

.env
OPENAI_API_KEY=your_openai_api_key

Get your OpenAI API key

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:

.env
ANTHROPIC_API_KEY=your_anthropic_api_key
COPILOTKIT_AGENT_MODEL=anthropic:claude-sonnet-4-6

Get your Anthropic API key

For Gemini, set COPILOTKIT_AGENT_MODEL=google:<model> and GOOGLE_API_KEY.

Start the development server

npm run dev

This will start both the UI and agent servers concurrently.

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!

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.

What's next?

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

How is this guide?