Aller au contenu principal

Intégrer Mastra à votre projet NestJS

Dans ce guide, vous allez créer avec Mastra et NestJS un Agent d’IA capable d’appeler des Tools. L’adaptateur de serveur NestJS enregistre les routes des Agents et Workflows Mastra sous forme de module NestJS, afin qu’elles s’exécutent dans votre application NestJS existante.

Avant de commencer
Lien direct vers Avant de commencer

  • Vous aurez besoin d’une clé API provenant d’un Provider de modèles pris en charge. Si vous n’avez pas de préférence, utilisez OpenAI.
  • Installez Node.js v22.13.0 ou une version ultérieure
  • Utilisez la plateforme Express de NestJS (@nestjs/platform-express)

Créer une application NestJS (facultatif)
Lien direct vers Créer une application NestJS (facultatif)

Si vous disposez déjà d’une application NestJS, passez à l’étape suivante.

Exécutez la commande suivante pour créer une application NestJS :

npx @nestjs/cli new mastra-nest

Cette commande crée un projet nommé mastra-nest, mais vous pouvez choisir le nom de votre choix.

Initialiser Mastra
Lien direct vers Initialiser Mastra

Accédez au répertoire de votre projet NestJS :

cd mastra-nest

Exécutez mastra init. Lorsque vous y êtes invité, choisissez un Provider (par exemple OpenAI) et saisissez votre clé :

npx mastra@latest init

Cette commande crée un dossier src/mastra contenant un exemple d’Agent météo et les fichiers suivants :

  • index.ts — configuration de Mastra, y compris la mémoire
  • tools/weather-tool.ts — Tool qui récupère la météo d’un lieu donné
  • agents/weather-agent.ts — Agent météo doté d’une instruction qui utilise le Tool

À l’étape suivante, vous transmettrez le fichier src/mastra/index.ts à l’adaptateur NestJS.

Ajouter l’adaptateur de serveur
Lien direct vers Ajouter l’adaptateur de serveur

Installez le package de l’adaptateur de serveur NestJS :

npm install @mastra/nestjs@latest

Ouvrez src/app.module.ts et enregistrez MastraModule :

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).

Tester votre Agent
Lien direct vers Tester votre Agent

Par défaut, les points de terminaison Mastra sont ajoutés sous le sous-chemin /api et utilisent les ID de vos Agents et Workflows. L’Agent weather-agent créé par défaut avec mastra init est disponible à l’adresse /api/agents/weather-agent.

Démarrez votre serveur NestJS :

npm run start

Dans un autre terminal, utilisez curl pour interroger l’Agent météo :

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?\"}]}"

Utiliser Mastra dans vos propres services
Lien direct vers Utiliser Mastra dans vos propres services

Le module exporte deux moyens d’accéder à Mastra depuis vos services NestJS : le wrapper MastraService et le jeton d’injection MASTRA.

MastraService
Lien direct vers MastraService

MastraService est un wrapper injectable qui propose des méthodes pratiques pour les opérations courantes :

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 expose :

  • getMastra() : renvoie l’instance Mastra sous-jacente
  • getAgent(id) : raccourci pour mastra.getAgent(id)
  • getWorkflow(id) : raccourci pour mastra.getWorkflow(id)
  • getOptions() : renvoie la configuration du module
  • isShuttingDown : vaut true après le début de l’arrêt progressif

Jeton MASTRA
Lien direct vers Jeton MASTRA

Si vous avez besoin d’accéder directement à l’instance Mastra (par exemple, pour utiliser le stockage, la mémoire ou d’autres API principales), injectez-la avec le jeton MASTRA :

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 })
  }
}

Les deux approches utilisent la même instance singleton Mastra enregistrée par MastraModule.

Étapes suivantes
Lien direct vers Étapes suivantes

Vous disposez maintenant d’un Agent Mastra fonctionnel dans NestJS. Pour enrichir le projet :

Pour en savoir plus sur l’intégration NestJS :

On this page