> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://mastra.zisheng.pro/fr/reference/server/nestjs-adapter) 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

- Vous aurez besoin d’une clé API provenant d’un [Provider de modèles](https://mastra.zisheng.pro/fr/models) pris en charge. Si vous n’avez pas de préférence, utilisez [OpenAI](https://mastra.zisheng.pro/fr/models/providers/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)

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

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

**npm**:

```bash
npx @nestjs/cli new mastra-nest
```

**pnpm**:

```bash
pnpm dlx @nestjs/cli new mastra-nest
```

**Yarn**:

```bash
yarn dlx @nestjs/cli new mastra-nest
```

**Bun**:

```bash
bun x @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

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

```bash
cd mastra-nest
```

Exécutez [`mastra init`](https://mastra.zisheng.pro/fr/reference/cli/mastra). Lorsque vous y êtes invité, choisissez un Provider (par exemple OpenAI) et saisissez votre clé :

**npm**:

```bash
npx mastra@latest init
```

**pnpm**:

```bash
pnpm dlx mastra@latest init
```

**Yarn**:

```bash
yarn dlx mastra@latest init
```

**Bun**:

```bash
bun x 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

Installez le package de l’adaptateur de serveur NestJS :

**npm**:

```bash
npm install @mastra/nestjs@latest
```

**pnpm**:

```bash
pnpm add @mastra/nestjs@latest
```

**Yarn**:

```bash
yarn add @mastra/nestjs@latest
```

**Bun**:

```bash
bun add @mastra/nestjs@latest
```

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

```typescript
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

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

```bash
npm run start
```

**pnpm**:

```bash
pnpm run start
```

**Yarn**:

```bash
yarn run start
```

**Bun**:

```bash
bun run start
```

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

```bash
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

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

### MastraService

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

```typescript
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

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

```typescript
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

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

- [Présentation des Agents](https://mastra.zisheng.pro/fr/docs/agents/overview)
- [Utiliser des Tools](https://mastra.zisheng.pro/fr/docs/agents/using-tools)
- [Mémoire des Agents](https://mastra.zisheng.pro/fr/docs/memory/overview)

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

- [Référence de l’adaptateur NestJS](https://mastra.zisheng.pro/fr/reference/server/nestjs-adapter)