Classe Mastra

La classe Mastra est l’orchestrateur central de toute application Mastra ; elle gère les Agents, les Workflows, le stockage, les logs, l’observabilité et bien plus encore. En général, vous créez une seule instance de Mastra pour coordonner votre application.

Considérez Mastra comme un registre de niveau supérieur dans lequel vous enregistrez les Agents, les Workflows, les Tools et les autres composants qui doivent être accessibles dans toute votre application.

Exemple d’utilisation

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'
import { LibSQLStore } from '@mastra/libsql'
import { weatherWorkflow } from './workflows/weather-workflow'
import { weatherAgent } from './agents/weather-agent'

export const mastra = new Mastra({
  workflows: { weatherWorkflow },
  agents: { weatherAgent },
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: ':memory:',
  }),
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
})

Activez l’envoi planifié des notifications lorsque les enregistrements de notifications différées et les résumés de notifications doivent être remis automatiquement par l’intermédiaire du planificateur de Workflows :

src/mastra/index.ts

export const mastra = new Mastra({
  agents: { supportAgent },
  storage,
  notifications: {
    dispatch: {
      enabled: true,
      cron: '*/1 * * * *',
      batchSize: 100,
    },
  },
})

notifications.dispatch.enabled permet à un Workflow de distribution interne de s’exécuter avec l’expression cron par défaut */1 * * * *. Le distributeur lit dans le stockage les enregistrements de notifications arrivés à échéance, regroupe les résumés par agentId, resourceId et threadId, puis émet des signaux via l’environnement d’exécution des fils de l’Agent. Il ne s’agit pas d’un point d’entrée destiné aux utilisateurs. La planification de la distribution (et le planificateur de Workflows qui la sous-tend) ne s’active qu’à la première notification différée ou résumée ; les applications qui ne différèrent jamais de notifications n’exécutent donc aucun planificateur.

Paramètres du constructeur

Consultez la référence de configuration pour obtenir une documentation détaillée de toutes les options de configuration disponibles.

agents?:

Record<string, Agent>

= {}

Instances d’Agent à enregistrer, indexées par nom

tools?:

Record<string, ToolApi>

= {}

Instances de Tool à enregistrer. Les clés sont les clés d’enregistrement utilisées par `getTool()`, et les valeurs sont les instances de Tool. Utilisez `getToolById()` pour rechercher un ID intrinsèque et `listTools()` pour lire le registre.

storage?:

MastraCompositeStore

Instance du moteur de stockage utilisée pour conserver les données

vectors?:

Record<string, MastraVector>

Instance de base vectorielle utilisée pour la recherche sémantique et les Tools vectoriels (par exemple Pinecone, PgVector ou Qdrant)

logger?:

Logger

= Logger de console avec le niveau INFO

Instance de logger créée avec new PinoLogger()

idGenerator?:

(context?: IdGeneratorContext) => string

Fonction personnalisée de génération d’ID. Utilisée par les Agents, les Workflows, la Memory et d’autres composants pour générer des identifiants uniques. Reçoit un contexte facultatif tel que idType, source, entityId et threadId afin de prendre en charge des formats d’ID dépendant du contexte.

workflows?:

Record<string, Workflow>

= {}

Workflows à enregistrer. Structurés sous forme de paires clé-valeur, où les clés sont les noms des Workflows et les valeurs leurs instances.

tts?:

Record<string, MastraVoice>

Providers de synthèse vocale à partir de texte

observability?:

ObservabilityEntrypoint

Configuration de l’observabilité pour le traçage et la surveillance

environment?:

string

Nom de l’environnement de déploiement (par exemple production, staging, development). Lorsqu’il est défini, il est automatiquement joint à tous les signaux d’observabilité afin de permettre leur filtrage par environnement sans transmettre tracingOptions.metadata.environment à chaque appel. Utilise process.env.NODE_ENV comme valeur de repli lorsqu’il n’est pas défini ; reste indéfini si aucune des deux valeurs ne l’est. La valeur tracingOptions.metadata.environment propre à l’appel est toujours prioritaire.

deployer?:

MastraDeployer

Instance de MastraDeployer destinée à la gestion des déploiements.

server?:

ServerConfig

Configuration du serveur comprenant le port, l’hôte, le délai d’expiration, les routes d’API, les middlewares, les paramètres CORS ainsi que les options de build pour Swagger UI, la journalisation des requêtes d’API et la documentation OpenAPI.

mcpServers?:

Record<string, MCPServerBase>

Objet dont les clés sont les clés du registre (utilisées par getMCPServer()) et les valeurs des instances de MCPServer ou des classes qui étendent MCPServerBase. Chaque MCPServer doit posséder une propriété id. Les serveurs peuvent être récupérés par leur clé de registre à l’aide de getMCPServer(), ou par leur id intrinsèque à l’aide de getMCPServerById().

bundler?:

BundlerConfig

= { externals: [], sourcemap: false, transpilePackages: [], dynamicPackages: [] }

Configuration du bundler de ressources avec des options pour externals, sourcemap, transpilePackages et dynamicPackages.

scorers?:

Record<string, Scorer>

= {}

Scorers servant à évaluer les réponses des Agents et les sorties des Workflows

processors?:

Record<string, Processor>

= {}

Processeurs d’entrée/sortie permettant de transformer les entrées et les sorties des Agents

gateways?:

Record<string, MastraModelGateway>

= {}

Gateways de modèles personnalisées à enregistrer pour accéder aux modèles d’IA par l’intermédiaire de Providers alternatifs ou de déploiements privés. Structurées sous forme de paires clé-valeur, où les clés sont les clés du registre (utilisées par getGateway()) et les valeurs les instances de gateway.

memory?:

Record<string, MastraMemory>

= {}

Instances de Memory à enregistrer. Elles peuvent être référencées par les Agents stockés et résolues au moment de l’exécution. Structurées sous forme de paires clé-valeur, où les clés sont les clés du registre et les valeurs les instances de Memory.

notifications?:

object

Configuration d’exécution pour la distribution des signaux de notification.

object

dispatch?:

NotificationDispatchConfig

Configuration de la distribution planifiée des notifications différées et des résumés de notifications. La distribution est activée par défaut.

object

enabled?:

boolean

Définissez sur false pour désactiver la distribution planifiée automatique des notifications.

cron?:

string

Planification cron utilisée par le Workflow interne de distribution des notifications.

batchSize?:

number

Nombre maximal d’enregistrements de notifications arrivés à échéance à traiter par exécution de la distribution.

versions?:

VersionOverrides

Remplacements globaux de version pour la délégation aux sous-Agents. Lorsqu’un Agent superviseur délègue à un sous-Agent, ces remplacements déterminent la version stockée de ce sous-Agent à utiliser à la place de celle définie par défaut dans le code. Nécessite la configuration du package de l’éditeur. Pour en savoir plus, consultez le versionnement dans l’éditeur.

VersionOverrides

agents?:

Record<string, VersionSelector>

Table de correspondance entre les ID d’Agents et leurs sélecteurs de version. Chaque sélecteur peut cibler une version donnée par son ID ou son statut de publication.

VersionSelector

versionId?:

string

ID d’une version précise à utiliser.

status?:

'draft' | 'published'

Sélectionne la dernière version ayant ce statut de publication.

workers?:

MastraWorker[] | false

Configure les workers qui s’exécutent dans cette instance Mastra. Lorsque cette option est omise, Mastra crée automatiquement des workers par défaut en fonction de votre PubSub et de votre configuration. Transmettez false pour désactiver tout traitement des événements (utile lorsque des workers autonomes sont exécutés séparément). Transmettez un MastraWorker[] pour ajouter des workers personnalisés : ils sont fusionnés avec les valeurs par défaut créées automatiquement, et un worker personnalisé ayant le même name qu’une valeur par défaut la remplace.

backgroundTasks?:

BackgroundTaskManagerConfig

Configure l’exécution des tâches en arrière-plan pour les Agents. Consultez la référence de configuration des tâches en arrière-plan pour découvrir toutes les options.

BackgroundTaskManagerConfig

enabled?:

boolean

Active la distribution des tâches en arrière-plan.

globalConcurrency?:

number

Nombre maximal de tâches simultanées pour l’ensemble des Agents.

perAgentConcurrency?:

number

Nombre maximal de tâches simultanées par Agent.

backpressure?:

'queue' | 'reject' | 'fallback-sync'

Comportement lorsque la limite d’accès concurrent est atteinte.

defaultTimeoutMs?:

number

Délai d’expiration par défaut des tâches, en millisecondes.

defaultRetries?:

RetryConfig

Configuration par défaut des nouvelles tentatives.

scheduler?:

object

Configure le worker de planification pour les déclencheurs de Workflow pilotés par cron. S’active automatiquement lorsqu’un Workflow déclare un schedule. Consultez les Workflows planifiés.

object

enabled?:

boolean

Active ou désactive explicitement le planificateur.

recovery?:

MastraRecoveryConfig

= { durableAgents: 'off' }

Comportement de récupération au démarrage pour les exécutions orphelines d’Agents et de Workflows. Consultez la récupération après incident.

object

durableAgents?:

'auto' | 'off'

Définissez sur 'auto' pour relancer automatiquement au démarrage du serveur les exécutions RUNNING orphelines d’Agents durables. La récupération relance les appels au LLM et réexécute les appels de Tools ; les Tools doivent donc être idempotents. Consultez la récupération après incident.

Méthodes

recoverAllDurableAgents()

Relance chaque exécution running orpheline d’Agent durable pour l’ensemble des Agents durables enregistrés. Appelée automatiquement au démarrage lorsque recovery.durableAgents vaut 'auto'. Vous pouvez également l’appeler directement pour effectuer une récupération manuelle ou depuis une tâche planifiée.

Nécessite un stockage persistant. Avec un stockage en mémoire, il n’y a rien à récupérer après le redémarrage d’un processus.

const result = await mastra.recoverAllDurableAgents()
// { agents: 2, recovered: 3, succeeded: 3, failed: 0 }

Renvoie :

agents:

number

Nombre d’Agents durables analysés.

recovered:

number

Nombre total d’exécutions relancées.

succeeded:

number

Exécutions redémarrées avec succès.

failed:

number

Exécutions dont le redémarrage a déclenché une erreur.