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, 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 pour poser vos questions.

Vous venez de Mastra Cloud ?

L'ancien produit Mastra Cloud a été remplacé par la plateforme Mastra, 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.

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

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

pnpm

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

Yarn

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

Bun

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 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 automatisés. Si vous le souhaitez, vous pouvez exécuter tous les codemods v1 en une seule fois :

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 pour plus de détails.

Changements incompatibles par domaine

• Classe Mastra — Restructuration des imports et modification de l'accès aux propriétés.
• Classe Agent — Déplacement des méthodes vocales vers un namespace et mise à jour de l'API de streaming.
• Tools — Modification de la signature execute de CreateTool afin de séparer l'entrée et le contexte.
• Workflows — Modification des noms de fonctions et suppression de fonctionnalités héritées.
• Memory — La configuration exige désormais des paramètres explicites et les valeurs par défaut ont changé.
• Storage — Standardisation de la pagination et renommage des méthodes selon le modèle list.
• Vectors — Renommage des méthodes du magasin vectoriel selon le modèle list.
• RAG — Mise à jour des noms de paramètres pour plus de clarté.
• MCP — Réorganisation du contexte des Tools et suppression des classes clientes obsolètes.
• Tracing — Remplacement de la télémétrie OTEL par un package d'observabilité dédié et des exporters.
• Evals et Scorers — Regroupement de l'API des Scorers avec de nouvelles conventions de nommage.
• CLI — Suppression de commandes et d'options pour simplifier l'interface.
• Déploiement — Mise à jour de la configuration de CloudflareDeployer pour utiliser les noms de propriétés standard de wrangler.json.
• SDK clients — Renommage des types et utilitaires pour plus de cohérence.
• Packages 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 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 :

npx @mastra/codemod@latest v1

Changements à fort impact

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

Changements à impact moyen

• Renommer RuntimeContext en RequestContext dans toute la base de code — Classe Agent, Tools, Workflows
• Renommer les méthodes de stockage du modèle get* vers le modèle list* — Storage
• Remplacer l'accès direct aux propriétés par des méthodes getter — Classe Mastra, Classe Agent
• Mettre à jour la portée de la mémoire si vous dépendez de la portée thread par défaut — Memory
• Mettre à jour les appels au magasin vectoriel pour utiliser des arguments nommés — Storage
• Supprimer le paramètre format des méthodes de l'Agent — Classe Agent
• Mettre à jour les méthodes vocales pour utiliser le namespace agent.voice — Classe Agent
• Renommer la propriété de configuration processors en spanOutputProcessors si vous utilisez des processeurs personnalisés — Tracing

Changements à faible impact

• Renommer keepSeparator en separatorPosition dans les options de découpage — RAG
• Renommer createRunAsync en createRun — Workflows
• Remplacer les noms de packages vocaux @mastra/speech-* par @mastra/voice-* — Packages Voice
• Mettre à jour les méthodes des Scorers : runExperiment → runEvals, getScorerByName → getScorerById — Evals et Scorers
• Supprimer les options CLI obsolètes — CLI
• Remplacer les types Get* des SDK clients par List* — SDK clients
• Remplacer runCount par retryCount — Workflows
• Remplacer la méthode exportEvent d'un exporter personnalisé par exportTracingEvent — Tracing