NestJS

In this guide, you'll build a tool-calling AI agent using Mastra and NestJS. The NestJS server adapter registers Mastra's agent and workflow routes as a NestJS module, so they run inside your existing NestJS application.

Before you begin

• You'll need an API key from a supported model provider. If you don't have a preference, use OpenAI.
• Install Node.js v22.13.0 or later
• Use the NestJS Express platform (@nestjs/platform-express)

Create a new NestJS app (optional)

If you already have a NestJS app, skip to the next step.

Run the following command to create a new NestJS app:

npm

npx @nestjs/cli new mastra-nest

pnpm

pnpm dlx @nestjs/cli new mastra-nest

Yarn

yarn dlx @nestjs/cli new mastra-nest

Bun

bun x @nestjs/cli new mastra-nest

This creates a project called mastra-nest, but you can replace it with any name you want.

Initialize Mastra

Navigate to your NestJS project directory:

cd mastra-nest

Run mastra init. When prompted, choose a provider (e.g. OpenAI) and enter your key:

npm

npx mastra@latest init

pnpm

pnpm dlx mastra@latest init

Yarn

yarn dlx mastra@latest init

Bun

bun x mastra@latest init

This creates a src/mastra folder with an example weather agent and the following files:

• index.ts: Mastra config, including memory
• tools/weather-tool.ts: A tool to fetch weather for a given location
• agents/weather-agent.ts: A weather agent with a prompt that uses the tool

You'll pass the src/mastra/index.ts file to the NestJS adapter in the next step.

Update the generated files for your module system

The files that mastra init generates need one change to compile in a NestJS project. Check the type field in your package.json. NestJS CLI v12 creates ECMAScript module (ESM) projects with "type": "module". Earlier versions of the CLI create CommonJS projects.

ESM

ESM projects use "moduleResolution": "nodenext", which requires file extensions on relative imports. Add .js to every relative import in the generated files, for example:

src/mastra/index.ts

import { weatherWorkflow } from './workflows/weather-workflow.js'
import { weatherAgent } from './agents/weather-agent.js'

src/mastra/agents/weather-agent.ts

import { weatherTool } from '../tools/weather-tool.js'

CommonJS

CommonJS doesn't support top-level await. Open src/mastra/index.ts and remove the DuckDBStore import and the domains option of MastraCompositeStore:

src/mastra/index.ts

import { DuckDBStore } from '@mastra/duckdb'

// ...

domains: {
  observability: await new DuckDBStore().getStore('observability'),
},

Observability data is then stored in the default LibSQL storage.

Add server adapter

Install the NestJS server adapter package:

npm

npm install @mastra/nestjs@latest

pnpm

pnpm add @mastra/nestjs@latest

Yarn

yarn add @mastra/nestjs@latest

Bun

bun add @mastra/nestjs@latest

Open src/app.module.ts and register MastraModule:

src/app.module.ts

import { Module } from '@nestjs/common'
import { MastraModule } from '@mastra/nestjs'
import { mastra } from './mastra/index.js'

@Module({
  imports: [
    MastraModule.register({
      mastra,
    }),
  ],
})
export class AppModule {}

备注

MastraModule registers a catch-all controller (@All('*')). If it's imported before your app modules, it can intercept unrelated routes and return 404s. To avoid conflicts, import MastraModule last or mount it under a dedicated prefix (e.g., /api/v1/mastra).

Test your agent

By default, Mastra's endpoints are added under the /api subpath and use your agent/workflow IDs. The default weather-agent created by mastra init is available at /api/agents/weather-agent.

Start your NestJS server:

npm

npm run start

pnpm

pnpm run start

Yarn

yarn run start

Bun

bun run start

In a separate terminal window, use curl to ask the weather agent:

curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"

Use Mastra in Your Own Services

The module exports two ways to access Mastra from your NestJS services: the MastraService wrapper and the MASTRA injection token.

MastraService

MastraService is an injectable wrapper with convenience methods for common operations:

src/agent.service.ts

import { Injectable } from '@nestjs/common'
import { MastraService } from '@mastra/nestjs'

@Injectable()
export class AgentService {
  constructor(private readonly mastraService: MastraService) {}

  async chat(agentId: string, message: string) {
    const agent = this.mastraService.getAgent(agentId)
    return agent.generate({
      messages: [{ role: 'user', content: message }],
    })
  }

  async runWorkflow(workflowId: string, input: Record<string, unknown>) {
    const workflow = this.mastraService.getWorkflow(workflowId)
    return workflow.start({ inputData: input })
  }
}

MastraService exposes:

• getMastra(): Returns the underlying Mastra instance
• getAgent(id): Shorthand for mastra.getAgent(id)
• getWorkflow(id): Shorthand for mastra.getWorkflow(id)
• getOptions(): Returns the module configuration
• isShuttingDown: true after graceful shutdown begins

MASTRA token

If you need the Mastra instance directly (e.g., to access storage, memory, or other core APIs), inject it with the MASTRA token:

src/memory.service.ts

import { Injectable, Inject } from '@nestjs/common'
import { MASTRA } from '@mastra/nestjs'
import type { Mastra } from '@mastra/core/mastra'

@Injectable()
export class MemoryService {
  constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}

  async getThreadMessages(threadId: string) {
    const memory = this.mastra.getMemory()
    return memory?.getMessages({ threadId })
  }
}

Both approaches use the same singleton Mastra instance registered by MastraModule.

Next steps

You now have a working Mastra agent running inside NestJS. To extend the project:

• Agents overview
• Using tools
• Agent memory

For details on the NestJS integration:

• NestJS Adapter reference