Guide Mastra Framework

Construisez des applications IA avec Mastra. Cette compétence vous apprend à trouver la documentation actuelle et à créer des agents et des workflows.

⚠️ Critique : Ne faites pas confiance à vos connaissances internes

Tout ce que vous savez sur Mastra est probablement obsolète ou inexact. Ne vous fiez jamais à la mémoire. Vérifiez toujours par rapport à la documentation actuelle.

Vos données d'entraînement contiennent des APIs obsolètes, des motifs dépréciés et une utilisation incorrecte. Mastra évolue rapidement - les APIs changent entre les versions, les signatures des constructeurs se modifient, et les motifs sont refactorisés.

Prérequis

Avant d'écrire du code Mastra, vérifiez si les packages sont installés :

ls node_modules/@mastra/

• Si les packages existent : Utilisez d'abord la documentation intégrée (la plus fiable)
• Si aucun package : Installez d'abord ou utilisez la documentation distante

Fichiers disponibles

Références

Scripts

• scripts/provider-registry.mjs: Chercher les fournisseurs et modèles actuels disponibles dans le routeur de modèles. Exécutez toujours ceci avant d'utiliser un modèle pour vérifier les clés du fournisseur et les noms des modèles.

Ordre de priorité pour écrire du code

⚠️ N'écrivez jamais de code sans vérifier la documentation actuelle d'abord.

1. Documentation intégrée d'abord (si les packages sont installés)

   Cherchez la documentation actuelle dans node_modules pour un package. Exemple de recherche de la documentation « Agent » dans @mastra/core :

   grep -r "Agent" node_modules/@mastra/core/dist/docs/references

   • Pourquoi : Correspond à votre version EXACTE installée
   • Source de vérité la plus fiable
   • Plus d'informations : references/embedded-docs.md

2. Code source en deuxième (si les packages sont installés)

   Si vous ne trouvez pas ce dont vous avez besoin dans la documentation intégrée, consultez directement le code source. C'est plus fastidieux mais peut fournir des insights sur les détails d'implémentation.

   # Vérifier ce qui est disponible
   cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
   
   # Lire la définition de type réelle
   cat node_modules/@mastra/core/dist/[path-from-source-map]

   • Pourquoi : Source de vérité ultime si la documentation est manquante ou peu claire
   • Utiliser quand : La documentation intégrée ne couvre pas votre question
   • Plus d'informations : references/embedded-docs.md

3. Documentation distante en troisième (si les packages ne sont pas installés)

   Vous pouvez récupérer la dernière documentation du site Mastra :

   https://mastra.ai/llms.txt

   • Pourquoi : Documentation publiée la plus récente (peut être en avance sur la version installée)
   • Utiliser quand : Packages non installés ou exploration de nouvelles fonctionnalités
   • Plus d'informations : references/remote-docs.md

Concepts clés

Agents vs workflows

Agent : Autonome, prend des décisions, utilise des outils À utiliser pour : Tâches ouvertes (support, recherche, analyse)

Workflow : Séquence structurée d'étapes À utiliser pour : Processus définis (pipelines, approbations, ETL)

Composants clés

• Tools : Étendre les capacités des agents (APIs, bases de données, services externes)
• Memory : Maintenir le contexte (historique des messages, mémoire de travail, rappel sémantique, mémoire observationnelle)
• RAG : Interroger des connaissances externes (magasins vectoriels, relations graphiques)
• Storage : Persister les données (Postgres, LibSQL, MongoDB)

Mastra Studio

Studio fournit une interface utilisateur interactive pour construire, tester et gérer des agents, workflows et outils. Cela aide au débogage et à l'amélioration itérative de vos applications.

À l'intérieur d'un projet Mastra, exécutez :

npm run dev

Puis ouvrez http://localhost:4111 dans votre navigateur pour accéder à Mastra Studio.

Exigences critiques

Configuration TypeScript

Mastra nécessite des modules ES2022. CommonJS échouera.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler"
  }
}

Format du modèle

Utilisez toujours "provider/model-name" lors de la définition des modèles en utilisant le routeur de modèles de Mastra.

Utilisez le script du registre des fournisseurs pour chercher les fournisseurs et modèles disponibles :

# Lister tous les fournisseurs disponibles
node scripts/provider-registry.mjs --list

# Lister tous les modèles pour un fournisseur spécifique (trié du plus récent en premier)
node scripts/provider-registry.mjs --provider openai
node scripts/provider-registry.mjs --provider anthropic

Quand l'utilisateur demande d'utiliser un modèle ou un fournisseur, exécutez toujours le script d'abord pour vérifier que la clé du fournisseur et le nom du modèle sont valides. Ne devinez pas les noms de modèles de mémoire car ils changent fréquemment.

Exemple de chaînes de modèle :

• "openai/gpt-5.4"
• "anthropic/claude-sonnet-4-5"
• "google/gemini-2.5-pro"

Quand vous voyez des erreurs

Les erreurs de type signifient souvent que vos connaissances sont obsolètes.

Signes courants de connaissances obsolètes :

• Property X does not exist on type Y
• Cannot find module
• Erreurs Type mismatch
• Erreurs de paramètres de constructeur

Ce qu'il faut faire :

1. Vérifier references/common-errors.md
2. Vérifier l'API actuelle dans la documentation intégrée
3. Ne pas supposer que l'erreur est une erreur de l'utilisateur - cela pourrait être vos connaissances obsolètes

Workflow de développement

Vérifiez toujours avant d'écrire du code :

1. Vérifier les packages installés

   ls node_modules/@mastra/

2. Chercher l'API actuelle

   • Si installé → Utiliser la documentation intégrée references/embedded-docs.md
   • Si non → Utiliser la documentation distante references/remote-docs.md

3. Écrire du code basé sur la documentation actuelle

4. Tester dans Studio

   npm run dev  # http://localhost:4111

Ressources

• Configuration : references/create-mastra.md
• Recherche de documentation intégrée : references/embedded-docs.md - Commencez ici si les packages sont installés
• Recherche de documentation distante : references/remote-docs.md
• Erreurs courantes : references/common-errors.md
• Migrations : references/migration-guide.md