How to build a Mastra agent with Novu Connect

Build a Mastra agent with Novu Connect. You call Mastra from a Novu onMessage handler and return the text. Novu delivers replies on Slack, Microsoft Teams, WhatsApp, Telegram, or email. This walkthrough uses Slack for the first connection. The same handler works on other channels once you link them.

Novu does not ship a dedicated @novu/framework/mastra adapter yet. Use @novu/framework, call Mastra in onMessage, and return the text (or call ctx.reply()).

What do I need before I start?

A Novu account
Node.js 22+
A Slack workspace where you can install apps (or another supported channel)
An OPENAI_API_KEY (or another model key Mastra supports)

How do I get a working agent?

Run the CLI

In an empty folder:

npx novu connect

When prompted:

Sign in to Novu (or paste your secret key).
Choose Custom code as the runtime (Mastra uses the base Framework path).
Name your agent. Note the identifier the CLI prints. Your code must use the same value.
You can skip LLM auth in the CLI. You will wire Mastra in the next steps after the scaffold.
Choose Slack (or another channel).

Connect Slack

When the CLI asks for a Slack App Configuration Token:

Open Slack API apps.
Under App Configuration Tokens, click Generate Token.
Select your workspace, generate the token, and copy it (it starts with xoxe.xoxp-).
Paste it into the CLI and finish the install / Allow flow in Slack.

The token is used once to create the Slack app. Novu does not store it.For screenshots of this flow, see Create a Slack app in the custom code quickstart.

Accept the scaffold, then wire Mastra

Confirm creating a starter project when the CLI asks. It creates a Next.js app with a bridge route and a demo handler.Then:

Install Mastra:

npm install @mastra/core

Add your model key to .env.local (keep the NOVU_SECRET_KEY the CLI wrote):

OPENAI_API_KEY=sk-...

Replace the demo handler with Mastra. Create app/novu/agents/mastra-support.ts:

import { Agent } from '@mastra/core/agent';

export const mastraSupport = new Agent({
  id: 'mastra-support',
  name: 'Support Agent',
  instructions: 'You are a helpful support agent. Keep answers short.',
  model: 'openai/gpt-4o',
});

Update your Novu agent file (use your real identifier) so it calls Mastra:

import { agent } from '@novu/framework';
import { mastraSupport } from './mastra-support';

function toMastraMessages(history: { role: string; type: string; content: string }[]) {
  return history
    .filter((entry) => entry.type === 'message' && entry.content.trim())
    .map((entry) => ({
      role: entry.role === 'agent' || entry.role === 'assistant' ? 'assistant' : 'user',
      content: entry.content,
    }));
}

export const supportBot = agent('support-bot', {
  onMessage: async (_message, ctx) => {
    const result = await mastraSupport.generate(toMastraMessages(ctx.history));

    return result.text;
  },
});

Export that agent from app/novu/agents/index.ts.

If you already have an app and skipped the scaffold, jump to Wire an existing app.

Run the agent locally

npm run dev:novu

This starts your app and tunnels it to Novu so channel messages reach your bridge. Keep the process running.If the script is missing:

npx novu dev --port 4000

Send a message

Message your bot in Slack (DM or @mention). You should get a reply from Mastra in the same thread.Success looks like: the tunnel is connected, and the reply is from your Mastra agent (not the demo scaffold text).If nothing comes back:

Confirm npm run dev:novu is still running.
Confirm the agent identifier in code matches the dashboard.
Confirm OPENAI_API_KEY is set.
Confirm Slack install completed and you are messaging the correct bot.

Wire an existing app

Use this only if you skipped the CLI scaffold. Otherwise you can skip this section.

Install packages and env

npm install @novu/framework @mastra/core

Add to .env.local:

OPENAI_API_KEY=sk-...
NOVU_SECRET_KEY=your-novu-secret-key

Copy NOVU_SECRET_KEY from API Keys in the dashboard if needed.

Create the Mastra agent and Novu handler

Same code as Accept the scaffold, then wire Mastra: a Mastra Agent, a small toMastraMessages helper, and a Novu agent() that returns result.text.

Add the bridge route

Create app/api/novu/route.ts:

import { serve } from '@novu/framework/next';
import { supportBot } from '../../novu/agents';

export const { GET, POST, OPTIONS } = serve({
  agents: [supportBot],
});

Then run npx novu dev (or npm run dev:novu) and message the bot. For Express, Hono, and other servers, see Connecting your app.

Add Mastra tools (optional)

import { Agent } from '@mastra/core/agent';
import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

const lookupOrder = createTool({
  id: 'lookup-order',
  description: 'Look up an order by ID',
  inputSchema: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => ({ orderId, status: 'shipped' }),
});

export const mastraSupport = new Agent({
  id: 'mastra-support',
  name: 'Support Agent',
  instructions: 'You are a helpful support agent. Use lookup-order when asked about an order.',
  model: 'openai/gpt-4o',
  tools: { lookupOrder },
});

For human-in-the-loop approval before a sensitive tool runs, use Novu’s tool approval APIs (ctx.toolApproval.request()).

Frequently asked questions

Which channels can I use with a Mastra agent?

Slack, Microsoft Teams, WhatsApp, Telegram, and email. One handler works for all of them. See Agents and providers.

Does Novu have a Mastra adapter?

Not yet. Use @novu/framework and return text from onMessage. AI SDK and LangChain already have dedicated adapters if you prefer those stacks.

Why map ctx.history myself?

Adapters like @novu/framework/ai-sdk convert history for you. On the base Framework path, you map history into whatever format Mastra expects, then call generate().

Can I stream tokens into the channel?

Yes, with care. Post an initial reply with ctx.reply(''), then update it as chunks arrive using ReplyHandle.edit(). The provider must support message edits.

Which CLI runtime should I pick?

Choose Custom code. That wires the base @novu/framework path Mastra uses.

Set this up with an AI assistant

Build a Mastra agent with Novu Connect

Open in Cursor

Next steps

Other frameworks

Patterns for any LLM stack without a Novu adapter.

Agents and providers

Slack, Teams, WhatsApp, Telegram, and email capabilities.

Going to production

Deploy the bridge and switch off local tunneling.

AI SDK quickstart

Same flow with a first-class Novu adapter.

Getting Started

Custom Code Agent

Managed Agent

Observability

How to build a Mastra agent with Novu Connect

What do I need before I start?

How do I get a working agent?

Run the CLI

Connect Slack

Accept the scaffold, then wire Mastra

Run the agent locally

Send a message

Wire an existing app

Frequently asked questions

Set this up with an AI assistant

Next steps

Other frameworks

Agents and providers

Going to production

AI SDK quickstart

​What do I need before I start?

​How do I get a working agent?

​Run the CLI

​Connect Slack

​Accept the scaffold, then wire Mastra

​Run the agent locally

​Send a message

​Wire an existing app

​Frequently asked questions

​Set this up with an AI assistant

​Next steps

Other frameworks

Agents and providers

Going to production

AI SDK quickstart

What do I need before I start?

How do I get a working agent?

Run the CLI

Connect Slack

Accept the scaffold, then wire Mastra

Run the agent locally

Send a message

Wire an existing app

Frequently asked questions

Set this up with an AI assistant

Next steps