Adaptateur NestJS

Le package @mastra/nestjs fournit un module NestJS permettant d'exécuter Mastra avec la plateforme NestJS basée sur Express.

La v1 est volontairement limitée à Express. Si Nest est démarré avec un autre adaptateur HTTP, MastraModule lève une erreur au démarrage au lieu de tenter une intégration partielle. Pour en savoir plus sur les concepts généraux des adaptateurs, consultez les adaptateurs de serveur.

Installation

Installez l'adaptateur NestJS et assurez-vous que votre application utilise la plateforme Express :

npm

npm install @mastra/nestjs@latest

pnpm

pnpm add @mastra/nestjs@latest

Yarn

yarn add @mastra/nestjs@latest

Bun

bun add @mastra/nestjs@latest

Exemple d'utilisation

src/app.module.ts

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

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

remarque

MastraModule enregistre un contrôleur générique (@All('*')). S'il est importé avant les modules de votre application, il peut intercepter des routes sans rapport et renvoyer des erreurs 404. Pour éviter les conflits, importez MastraModule en dernier ou montez-le sous un préfixe dédié (par exemple, /api/v1/mastra).

src/main.ts

import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)
  await app.listen(3000)
}

bootstrap()

Par défaut, les routes Mastra sont montées sous /api. Utilisez prefix pour modifier ce chemin.

Options du module

mastra:

Mastra

Instance Mastra

prefix?:

string

= `/api`

Préfixe du chemin des routes (par exemple, /api/v2)

rateLimitOptions?:

{ enabled?: boolean; defaultLimit?: number; windowMs?: number; generateLimit?: number }

Configuration de la limitation du débit (activée par défaut)

shutdownOptions?:

{ timeoutMs?: number; notifyClients?: boolean }

Configuration de l'arrêt progressif

bodyLimitOptions?:

{ maxSize?: number; maxFileSize?: number; tempDir?: string; allowedMimeTypes?: string[] }

Limites de taille du corps des requêtes

streamOptions?:

{ redact?: boolean; heartbeatMs?: number }

Configuration du streaming

tracingOptions?:

{ enabled?: boolean; serviceName?: string }

Configuration du Tracing OpenTelemetry

contextOptions?:

{ strict?: boolean; logWarnings?: boolean }

Configuration de l'analyse du contexte de requête

customRouteAuthConfig?:

Map<string, boolean>

Remplacements de l'authentification propres à chaque route. Les clés suivent le format METHOD:PATH.

tools?:

Record<string, Tool>

Tools enregistrés pour le serveur

taskStore?:

InMemoryTaskStore

Stockage des tâches pour les opérations A2A (Agent-to-Agent)

mcpOptions?:

{ serverless?: boolean; sessionIdGenerator?: () => string }

Options de transport MCP

auth?:

{ enabled?: boolean; allowQueryApiKey?: boolean }

= `{ enabled: false }`

Active l'authentification Mastra par token. Désactivée par défaut, car la plupart des applications NestJS utilisent leurs propres gardes d'authentification. L'authentification apiKey par paramètre de requête doit être activée explicitement pour assurer la rétrocompatibilité.

Enregistrement asynchrone

src/app.module.ts

import { Module } from '@nestjs/common'
import { ConfigModule, ConfigService } from '@nestjs/config'
import { MastraModule } from '@mastra/nestjs'
import { Mastra } from '@mastra/core/mastra'

@Module({
  imports: [
    ConfigModule.forRoot(),
    MastraModule.registerAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        mastra: new Mastra({
          agents: {
            greeter: {
              name: 'greeter',
              description: 'Greets the user',
              model: config.get('MASTRA_MODEL', 'openai/gpt-5-mini'),
            },
          },
        }),
        prefix: config.get('MASTRA_PREFIX', '/api'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Accès à Mastra

Utilisez le token MASTRA ou MastraService dans vos services :

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

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

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

Routes MCP

Les points de terminaison MCP sont exposés sous le préfixe de l'API :

• POST /api/mcp/:serverId/mcp
• GET /api/mcp/:serverId/sse
• POST /api/mcp/:serverId/messages

Routes d'état

Les points de terminaison opérationnels ne comportent volontairement aucun préfixe afin d'assurer la compatibilité avec l'infrastructure :

• GET /health
• GET /ready
• GET /info

Voir aussi

• Adaptateurs de serveur
• Référence de MastraServer