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

# Configuration

Cette référence présente toutes les options prises en charge par Mastra. Pour initialiser et configurer Mastra, instanciez la [classe `Mastra`](https://mastra.zisheng.pro/fr/reference/core/mastra-class).

```ts
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  // Your options...
})
```

## Options de premier niveau

### agents

**Type :** `Record<string, Agent>`

Un registre d’instances d’Agent indexées par leur nom. Les Agents sont des systèmes autonomes capables de prendre des décisions et d’agir à l’aide de modèles d’IA, d’outils et de la mémoire.

Pour en savoir plus, consultez la [documentation sur les Agents](https://mastra.zisheng.pro/fr/docs/agents/overview).

```typescript
import { Mastra } from '@mastra/core'
import { Agent } from '@mastra/core/agent'

export const mastra = new Mastra({
  agents: {
    weatherAgent: new Agent({
      id: 'weather-agent',
      name: 'Weather Agent',
      instructions: 'You help with weather information',
      model: 'openai/gpt-5.6-sol',
    }),
  },
})
```

### backgroundTasks

**Type :** `BackgroundTaskManagerConfig`

Active et configure le gestionnaire de tâches en arrière-plan. Lorsqu’il est activé, les Agents peuvent déléguer les appels d’outils de longue durée (y compris les appels de sous-agents) afin qu’ils s’exécutent de manière asynchrone pendant que la boucle agentique se poursuit. Les tâches étant persistées, un backend `storage` configuré est requis.

Pour en savoir plus, consultez la [documentation sur les tâches en arrière-plan](https://mastra.zisheng.pro/fr/docs/long-running-agents/background-tasks).

```typescript
import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  backgroundTasks: {
    enabled: true,
    globalConcurrency: 10,
    perAgentConcurrency: 5,
    backpressure: 'queue',
    defaultTimeoutMs: 300_000,
  },
})
```

**enabled** (`boolean`): Indique si le gestionnaire de tâches en arrière-plan est disponible. Le gestionnaire ne s’initialise que lorsque cette valeur est true et qu’un backend de stockage est configuré. Ce commutateur contrôle uniquement la disponibilité de la fonctionnalité : il n’active l’exécution en arrière-plan pour aucun outil. Les outils doivent l’activer au niveau de l’outil ou de l’Agent (voir le guide sur les tâches en arrière-plan). (Default: `false`)

**globalConcurrency** (`number`): Nombre maximal de tâches en arrière-plan exécutées simultanément pour tous les Agents. (Default: `10`)

**perAgentConcurrency** (`number`): Nombre maximal de tâches en arrière-plan exécutées simultanément pour un seul Agent. (Default: `5`)

**backpressure** (`'queue' | 'reject' | 'fallback-sync'`): Comportement lorsqu’une limite de concurrence est atteinte. 'queue' attend qu’une place se libère, 'reject' lève une erreur lors de la mise en file d’attente et 'fallback-sync' exécute plutôt l’outil de manière synchrone dans la boucle agentique. (Default: `'queue'`)

**defaultTimeoutMs** (`number`): Délai d’expiration par défaut de chaque tâche, en millisecondes. Peut être remplacé pour chaque outil ou chaque appel. (Default: `300000`)

**defaultRetries** (`RetryConfig`): Politique de nouvelle tentative appliquée par défaut aux tâches qui échouent.

**defaultRetries.maxRetries** (`number`): Nombre maximal de nouvelles tentatives avant que la tâche soit marquée comme ayant échoué.

**defaultRetries.retryDelayMs** (`number`): Délai entre les nouvelles tentatives, en millisecondes.

**defaultRetries.backoffMultiplier** (`number`): Multiplicateur appliqué à retryDelayMs à chaque tentative suivante.

**defaultRetries.maxRetryDelayMs** (`number`): Limite supérieure du délai de nouvelle tentative, indépendamment du backoff.

**defaultRetries.retryableErrors** (`(error: Error) => boolean`): Prédicat déterminant si une erreur donnée doit entraîner une nouvelle tentative. Par défaut : réessayer pour toutes les erreurs.

**cleanup** (`CleanupConfig`): Détermine la durée de conservation des enregistrements de tâches et la fréquence d’exécution du processus de nettoyage.

**cleanup.completedTtlMs** (`number`): Durée de conservation des enregistrements des tâches terminées, en millisecondes. Par défaut : 1 heure.

**cleanup.failedTtlMs** (`number`): Durée de conservation des enregistrements des tâches ayant échoué, en millisecondes. Par défaut : 24 heures.

**cleanup.cleanupIntervalMs** (`number`): Fréquence d’exécution du processus de nettoyage, en millisecondes. Par défaut : 1 minute.

**waitTimeoutMs** (`number`): Durée pendant laquelle la boucle agentique attend qu’une tâche en arrière-plan se termine avant de poursuivre. Si une tâche n’est pas terminée dans ce délai, la boucle continue sans définir isContinued. Par défaut : undefined (ne pas attendre). Peut être remplacé pour chaque Agent ou chaque outil.

**onTaskComplete** (`(task: BackgroundTask) => void | Promise<void>`): Callback global appelé lorsqu’une tâche en arrière-plan se termine correctement. Il est déclenché en plus des callbacks propres à chaque outil et à chaque Agent.

**onTaskFailed** (`(task: BackgroundTask) => void | Promise<void>`): Callback global appelé lorsqu’une tâche en arrière-plan échoue. Il est déclenché en plus des callbacks propres à chaque outil et à chaque Agent.

### deployer

**Type :** `MastraDeployer`

Provider de déploiement permettant de publier des applications sur des plateformes cloud.

Pour en savoir plus, consultez la [documentation sur le déploiement](https://mastra.zisheng.pro/fr/docs/deployment/overview).

```typescript
import { Mastra } from '@mastra/core'
import { NetlifyDeployer } from '@mastra/deployer-netlify'

export const mastra = new Mastra({
  deployer: new NetlifyDeployer(),
})
```

### events

**Type :** `Record<string, EventHandler | EventHandler[]>`

Gestionnaires d’événements du système pub/sub interne. Associe les sujets d’événements aux fonctions de gestion appelées lorsque des événements sont publiés sur ces sujets.

> **Attention:** Cette option est utilisée en interne par le moteur de Workflow de Mastra. La plupart des utilisateurs n’auront pas besoin de la configurer.

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  events: {
    'my-topic': async event => {
      console.log('Event received:', event)
    },
  },
})
```

### gateways

**Type :** `Record<string, MastraModelGateway>`

Gateways de routage de modèles personnalisées permettant d’accéder aux providers de LLM. Les gateways gèrent l’authentification propre au provider, la construction des URL et la résolution des modèles. Utilisez cette option pour prendre en charge des providers de LLM personnalisés ou auto-hébergés.

Pour en savoir plus, consultez la [documentation sur les gateways personnalisées](https://mastra.zisheng.pro/fr/models/gateways/custom-gateways).

```typescript
import { Mastra } from '@mastra/core'
import { MyPrivateGateway } from './gateways'

export const mastra = new Mastra({
  gateways: {
    private: new MyPrivateGateway(),
  },
})
```

### idGenerator

**Type :** `(context?: IdGeneratorContext) => string`\
**Valeur par défaut :** `crypto.randomUUID()`

Fonction personnalisée de génération d’ID servant à créer des identifiants uniques. Mastra transmet un contexte facultatif afin que vous puissiez générer les ID en fonction de l’élément créé.

`IdGeneratorContext` comprend :

- `idType` : `'thread' | 'message' | 'run' | 'step' | 'generic'`
- `source?` : `'agent' | 'workflow' | 'memory'`
- `entityId?` : ID de l’entité Agent/Workflow/mémoire à l’origine de la requête
- `threadId?` : ID du thread lorsqu’il est pertinent (par exemple, lors de la création d’ID de messages)
- `resourceId?` : ID de la ressource lorsqu’il est pertinent (par exemple, pour les threads limités à un utilisateur)
- `role?` : rôle du message lors de la création d’un ID de message
- `stepType?` : type d’étape du Workflow lors de la création d’un ID d’étape

> **Attention:** Cette option est utilisée en interne par Mastra pour créer les ID des exécutions de Workflow, des conversations d’Agent et d’autres ressources. La plupart des utilisateurs n’auront pas besoin de la configurer.

```typescript
import { v4 as uuid } from '@lukeed/uuid'
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  idGenerator: context => {
    if (context?.idType === 'message' && context?.threadId) {
      return `msg-${context.threadId}-${uuid()}`
    }

    if (context?.idType === 'run' && context?.source && context?.entityId) {
      return `${context.source}-run-${context.entityId}-${uuid()}`
    }

    return uuid()
  },
})
```

### logger

**Type :** `IMastraLogger | false`\
**Valeur par défaut :** `ConsoleLogger` avec le niveau `INFO` en développement et `WARN` en production

Implémentation du logger pour la journalisation et le débogage de l’application. Définissez-la sur `false` pour désactiver complètement la journalisation.

Pour en savoir plus, consultez la [documentation sur la journalisation](https://mastra.zisheng.pro/fr/docs/observability/logging).

```typescript
import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'MyApp', level: 'debug' }),
})
```

### mcpServers

**Type :** `Record<string, MCPServerBase>`

Serveurs MCP (Model Context Protocol) qui exposent les outils, Agents, Workflows et ressources de Mastra aux clients compatibles avec MCP. Utilisez cette option pour créer vos propres serveurs MCP, accessibles depuis tout système prenant en charge le protocole.

Pour en savoir plus, consultez la [présentation de MCP](https://mastra.zisheng.pro/fr/docs/mcp/overview).

```typescript
import { Mastra } from '@mastra/core'
import { MCPServer } from '@mastra/mcp'

const mcpServer = new MCPServer({
  id: 'my-mcp-server',
  name: 'My MCP Server',
  version: '1.0.0',
})

export const mastra = new Mastra({
  mcpServers: {
    myServer: mcpServer,
  },
})
```

### memory

**Type :** `Record<string, MastraMemory>`

Un registre d’instances de mémoire auxquelles les Agents peuvent faire référence. La mémoire assure la cohérence des Agents entre les interactions en conservant les informations pertinentes des conversations précédentes. Mastra prend en charge l’historique des messages récents et la mémoire de travail pour les informations persistantes propres à l’utilisateur. Le rappel sémantique récupère les messages plus anciens en fonction de leur pertinence.

Pour en savoir plus, consultez la [documentation sur la mémoire](https://mastra.zisheng.pro/fr/docs/memory/overview).

> **Remarque:** La plupart des utilisateurs configurent la mémoire directement sur les Agents. Cette configuration de premier niveau sert à définir des instances de mémoire réutilisables et partageables entre plusieurs Agents.

```typescript
import { Mastra } from '@mastra/core'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: ':memory:',
  }),
  memory: {
    chatMemory: new Memory({
      options: {
        lastMessages: 20,
      },
    }),
  },
})
```

### observability

**Type :** `ObservabilityEntrypoint`

Mastra fournit des fonctionnalités d’observabilité pour les applications d’IA. Surveillez les opérations des LLM, tracez les décisions des Agents et déboguez les Workflows complexes avec des outils qui comprennent les schémas propres à l’IA. Le tracing capture les interactions avec les modèles, les chemins d’exécution des Agents, les appels d’outils et les étapes des Workflows.

Pour en savoir plus, consultez la [documentation sur l’observabilité](https://mastra.zisheng.pro/fr/docs/observability/overview).

```typescript
import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})
```

### processors

**Type :** `Record<string, Processor>`

Processeurs d’entrée/sortie permettant de transformer les entrées et les sorties des Agents. Les processeurs s’exécutent à des points précis du pipeline d’exécution de l’Agent, ce qui permet de modifier les entrées avant qu’elles n’atteignent le modèle de langage ou les sorties avant leur renvoi. Utilisez-les pour ajouter des garde-fous, détecter les injections de prompt, modérer le contenu ou appliquer une logique métier personnalisée.

Pour en savoir plus, consultez la [documentation sur les processeurs](https://mastra.zisheng.pro/fr/docs/agents/processors).

> **Remarque:** La plupart des utilisateurs configurent les processeurs directement sur les Agents. Cette configuration de premier niveau sert à définir des instances de processeur réutilisables et partageables entre plusieurs Agents.

```typescript
import { Mastra } from '@mastra/core'
import { ModerationProcessor } from '@mastra/core/processors'

export const mastra = new Mastra({
  processors: {
    moderation: new ModerationProcessor({
      model: 'openai/gpt-5-mini',
      categories: ['hate', 'harassment', 'violence'],
    }),
  },
})
```

### pubsub

**Type :** `PubSub`\
**Valeur par défaut :** `EventEmitterPubSub`

Système pub/sub pour la communication événementielle entre les composants. Mastra l’utilise en interne pour traiter les événements des Workflows et assurer la communication entre les composants.

> **Attention:** Cette option est utilisée en interne par Mastra. La plupart des utilisateurs n’auront pas besoin de la configurer.

```typescript
import { Mastra } from '@mastra/core'
import { CustomPubSub } from './pubsub'

export const mastra = new Mastra({
  pubsub: new CustomPubSub(),
})
```

### scorers

**Type :** `Record<string, Scorer>`

Les Scorers évaluent la qualité des réponses des Agents et des sorties des Workflows. Ils fournissent des métriques quantifiables pour mesurer la qualité des Agents au moyen de méthodes fondées sur l’évaluation par un modèle, sur des règles ou sur des statistiques. Utilisez les Scorers pour suivre les performances et comparer les approches. Ils permettent également d’identifier les points à améliorer.

Pour en savoir plus, consultez la [documentation sur les Scorers](https://mastra.zisheng.pro/fr/docs/evals/overview).

> **Remarque:** La plupart des utilisateurs configurent les Scorers directement sur les Agents. Cette configuration de premier niveau sert à définir des instances de Scorer réutilisables et partageables entre plusieurs Agents.

```typescript
import { Mastra } from '@mastra/core'
import { createToxicityScorer } from '@mastra/evals/scorers/prebuilt'

export const mastra = new Mastra({
  scorers: {
    toxicity: createToxicityScorer({ model: 'openai/gpt-5-mini' }),
  },
})
```

### storage

**Type :** `MastraCompositeStore`

Provider de stockage permettant de persister les données de l’application. Il est utilisé par la mémoire, les Workflows, les traces et les autres composants nécessitant une persistance. Mastra prend en charge plusieurs backends de base de données, notamment PostgreSQL, MongoDB et libSQL.

Pour en savoir plus, consultez la [documentation sur le stockage](https://mastra.zisheng.pro/fr/docs/storage/overview).

```typescript
import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})
```

### tools

**Type :** `Record<string, Tool>`

Les Tools sont des fonctions réutilisables que les Agents peuvent employer pour interagir avec des systèmes externes. Chaque Tool définit ses entrées, ses sorties et sa logique d’exécution.

Pour en savoir plus, consultez la [documentation sur les Tools](https://mastra.zisheng.pro/fr/docs/agents/using-tools).

> **Remarque:** La plupart des utilisateurs configurent les Tools directement sur les Agents. Cette configuration de premier niveau sert à définir des Tools réutilisables et partageables entre plusieurs Agents.

```typescript
import { Mastra } from '@mastra/core'
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Fetches weather for a city',
  inputSchema: z.object({
    city: z.string(),
  }),
  execute: async () => {
    return { temperature: 20, conditions: 'Sunny' }
  },
})

export const mastra = new Mastra({
  tools: {
    weather: weatherTool,
  },
})
```

### tts

**Type :** `Record<string, MastraVoice>`

Providers de synthèse vocale. Enregistrez des providers vocaux afin que les Agents puissent convertir leurs réponses textuelles en audio parlé.

Pour en savoir plus, consultez la [documentation sur la voix](https://mastra.zisheng.pro/fr/guides/voice/overview).

> **Remarque:** La plupart des utilisateurs configurent la voix directement sur les Agents. Cette configuration de premier niveau sert à définir des providers vocaux réutilisables et partageables entre plusieurs Agents.

```typescript
import { Mastra } from '@mastra/core'
import { OpenAIVoice } from '@mastra/voice-openai'

export const mastra = new Mastra({
  tts: {
    openai: new OpenAIVoice(),
  },
})
```

### vectors

**Type :** `Record<string, MastraVector>`

Stores vectoriels pour la recherche sémantique et les embeddings. Ils sont utilisés dans les pipelines RAG, la recherche par similarité et d’autres fonctionnalités fondées sur les embeddings. Mastra prend en charge plusieurs bases de données vectorielles, notamment Pinecone, PostgreSQL avec pgvector, OracleDB et MongoDB.

Pour en savoir plus, consultez la [documentation sur le RAG](https://mastra.zisheng.pro/fr/guides/rag/overview).

> **Remarque:** La plupart des utilisateurs créent directement les stores vectoriels lors de la construction de pipelines RAG. Cette configuration de premier niveau sert à définir des instances de store vectoriel réutilisables et partageables dans toute votre application.

```typescript
import { Mastra } from '@mastra/core'
import { PineconeVector } from '@mastra/pinecone'

export const mastra = new Mastra({
  vectors: {
    pinecone: new PineconeVector({
      id: 'pinecone-vector',
      apiKey: process.env.PINECONE_API_KEY,
    }),
  },
})
```

### workflows

**Type :** `Record<string, Workflow>`

Les Workflows définissent des pipelines d’exécution par étapes, avec des entrées et des sorties dont les types sont sûrs. Utilisez-les pour les tâches comportant plusieurs étapes dans un ordre d’exécution précis, afin de contrôler la circulation des données entre les étapes.

Pour en savoir plus, consultez la [documentation sur les Workflows](https://mastra.zisheng.pro/fr/docs/workflows/overview).

```typescript
import { Mastra } from '@mastra/core'
import { testWorkflow } from './workflows/test-workflow'

export const mastra = new Mastra({
  workflows: {
    testWorkflow,
  },
})
```

### workspace

**Type :** `Workspace`

Un Workspace Mastra fournit aux Agents un environnement persistant pour stocker des fichiers et exécuter des commandes. Les Agents héritent du Workspace global de la classe `Mastra`, sauf si leur propre Workspace est configuré.

Consultez la [documentation sur le Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview) pour connaître les détails d’implémentation.

```typescript
import { Mastra } from '@mastra/core'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
})

const mastra = new Mastra({
  workspace,
})
```

## Options du bundler

### bundler.entries

**Type :** `Record<string, string>`\
**Valeur par défaut :** `{}`

Points d’entrée de processus supplémentaires à générer avec le bundle du serveur, sous la forme d’une correspondance entre le nom de sortie et le chemin source relatif à votre répertoire Mastra. Chaque entrée produit son propre fichier `<name>.mjs` dans `.mastra/output`.

Utilisez cette option pour les processus de longue durée qui s’exécutent à côté de votre serveur Mastra plutôt qu’en son sein, comme un [worker vocal LiveKit](https://mastra.zisheng.pro/fr/guides/voice/realtime-voice). Le point d’entrée partage avec le serveur le répertoire de sortie, le fichier `package.json` et les dépendances installées. Une seule commande `mastra build` produit ainsi un artefact déployable que vous pouvez démarrer avec différentes commandes.

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    entries: { 'voice-worker': './voice-worker.ts' },
  },
})
```

Cela génère `.mastra/output/voice-worker.mjs` à côté de `.mastra/output/index.mjs`. Les dépendances importées uniquement par le point d’entrée supplémentaire sont également analysées, afin d’être installées dans la sortie.

Les noms d’entrée peuvent contenir `/` afin d’imbriquer la sortie. Ils ne peuvent pas être `index`, réservé au bundle du serveur, ni `tools`, réservé à l’agrégateur de Tools, et ne peuvent pas commencer par `tools/`, réservé aux bundles de Tools.

> **Remarque:** `mastra build` applique la valeur par défaut de [`bundler.externals`](#bundlerexternals), à savoir `true`, uniquement lorsqu’aucune option du bundler n’est définie. Dès que vous définissez `entries`, définissez également `externals` explicitement si votre point d’entrée supplémentaire dépend de packages qui ne peuvent pas être intégrés au bundle, comme des modules natifs.

### bundler.externals

**Type :** `boolean | string[]`\
**Valeur par défaut :** `true`

Lorsque vous exécutez `mastra build`, Mastra regroupe votre projet dans le répertoire `.mastra/output`. Cette option détermine les packages exclus du bundle (marqués comme « externes ») et installés séparément par un gestionnaire de packages. Elle est utile lorsque le bundler interne de Mastra ([Rollup](https://rollupjs.org/configuration-options/#external)) rencontre des difficultés pour regrouper certains packages.

Par défaut, `mastra build` définit cette option sur `true`.

Les valeurs ont les significations suivantes :

- `true` : toutes les dépendances répertoriées dans le fichier `package.json` de votre projet sont marquées comme externes
- `false` : aucune dépendance n’est marquée comme externe ; tout est regroupé dans le bundle
- `string[]` : tableau des noms de packages à marquer comme externes ; les autres sont regroupés dans le bundle

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    externals: ['some-package', 'another-package'],
  },
})
```

### bundler.sourcemap

**Type :** `boolean`\
**Valeur par défaut :** `false`

Active la génération de source maps pour la sortie regroupée.

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    sourcemap: true,
  },
})
```

### bundler.transpilePackages

**Type :** `string[]`\
**Valeur par défaut :** `[]`

Liste des packages dont le code source doit être transpilé par esbuild pendant le processus de build. Utilisez cette option pour les dépendances qui contiennent du TypeScript ou un autre code devant être compilé avant la mise en bundle.

Cette option n’est nécessaire que si vous importez directement du code source non compilé. Si vos packages sont déjà compilés en CommonJS ou en ESM, il est inutile de les répertorier ici.

Mastra détecte automatiquement les packages du Workspace dans les monorepos et les ajoute à cette liste. En général, vous devez donc uniquement préciser les packages externes qui nécessitent une transpilation.

Pendant le build, Mastra résout également les alias de `tsconfig.json` `baseUrl` et `paths`. Cela inclut les imports de style ESM, tels que `~/utils/logger.js`, qui pointent vers des fichiers sources TypeScript.

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    transpilePackages: ['@my-org/shared-utils'],
  },
})
```

## Options du serveur

### server.apiRoutes

**Type :** `ApiRoute[]`

Mastra expose automatiquement les Agents et les Workflows enregistrés par l’intermédiaire de son serveur. Pour ajouter d’autres comportements, vous pouvez définir vos propres routes HTTP.

Pour en savoir plus, consultez la documentation sur les [routes d’API personnalisées](https://mastra.zisheng.pro/fr/docs/server/custom-api-routes).

```typescript
import { Mastra } from '@mastra/core'
import { registerApiRoute } from '@mastra/core/server'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      registerApiRoute('/my-custom-route', {
        method: 'GET',
        handler: async c => {
          return c.json({ message: 'Custom route' })
        },
      }),
    ],
  },
})
```

### server.auth

**Type :** `MastraAuthConfig | MastraAuthProvider`

Configuration de l’authentification du serveur. Mastra prend en charge plusieurs providers d’authentification, notamment JWT, Clerk, Supabase, Firebase, WorkOS et Auth0.

Pour en savoir plus, consultez la [documentation sur l’authentification](https://mastra.zisheng.pro/fr/docs/server/auth).

```typescript
import { Mastra } from '@mastra/core'
import { MastraJwtAuth } from '@mastra/auth'

export const mastra = new Mastra({
  server: {
    auth: new MastraJwtAuth({
      secret: process.env.MASTRA_JWT_SECRET,
      mapUserToResourceId: user => user.id,
    }),
  },
})
```

Le callback `mapUserToResourceId` associe l’utilisateur authentifié à un ID de ressource afin de limiter la portée de la mémoire et des threads. Lorsqu’il est fourni, il est appelé après une authentification réussie et la valeur renvoyée est définie dans le contexte de la requête sous la clé `MASTRA_RESOURCE_ID_KEY`. Pour plus de détails, consultez [Autorisation (isolation des utilisateurs)](https://mastra.zisheng.pro/fr/docs/server/middleware).

### server.bodySizeLimit

**Type :** `number`\
**Valeur par défaut :** `4_718_592` (4,5 Mo)

Taille maximale du corps de la requête, en octets. Augmentez cette limite si votre application doit traiter des charges utiles plus volumineuses.

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    bodySizeLimit: 10 * 1024 * 1024, // 10mb
  },
})
```

### server.mcpOptions

**Type :** `object`\
**Valeur par défaut :** `undefined`

Options de transport MCP appliquées à toutes les routes MCP HTTP et SSE. Utilisez-les pour activer le mode sans état dans les environnements serverless (Cloudflare Workers, Vercel Edge, AWS Lambda, etc.), où les connexions persistantes et l’état de session en mémoire ne sont pas disponibles.

| Propriété            | Type           | Valeur par défaut | Description                                              |
| -------------------- | -------------- | ----------------- | -------------------------------------------------------- |
| `serverless`         | `boolean`      | `false`           | Exécute MCP en mode sans état, sans gestion des sessions |
| `sessionIdGenerator` | `() => string` | `undefined`       | Fonction personnalisée de génération d’ID de session     |

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    mcpOptions: {
      serverless: true,
    },
  },
})
```

### server.build

Configuration des fonctionnalités du serveur au moment du build. Ces options contrôlent les outils de développement tels que Swagger UI et la journalisation des requêtes, activés pendant le développement local mais désactivés par défaut en production.

| Propriété     | Type      | Valeur par défaut | Description                                                                                                                                                                                                                                                  |
| ------------- | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `swaggerUI`   | `boolean` | `false`           | Active Swagger UI à l’adresse `/swagger-ui` pour explorer l’API de manière interactive (nécessite que `openAPIDocs` soit défini sur `true`)                                                                                                                  |
| `apiReqLogs`  | `boolean` | `false`           | Active la journalisation des requêtes d’API dans la console                                                                                                                                                                                                  |
| `openAPIDocs` | `boolean` | `false`           | Active la spécification OpenAPI à l’adresse `/api/openapi.json`. Les routes Mastra intégrées utilisent `servers: [{url: "/api"}]`, tandis que les routes personnalisées reçoivent une valeur de remplacement `servers: [{url: "/"}]` propre à chaque chemin. |

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    build: {
      swaggerUI: true,
      apiReqLogs: true,
      openAPIDocs: true,
    },
  },
})
```

### server.cors

**Type :** `CorsOptions | false`

Configuration CORS (Cross-Origin Resource Sharing) du serveur. Définissez-la sur `false` pour désactiver complètement CORS. Utilisez cette option afin d’appliquer une politique unique à toutes les routes. Pour une politique personnalisée propre à une route, utilisez l’option `cors` de [`registerApiRoute()`](https://mastra.zisheng.pro/fr/reference/server/register-api-route).

| Propriété       | Type                 | Valeur par défaut                                                                      | Description                                                    |
| --------------- | -------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `origin`        | `string \| string[]` | `'*'`                                                                                  | Origines des requêtes CORS                                     |
| `allowMethods`  | `string[]`           | `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']`                                 | Méthodes HTTP                                                  |
| `allowHeaders`  | `string[]`           | `['Content-Type', 'Authorization', 'x-mastra-client-type', 'x-mastra-dev-playground']` | En-têtes de requête                                            |
| `exposeHeaders` | `string[]`           | `['Content-Length', 'X-Requested-With']`                                               | En-têtes exposés au navigateur                                 |
| `credentials`   | `boolean`            | `false`                                                                                | Identifiants (cookies, en-têtes d’autorisation)                |
| `maxAge`        | `number`             | `3600`                                                                                 | Durée de mise en cache de la requête préliminaire, en secondes |

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    cors: {
      origin: ['https://example.com'],
      allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
      allowHeaders: ['Content-Type', 'Authorization'],
      credentials: false,
    },
  },
})
```

### server.host

**Type :** `string`\
**Valeur par défaut :** `localhost` (ou la variable d’environnement `MASTRA_HOST` si elle est définie)

Adresse d’hôte à laquelle le serveur de développement Mastra se lie. Si la variable d’environnement `MASTRA_HOST` est définie, elle prévaut sur la valeur par défaut.

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    host: '0.0.0.0',
  },
})
```

### server.https

**Type :** `{ key: Buffer; cert: Buffer }`

Configuration HTTPS permettant d’exécuter le serveur de développement avec TLS. Mastra prend en charge le développement HTTPS local au moyen du flag `mastra dev --https`, qui crée et gère automatiquement les certificats. Pour gérer vous-même les certificats, fournissez vos propres fichiers de clé et de certificat :

```typescript
import { Mastra } from '@mastra/core'
import fs from 'node:fs'

export const mastra = new Mastra({
  server: {
    https: {
      key: fs.readFileSync('path/to/key.pem'),
      cert: fs.readFileSync('path/to/cert.pem'),
    },
  },
})
```

### server.middleware

**Type :** `Middleware | Middleware[]`

Fonctions middleware personnalisées qui interceptent les requêtes avant ou après les gestionnaires de routes. Un middleware peut servir à l’authentification, à la journalisation, à l’injection d’un contexte propre à la requête ou à l’ajout d’en-têtes. Chaque middleware reçoit le `Context` Hono et une fonction `next`. Renvoyez une `Response` pour interrompre le traitement de la requête, ou appelez `next()` pour le poursuivre.

Pour en savoir plus, consultez la [documentation sur les middlewares](https://mastra.zisheng.pro/fr/docs/server/middleware).

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    middleware: [
      {
        handler: async (c, next) => {
          const authHeader = c.req.header('Authorization')
          if (!authHeader) {
            return new Response('Unauthorized', { status: 401 })
          }
          await next()
        },
        path: '/api/*',
      },
    ],
  },
})
```

### server.onError

**Type :** `(err: Error, c: Context) => Response | Promise<Response>`

Gestionnaire d’erreurs personnalisé appelé lorsqu’une erreur non gérée se produit. Utilisez-le pour personnaliser les réponses d’erreur, journaliser les erreurs dans des services externes tels que Sentry ou implémenter un formatage personnalisé des erreurs.

Ce hook est pris en charge par tous les adaptateurs de serveur. Le paramètre `c` fournit un objet de contexte compatible avec Hono. Pour les adaptateurs autres que Hono (Koa, Express et Fastify), un shim fournit les méthodes courantes telles que `c.json()` et `c.req.path`.

```typescript
import { Mastra } from '@mastra/core'
import * as Sentry from '@sentry/node'

export const mastra = new Mastra({
  server: {
    onError: (err, c) => {
      Sentry.captureException(err)

      return c.json(
        {
          error: err.message,
          timestamp: new Date().toISOString(),
        },
        500,
      )
    },
  },
})
```

### server.onValidationError

**Type :** `(error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined`

Gestionnaire personnalisé appelé lorsqu’une requête échoue à la validation du schéma Zod. Utilisez-le pour personnaliser les réponses aux erreurs de validation, modifier le code de statut ou formater les erreurs conformément aux normes de votre API.

Renvoyez un objet `{ status, body }` pour remplacer la réponse `400` par défaut, ou `undefined` pour conserver le comportement par défaut. Ce hook est pris en charge par tous les adaptateurs de serveur (Hono, Express, Fastify et Koa).

Le paramètre `context` indique la partie de la requête qui a échoué à la validation :

- `'query'` : paramètres de requête
- `'body'` : corps de la requête
- `'path'` : paramètres du chemin

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    onValidationError: (error, context) => ({
      status: 422,
      body: {
        ok: false,
        errors: error.issues.map(i => ({
          path: i.path.join('.'),
          message: i.message,
        })),
        source: context,
      },
    }),
  },
})
```

Vous pouvez également définir `onValidationError` sur chaque route créée avec `createRoute()`. Un hook défini au niveau de la route prévaut sur celui défini au niveau du serveur.

### server.port

**Type :** `number`\
**Valeur par défaut :** `4111` (ou la variable d’environnement `PORT` si elle est définie)

Port auquel le serveur de développement Mastra se lie. Si la variable d’environnement `PORT` est définie, elle prévaut sur la valeur par défaut.

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    port: 8080,
  },
})
```

### server.studioBase

**Type :** `string`\
**Valeur par défaut :** `/`

Chemin de base pour héberger [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview). Utilisez cette option afin d’héberger Studio dans un sous-chemin de votre application existante plutôt qu’à la racine.

Cette option est utile lors de l’intégration à des applications existantes, de l’utilisation d’outils d’authentification tels que Cloudflare Zero Trust qui tirent parti de domaines partagés, ou de la gestion de plusieurs services sous un même domaine.

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    studioBase: '/my-mastra-studio',
  },
})
```

**Exemples d’URL :**

- Par défaut : `http://localhost:4111/` (Studio à la racine)
- Avec `studioBase` : `http://localhost:4111/my-mastra-studio/` (Studio dans un sous-chemin)

### server.timeout

**Type :** `number`\
**Valeur par défaut :** `180000` (3 minutes)

Délai d’expiration des requêtes, en millisecondes. Les requêtes qui dépassent cette durée sont interrompues.

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    timeout: 30000, // 30 seconds
  },
})
```