Workflows planifiés

Déclarez un champ schedule dans un Workflow et Mastra le déclenchera selon l’expression cron indiquée. Ce même Workflow reste directement exécutable avec workflow.start() : les déclenchements planifiés et les exécutions manuelles empruntent le même chemin d’exécution.

Démarrage rapide

Le Workflow suivant s’exécute chaque jour à 9 h, heure de New York. Enregistrez-le dans Mastra comme n’importe quel autre Workflow : le planificateur le détecte automatiquement.

src/mastra/workflows/daily-report.ts

import { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'

const sendReport = createStep({
  id: 'send-report',
  inputSchema: z.object({ userId: z.string() }),
  outputSchema: z.object({ ok: z.boolean() }),
  execute: async ({ inputData }) => {
    // ...send the report for inputData.userId
    return { ok: true }
  },
})

export const dailyReport = createWorkflow({
  id: 'daily-report',
  inputSchema: z.object({ userId: z.string() }),
  outputSchema: z.object({ ok: z.boolean() }),
  schedule: {
    cron: '0 9 * * *',
    timezone: 'America/New_York',
    inputData: { userId: 'system' },
  },
})
  .then(sendReport)
  .commit()

Aucun appel distinct d’« enregistrement de la planification » n’est nécessaire. Le planificateur lit directement le champ schedule du Workflow lorsque Mastra démarre.

Ce que modifie schedule

Un Workflow qui déclare schedule est automatiquement promu vers le moteur d’exécution événementiel. L’API publique (workflow.start(), workflow.startAsync(), streamLegacy(), resume()) ne change pas : EventedWorkflow extends Workflow et redéfinit chaque méthode avec une signature identique. Du point de vue de votre code, les déclenchements planifiés et les exécutions manuelles sont indifférenciables.

Cette promotion a une conséquence pratique : les exécutions événementielles nécessitent un adaptateur de stockage qui prend en charge les mises à jour simultanées, comme @mastra/libsql. Si votre adaptateur ne les prend pas en charge, createRun() lève une erreur explicite qui désigne le champ schedule. Changez d’adaptateur ou supprimez la planification.

Planification unique

Transmettez un objet à schedule pour déclencher un Workflow selon une seule fréquence :

src/mastra/workflows/daily-report.ts

const dailyReport = createWorkflow({
  id: 'daily-report',
  schedule: {
    cron: '0 9 * * *',
    timezone: 'America/New_York',
    inputData: { userId: 'system' },
  },
  // ...
})

Champs :

• cron (obligatoire) : expression cron en 5, 6 ou 7 parties. Elle est validée lors de la construction du Workflow.
• timezone (facultatif) : fuseau horaire IANA, par exemple America/New_York. Par défaut, le fuseau horaire local de l’hôte est utilisé. Définissez-le explicitement en production afin que les heures de déclenchement ne dépendent pas des paramètres régionaux du serveur.
• inputData (facultatif) : charge utile transmise en entrée du Workflow à chaque déclenchement.
• initialState (facultatif) : état initial de l’exécution.
• requestContext (facultatif) : contexte de requête associé à l’exécution.
• metadata (facultatif) : métadonnées arbitraires conservées avec l’enregistrement de planification.

Planifications multiples

Transmettez un tableau pour déclencher le même Workflow selon plusieurs fréquences. Chaque entrée doit posséder un id unique et stable :

src/mastra/workflows/status-check.ts

const statusCheck = createWorkflow({
  id: 'status-check',
  schedule: [
    { id: 'morning', cron: '0 9 * * *', inputData: { window: 'morning' } },
    { id: 'evening', cron: '0 18 * * *', inputData: { window: 'evening' } },
  ],
  // ...
})

Chaque entrée crée un enregistrement de planification indépendant, se déclenche selon sa propre expression cron et apparaît séparément dans la vue Schedules de Studio.

Consulter les planifications dans Studio

Studio présente les planifications dans une section de premier niveau, et non dans un onglet du Workflow :

• Toutes les planifications : ouvrez /workflows/schedules pour afficher la liste de tous les Workflows. Chaque ligne indique l’identifiant du Workflow, l’expression cron, le prochain déclenchement et l’état de l’exécution la plus récente. Vous pouvez ainsi voir d’un coup d’œil si un élément pose problème.
• Filtrage par Workflow : ajoutez ?workflowId=<id> pour limiter la liste à un seul Workflow, par exemple /workflows/schedules?workflowId=daily-report.
• Détails d’une planification : sélectionnez une ligne pour ouvrir /workflows/schedules/:scheduleId. La page affiche les métadonnées de la planification et les commandes Pause / Resume, suivies de l’historique complet des déclenchements.

L’en-tête d’un Workflow comporte une action Schedules lorsqu’il possède au moins une planification :

• Si une seule planification correspond, l’action renvoie directement vers sa page de détails.
• S’il existe plusieurs planifications, l’action renvoie vers la liste filtrée par Workflow à l’adresse /workflows/schedules?workflowId=<id>.
• S’il n’existe aucune planification, l’action est masquée.

Historique des déclenchements

Chaque déclenchement crée un enregistrement qui contient l’identifiant de l’exécution, l’heure planifiée, l’heure réelle de déclenchement et l’état de publication. La page de détails de la planification associe chaque déclenchement à l’exécution correspondante du Workflow et affiche :

• L’état de l’exécution (running, success, failed, suspended, canceled) sous forme de badge.
• L’heure de début et la durée de l’exécution.
• Un lien vers la vue graphique complète de l’exécution à l’adresse /workflows/:workflowId/graph/:runId.
• Un badge pending pour les déclenchements dont l’enregistrement d’exécution n’a pas encore été écrit en raison d’une condition de concurrence entre la publication du déclenchement et l’instantané de l’exécution.
• Un badge publish failed accompagné de l’erreur de publication lorsque le planificateur n’a pas pu placer l’exécution dans la file d’attente.

Lorsque des déclenchements se trouvent dans un état non terminal, le panneau actualise les données toutes les cinq secondes jusqu’à ce qu’ils atteignent un état terminal. La liste est paginée afin que les planifications de longue durée ne chargent pas des milliers de lignes dès l’ouverture.

Suspendre une planification lors de l’exécution

Lorsqu’un Workflow planifié se déclenche incorrectement en production, vous n’avez pas besoin de le redéployer ni de modifier manuellement la base de données. Suspendez-le depuis le SDK :

import { MastraClient } from '@mastra/client-js'

const client = new MastraClient({ baseUrl: 'http://localhost:4111' })

// Schedule ids are derived from the workflow id: `wf_<workflowId>` for a
// single declarative schedule, or `wf_<workflowId>__<scheduleId>` when you
// declare multiple schedules per workflow as an array.
await client.pauseSchedule('wf_daily-report')
// ...investigate, ship a fix, then:
await client.resumeSchedule('wf_daily-report')

Dans Studio, ouvrez la page de détails de la planification et sélectionnez Pause ou Resume dans l’en-tête.

Quelques règles à connaître :

• La suspension est persistante. L’état est écrit dans la table des planifications et résiste aux redémarrages du processus et aux redéploiements. L’upsert de la configuration déclarative ne remplace jamais un état défini par l’utilisateur, même lorsque vous modifiez cron, timezone ou d’autres champs.
• La reprise recalcule nextFireAt à partir de l’instant présent. Une planification suspendue pendant une semaine ne déclenche pas sept exécutions en attente dès sa reprise. Elle se déclenche au prochain passage normal de l’expression cron.
• Reprenez la planification avec resumeSchedule ou le bouton Resume de Studio. Modifier la configuration schedule du Workflow ne réactive pas un enregistrement suspendu.
• La suspension et la reprise sont idempotentes. Suspendre une planification déjà suspendue est une opération sans effet.
• Cette dérogation opérationnelle contrôle les planifications existantes. Définissez les planifications déclaratives dans le code. Elles sont créées, supprimées et modifiées dans le code au moyen du champ schedule de createWorkflow. Pour créer plutôt des planifications impératives lors de l’exécution, utilisez le service unifié mastra.schedules avec un workflowId.

Les routes HTTP sous-jacentes sont POST /api/schedules/:scheduleId/pause et POST /api/schedules/:scheduleId/resume. Elles nécessitent toutes deux l’autorisation schedules:write.

Redéployer après des modifications

Lorsque vous modifiez la configuration schedule et redéployez, Mastra compare l’enregistrement de planification existant à la nouvelle configuration :

• Si cron ou timezone a changé, nextFireAt est recalculé.
• Si seuls inputData, initialState ou metadata ont changé, l’enregistrement est mis à jour sur place et l’heure du prochain déclenchement est conservée.
• L’état défini par l’utilisateur (par exemple, une suspension effectuée avec client.pauseSchedule) et l’historique des déclenchements ne sont jamais remplacés.

La suppression d’une entrée de planification dans le tableau schedule d’un Workflow entraîne la suppression de son enregistrement au démarrage suivant.

Topologie de déploiement

Le planificateur intégré utilise une boucle de battement setInterval pour interroger la table des planifications et revendiquer les enregistrements arrivés à échéance. Il distribue les exécutions de Workflows par l’intermédiaire du système pubsub du processus. Il suppose que le processus hôte reste actif longtemps.

Hôte de longue durée (recommandé)

Les cibles de déploiement comme Fly Machines, Railway, Render, AWS ECS, GKE ou votre propre serveur maintiennent le processus Mastra actif entre les déclenchements cron. Les planifications fonctionnent sans configuration supplémentaire. Pour les déploiements en production, vous pouvez exécuter le planificateur dans un processus de Worker dédié afin de l’isoler de la couche API.

Plateformes serverless

Les plateformes de fonctions en tant que service, comme Vercel, Netlify, AWS Lambda et Cloudflare Workers, arrêtent le processus après chaque requête. Comme la boucle de battement n’a pas l’occasion d’effectuer un second passage, les planifications déclarées dans le code ne se déclenchent actuellement pas sur ces plateformes avec le planificateur intégré.

Sur ces plateformes, utilisez plutôt @mastra/inngest. Inngest est conçu nativement pour le serverless et conserve l’état cron à votre place.

Workflows Inngest

Le champ schedule décrit sur cette page pilote le planificateur intégré de Mastra. Si vous utilisez @mastra/inngest, les Workflows planifiés sont configurés au moyen du champ cron propre à Inngest dans createFunction et sont déclenchés par le planificateur d’Inngest.

Conséquences pratiques :

• Les planifications Inngest n’apparaissent pas dans la vue /workflows/schedules de Studio.
• L’action Schedules de l’en-tête du Workflow ne s’affiche pas pour les Workflows Inngest.
• client.pauseSchedule et client.resumeSchedule ne contrôlent pas les planifications Inngest.

Gérez les planifications Inngest depuis le tableau de bord Inngest. Utilisez les planifications Mastra si vous souhaitez que Mastra prenne en charge l’ensemble du processus de planification.

Voir aussi

• Présentation des Workflows
• Suspendre et reprendre
• Workers : le Worker de planification exécute les planifications cron dans un processus dédié
• Planifications des Agents : exécutez un Agent plutôt qu’un Workflow selon une planification cron et gérez les deux types de planification lors de l’exécution au moyen de mastra.schedules.