> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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.

```typescript
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 :

```typescript
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 :

```typescript
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 :

```typescript
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`](https://mastra.zisheng.pro/fr/docs/long-running-agents/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é](https://mastra.zisheng.pro/fr/docs/deployment/workers) 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-workflows). 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](https://www.inngest.com/docs/guides/scheduled-functions). Utilisez les planifications Mastra si vous souhaitez que Mastra prenne en charge l’ensemble du processus de planification.

## Voir aussi

- [Présentation des Workflows](https://mastra.zisheng.pro/fr/docs/workflows/overview)
- [Suspendre et reprendre](https://mastra.zisheng.pro/fr/docs/workflows/suspend-and-resume)
- [Workers](https://mastra.zisheng.pro/fr/docs/deployment/workers) : le [Worker de planification](https://mastra.zisheng.pro/fr/docs/deployment/workers) exécute les planifications cron dans un processus dédié
- [Planifications des Agents](https://mastra.zisheng.pro/fr/docs/long-running-agents/schedules) : 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`.