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

# Passer à Mastra v1

> **Mettre à jour vers la dernière version 0.x:** Avant de passer à la v1, vérifiez que vous utilisez la dernière version 0.x de Mastra. Suivez d'abord le [guide de mise à niveau vers la dernière version 0.x](https://mastra.ai/guides/v0/migrations/upgrade-to-latest-0x), puis revenez ici pour terminer la migration vers la v1.

Mastra v1 est sortie en janvier 2026. Nous vous recommandons de démarrer tout nouveau projet avec Mastra v1, ou de mettre à niveau votre projet existant afin de continuer à recevoir les mises à jour et l'assistance.

Ce guide présente les changements incompatibles liés au passage de Mastra 0.x à la v1.0. La migration est organisée par package et domaine fonctionnel afin de vous aider à mettre à jour méthodiquement votre base de code.

> **Besoin d'aide ?:** Vous avez besoin d'aide pour la migration ? Rejoignez notre [communauté Discord](https://discord.gg/BTYqqHKUrf) pour poser vos questions.

> **Vous venez de Mastra Cloud ?:** L'ancien produit Mastra Cloud a été remplacé par la [plateforme Mastra](https://mastra.zisheng.pro/fr/docs/mastra-platform/overview), qui répartit l'hébergement entre deux produits distincts : **Studio** (environnement visuel et observabilité) et **Server** (API de production). Les anciens jetons d'accès Mastra Cloud ne fonctionnent pas avec la plateforme Mastra. Créez-en de nouveaux avec `mastra auth tokens create`.
>
> Si vous passez aux packages v1 sans migrer également votre configuration `telemetry:` vers `observability:` et sans créer de projet Studio, les données d'observabilité ne seront plus transmises. Suivez intégralement le [guide de migration de Mastra Cloud](https://mastra.zisheng.pro/fr/guides/migrations/mastra-cloud).

## Stratégie de migration

### Mettre à jour tous les packages Mastra vers le tag `latest`

Utilisez votre gestionnaire de packages pour mettre à jour les versions de votre projet. Mettez à jour **tous** les packages Mastra simultanément afin de garantir leur compatibilité, c'est-à-dire tous les packages `@mastra/*` ainsi que `mastra`.

Voici comment mettre à jour les packages les plus couramment utilisés :

**npm**:

```bash
npm install @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

**pnpm**:

```bash
pnpm add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

**Yarn**:

```bash
yarn add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

**Bun**:

```bash
bun add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

Installez tout autre package Mastra avec le tag `@latest` pour obtenir la version v1 la plus récente disponible. Veillez à mettre à jour tous les packages Mastra, en particulier dans un monorepo, afin d'éviter les incompatibilités de versions.

### Mettre à jour la version de Node.js

Mastra v1 nécessite Node.js **22.13.0** ou une version ultérieure. Mettez à jour vos environnements de développement et de production en conséquence.

### Parcourir la liste de contrôle de migration

Suivez la [liste de contrôle de migration](#migration-checklist) ci-dessous pour mettre à jour votre base de code. Chaque élément renvoie vers un guide détaillé consacré au changement correspondant.

> **Codemods:** Nous avons préparé des [codemods](https://github.com/mastra-ai/mastra/tree/main/packages/codemod) automatisés. Si vous le souhaitez, vous pouvez exécuter tous les codemods v1 en une seule fois :
>
> ```bash
> npx @mastra/codemod@latest v1
> ```

> **Migration de base de données obligatoire:** Si vous utilisez un stockage PostgreSQL ou LibSQL, vous devrez exécuter une migration de base de données. Consultez le [guide de migration du stockage](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/storage) pour plus de détails.

## Changements incompatibles par domaine

- **[Classe Mastra](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/mastra)** — Restructuration des imports et modification de l'accès aux propriétés.
- **[Classe Agent](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/agent)** — Déplacement des méthodes vocales vers un namespace et mise à jour de l'API de streaming.
- **[Tools](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/tools)** — Modification de la signature `execute` de CreateTool afin de séparer l'entrée et le contexte.
- **[Workflows](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/workflows)** — Modification des noms de fonctions et suppression de fonctionnalités héritées.
- **[Memory](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/memory)** — La configuration exige désormais des paramètres explicites et les valeurs par défaut ont changé.
- **[Storage](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/storage)** — Standardisation de la pagination et renommage des méthodes selon le modèle `list`.
- **[Vectors](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/vectors)** — Renommage des méthodes du magasin vectoriel selon le modèle `list`.
- **[RAG](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/rag)** — Mise à jour des noms de paramètres pour plus de clarté.
- **[MCP](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/mcp)** — Réorganisation du contexte des Tools et suppression des classes clientes obsolètes.
- **[Tracing](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/tracing)** — Remplacement de la télémétrie OTEL par un package d'observabilité dédié et des exporters.
- **[Evals et Scorers](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/evals)** — Regroupement de l'API des Scorers avec de nouvelles conventions de nommage.
- **[CLI](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/cli)** — Suppression de commandes et d'options pour simplifier l'interface.
- **[Déploiement](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/deployment)** — Mise à jour de la configuration de CloudflareDeployer pour utiliser les noms de propriétés standard de `wrangler.json`.
- **[SDK clients](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/client)** — Renommage des types et utilitaires pour plus de cohérence.
- **[Packages Voice](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/voice)** — Renommage des packages de speech vers voice.

## Liste de contrôle de migration

Suivez cette liste dans l'ordre, en commençant par les changements à fort impact qui concernent la plupart des applications.

> **Codemods:** Nous avons préparé des [codemods](https://github.com/mastra-ai/mastra/tree/main/packages/codemod) automatisés. Tout au long du guide de migration, vous trouverez des instructions pour les utiliser lors de changements précis.
>
> Si vous le souhaitez, vous pouvez exécuter tous les codemods v1 en une seule fois :
>
> ```bash
> npx @mastra/codemod@latest v1
> ```

### Changements à fort impact

- Adopter le format `(inputData, context)` pour les signatures des Tools créés avec `createTool` — [Tools](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/tools)
- Restructurer les imports de `@mastra/core` afin d'utiliser des imports de sous-chemins — [Classe Mastra](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/mastra)
- Remplacer la pagination `offset/limit` par `page/perPage` — [Storage](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/storage)
- Installer `@mastra/observability` et envelopper la configuration avec `new Observability()` — [Tracing](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/tracing)
- Migrer la configuration de `telemetry:` vers `observability:` lors d'une mise à niveau depuis OTEL 0.x — [Tracing](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/tracing)

### Changements à impact moyen

- Renommer `RuntimeContext` en `RequestContext` dans toute la base de code — [Classe Agent](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/agent), [Tools](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/tools), [Workflows](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/workflows)
- Renommer les méthodes de stockage du modèle `get*` vers le modèle `list*` — [Storage](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/storage)
- Remplacer l'accès direct aux propriétés par des méthodes getter — [Classe Mastra](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/mastra), [Classe Agent](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/agent)
- Mettre à jour la portée de la mémoire si vous dépendez de la portée `thread` par défaut — [Memory](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/memory)
- Mettre à jour les appels au magasin vectoriel pour utiliser des arguments nommés — [Storage](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/storage)
- Supprimer le paramètre `format` des méthodes de l'Agent — [Classe Agent](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/agent)
- Mettre à jour les méthodes vocales pour utiliser le namespace `agent.voice` — [Classe Agent](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/agent)
- Renommer la propriété de configuration `processors` en `spanOutputProcessors` si vous utilisez des processeurs personnalisés — [Tracing](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/tracing)

### Changements à faible impact

- Renommer `keepSeparator` en `separatorPosition` dans les options de découpage — [RAG](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/rag)
- Renommer `createRunAsync` en `createRun` — [Workflows](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/workflows)
- Remplacer les noms de packages vocaux `@mastra/speech-*` par `@mastra/voice-*` — [Packages Voice](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/voice)
- Mettre à jour les méthodes des Scorers : `runExperiment` → `runEvals`, `getScorerByName` → `getScorerById` — [Evals et Scorers](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/evals)
- Supprimer les options CLI obsolètes — [CLI](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/cli)
- Remplacer les types `Get*` des SDK clients par `List*` — [SDK clients](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/client)
- Remplacer `runCount` par `retryCount` — [Workflows](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/workflows)
- Remplacer la méthode `exportEvent` d'un exporter personnalisé par `exportTracingEvent` — [Tracing](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/tracing)