Workers

beta

Cette fonctionnalité est en version bêta. L'API est suffisamment stable pour une utilisation en production, mais certains détails peuvent encore évoluer. Consultez les limitations connues pour connaître les lacunes actuelles.

Les workers prennent en charge les traitements en arrière-plan en dehors du cycle requête-réponse. L'exécution des étapes de Workflow, la planification cron et les appels d'outils de longue durée s'exécutent tous dans des workers, ce qui préserve la réactivité de l'API.

Par défaut, les workers s'exécutent dans le même processus que l'API. Pour les charges de production, vous pouvez les répartir dans des processus ou conteneurs distincts et dimensionner chacun indépendamment.

Quand utiliser des workers

Les workers sont utiles dans les situations suivantes :

• Les étapes de Workflow durent plus de quelques secondes et ne doivent pas bloquer les réponses de l'API
• Vous avez besoin d'événements durables afin que le travail en cours survive aux redémarrages des processus
• Différentes parties du système doivent pouvoir être dimensionnées indépendamment (par exemple, davantage de capacité d'orchestration sans multiplier les instances d'API)
• Les appels d'outils en arrière-plan doivent s'exécuter sur des ressources de calcul dédiées

Si votre application reçoit peu de trafic et que les Workflows se terminent rapidement, la configuration en processus par défaut convient parfaitement. N'ajoutez l'infrastructure de workers que lorsque vous en avez besoin.

Types de workers

Mastra fournit trois types de workers intégrés. Chacun gère un type précis de traitement en arrière-plan.

Worker d'orchestration

Il s'abonne aux événements de Workflow sur le bus PubSub et exécute les étapes du Workflow. Chaque événement workflow.start, transition d'étape et événement de cycle de vie transite par ce worker.

Dans un déploiement réparti, le worker d'orchestration extrait les événements d'un backend PubSub distribué et délègue l'exécution des étapes à l'API via HTTP. En mode intégré au processus, il exécute directement les étapes.

Le worker d'orchestration nécessite un backend PubSub prenant en charge le mode pull (par exemple RedisStreamsPubSub ou GoogleCloudPubSub).

Worker de planification

Il interroge le stockage pour repérer les planifications cron arrivées à échéance et publie des événements workflow.start. Il agit uniquement comme producteur : il crée du travail que le worker d'orchestration récupère ensuite.

Le planificateur lit automatiquement les champs déclaratifs schedule de vos définitions de Workflow. Consultez les Workflows planifiés pour apprendre à déclarer des planifications.

N'exécutez pas plus d'une instance du planificateur. Plusieurs planificateurs interrogeant le même stockage déclencheraient des événements en double pour une même planification.

Worker de tâches d'arrière-plan

Il exécute les appels d'outils d'Agent marqués avec background: { enabled: true }. Lorsqu'un Agent invoque un outil d'arrière-plan, l'API transmet la tâche à ce worker au lieu de bloquer le flux de réponse.

Le worker de tâches d'arrière-plan gère les limites de concurrence, le cycle de vie des tâches et la livraison des résultats via le bus PubSub.

Modes d'exécution des workers

Mode intégré au processus (par défaut)

Sans configuration, Mastra crée et démarre les workers au sein du processus de l'API. Les événements transitent par un PubSub en mémoire et tous les composants partagent un même environnement d'exécution Node.js.

src/mastra/index.ts

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

export const mastra = new Mastra({
  // Workers run in-process by default.
  // No pubsub or worker config needed.
})

Cette configuration ne nécessite aucune infrastructure externe au-delà de votre adaptateur de stockage. Elle ne résiste pas aux arrêts brutaux du processus et ne permet pas de dimensionner les composants séparément.

Processus séparés

Pour exécuter les workers dans leurs propres processus, configurez un backend PubSub distribué et utilisez la variable d'environnement MASTRA_WORKERS pour déterminer quels workers démarrent dans chaque processus.

Redis Streams + PostgreSQL

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { RedisStreamsPubSub } from '@mastra/redis-streams'
import { PostgresStore } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new PostgresStore({
    connectionString: process.env.DATABASE_URL!,
  }),
  pubsub: new RedisStreamsPubSub({
    url: process.env.REDIS_URL!,
  }),
})

Google Cloud Pub/Sub + LibSQL

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { GoogleCloudPubSub } from '@mastra/google-cloud-pubsub'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    url: process.env.DATABASE_URL!,
  }),
  pubsub: new GoogleCloudPubSub({
    projectId: process.env.GCP_PROJECT_ID!,
  }),
})

Tout backend de stockage pris en charge convient. Remplacez l'adaptateur de stockage par celui de votre base de données préférée.

Exécutez le même artefact de build dans plusieurs conteneurs, chacun avec une valeur MASTRA_WORKERS différente afin de contrôler le worker démarré dans chaque processus.

Les déploiements répartis nécessitent un backend PubSub distribué (RedisStreamsPubSub ou GoogleCloudPubSub), un backend de stockage partagé et une connectivité réseau entre le worker d'orchestration et l'API.

Le guide de déploiement des workers décrit cette configuration avec des exemples Docker Compose et Kubernetes.

Architecture réseau

Les workers font partie de l'infrastructure interne. Ils ne sont pas exposés aux utilisateurs finaux et n'ont besoin ni de leur propre sous-domaine, ni d'une URL publique, ni d'une route HTTP entrante.

Dans un déploiement réparti :

• Le serveur d'API est le seul processus exposé publiquement : il traite toutes les requêtes HTTP des clients, notamment les points de terminaison REST, les interactions avec les Agents, les déclenchements de Workflow et les routes personnalisées.
• Les workers établissent uniquement des connexions sortantes : ils extraient les événements du backend PubSub distribué et lisent ou écrivent dans la base de données de stockage partagée. Ils n'acceptent aucun trafic entrant provenant des clients.
• Le worker d'orchestration appelle l'API en interne : il envoie les requêtes d'exécution d'étape à l'API sur le réseau des conteneurs au moyen de MASTRA_STEP_EXECUTION_URL. Il s'agit d'une communication interne entre services, et non d'un point de terminaison public.

Les trois types de workers (orchestration, planification et tâche d'arrière-plan) se trouvent derrière l'API sur un réseau privé. Ils partagent l'accès au backend PubSub et à la base de données de stockage, mais ne reçoivent jamais directement de trafic client. Si une fonctionnalité liée aux workers nécessite une route HTTP (par exemple pour émettre des jetons destinés à une intégration vocale), cette route s'exécute sur le serveur d'API, et non dans le processus du worker.

Limitations connues

• Aucune file de lettres mortes : les événements en échec reçoivent un accusé négatif et sont retentés, mais aucune DLQ ne recueille ceux qui échouent après toutes les tentatives.
• Aucun point de terminaison de santé intégré : les workers n'exposent pas de contrôle de santé HTTP. Utilisez des sondes de vivacité au niveau des conteneurs ou une surveillance des processus.
• Le planificateur ne doit avoir qu'une instance : l'exécution de plusieurs processus de planification déclenche les mêmes planifications en double.
• Exécutions bloquées à l'état « running » après un arrêt brutal de l'API : si le processus de l'API s'interrompt pendant l'exécution d'une étape de Workflow, l'exécution reste à l'état running sans nouvelle tentative automatique. Pour les Agents durables, définissez recovery.durableAgents sur 'auto' dans la configuration de Mastra afin de relancer automatiquement les exécutions orphelines au redémarrage du serveur. Consultez la récupération après incident pour plus de détails.

Voir aussi

• Guide de déploiement des workers : exemples Docker Compose et Kubernetes
• Authentification des workers : sécuriser les communications entre les workers et l'API
• Référence des workers : détails sur les variables d'environnement et les types de workers, avec la liste des backends de stockage pris en charge
• Référence de la CLI : mastra worker build et mastra worker start
• PubSub : backends de livraison des événements
• Workflows planifiés : déclarer des planifications cron sur les Workflows