Schedules

Un agent basé sur des fichiers découvre les schedules dans son répertoire schedules/. Chaque fichier déclare une tâche récurrente : une expression cron et l’action que l’agent doit effectuer lorsqu’elle se déclenche. Mastra les enregistre dans le stockage des schedules au démarrage ; un agent planifié n’a donc besoin d’aucun code d’enregistrement à l’exécution.

Utilisez cette page pour la convention basée sur des fichiers. Pour créer des schedules à l’exécution, consultez Schedules.

defineSchedule est réexporté depuis @mastra/core/agent, ce qui permet aux agents basés sur des fichiers de n’utiliser qu’un seul chemin d’importation. @mastra/core/schedules l’exporte également.

Démarrage rapide

Ajoutez un fichier dans le répertoire schedules/ de l’agent :

src/mastra/agents/support/schedules/heartbeat.ts

import { defineSchedule } from '@mastra/core/agent'

export default defineSchedule({
  cron: '*/5 * * * *',
  prompt: 'Check system health and report any failures.',
})

Toutes les cinq minutes, Mastra exécute l’agent support avec ce prompt.

Identité d’une schedule

L’ID d’une schedule est son chemin relatif à schedules/, sans l’extension. Les répertoires imbriqués permettent donc de regrouper les schedules associées :

Schedule layout

src/mastra/agents/
└── support/
    ├── config.ts
    ├── instructions.md
    └── schedules/
        ├── heartbeat.ts      # id: heartbeat
        ├── cleanup.md        # id: cleanup
        └── billing/
            └── sweep.ts      # id: billing/sweep

Cet ID reste stable entre les builds, ce qui permet à Mastra de distinguer une schedule modifiée d’une nouvelle. Renommer ou déplacer un fichier est traité comme la suppression d’une schedule et la création d’une autre.

heartbeat.ts et heartbeat.md correspondent au même ID ; les déclarer tous les deux provoque donc une erreur de build.

Modes d’exécution

Une schedule définit exactement un mode d’exécution. Définir les deux, ou aucun, fait échouer le build.

Mode prompt

prompt exécute l’agent propriétaire avec un message fixe. Il s’agit d’un déclenchement sans attente : rien n’attend le résultat.

src/mastra/agents/support/schedules/digest.ts

import { defineSchedule } from '@mastra/core/agent'

export default defineSchedule({
  cron: '0 9 * * 1',
  timezone: 'America/New_York',
  prompt: 'Summarize last week and post the digest.',
})

Mode handler

handler calcule les paramètres du déclenchement lorsque la schedule se déclenche. Utilisez-le lorsque le prompt dépend de l’état actuel, lorsque certains déclenchements doivent être ignorés ou lorsque l’exécution a besoin du contexte de distribution de canal.

src/mastra/agents/support/schedules/billing/sweep.ts

import { defineSchedule } from '@mastra/core/agent'

export default defineSchedule({
  cron: '0 3 * * *',
  handler: async ({ mastra, agentId }) => {
    const overdue = await findOverdueInvoices()

    // Returning null skips this fire; nothing runs and the trigger is
    // recorded with outcome 'skipped'.
    if (overdue.length === 0) return null

    return {
      prompt: `Chase these overdue invoices: ${overdue.join(', ')}`,
      threadId: 'billing-ops',
      resourceId: agentId,
    }
  },
})

La valeur de retour du handler fusionne ses valeurs avec les champs stockés de la schedule. Renvoyer undefined n’applique aucune surcharge ; le déclenchement revient donc à ces champs stockés. Puisqu’une schedule en mode handler ne peut pas déclarer de prompt, ce déclenchement échoue alors en raison d’un prompt manquant. Renvoyez un prompt pour exécuter la tâche ou null pour l’ignorer.

Les handlers sont des fonctions ; ils ne peuvent donc pas être persistés dans la ligne de schedule stockée. Mastra les résout dans le processus lors du déclenchement de la schedule. Une schedule en mode handler qui ne fournit aucun prompt (et n’en déclare aucun) fait échouer ce déclenchement avec un motif, plutôt que d’envoyer un message vide à l’agent.

Cette résolution dans le processus signifie que le processus qui exécute le scheduler doit avoir enregistré l’agent propriétaire. Un déploiement normal démarre un seul point d’entrée et obtient cela automatiquement. Les workers autonomes ont besoin du même point d’entrée que votre serveur. Si vous en démarrez un depuis un point d’entrée réduit, il n’a aucun handler à appeler ; ses déclenchements échouent donc au lieu de s’exécuter.

Schedules Markdown

Une schedule .md utilise le frontmatter pour le cron et le corps du document comme prompt. Il s’agit du mode prompt, avec davantage d’espace pour écrire :

src/mastra/agents/support/schedules/cleanup.md

---
cron: '0 3 * * *'
timezone: 'UTC'
name: 'nightly cleanup'
---

Review tickets untouched for 30 days.

Close the ones that are clearly resolved and summarize the rest.

Mettez toujours le cron entre guillemets. Un * initial est un alias YAML ; ainsi, cron: */5 * * * * provoque une erreur d’analyse, alors que cron: "*/5 * * * *" fonctionne.

Le frontmatter accepte toutes les options ci-dessous sauf handler, qui nécessite une fonction et donc un module de schedule .ts ou .js. prompt ne peut pas non plus être défini, car le corps constitue le prompt. Les champs frontmatter inconnus font échouer le build plutôt que d’être ignorés silencieusement ; une faute de frappe telle que ifIdel est donc détectée au moment du build.

Options

cron:

string

Expression cron standard à cinq champs. Obligatoire. Le scheduler évalue les schedules dans une boucle de ticks ; la granularité effective est donc d’une minute. Les champs inférieurs à la minute ne sont pas pris en charge.

prompt?:

string

Message avec lequel l’agent s’exécute à chaque déclenchement. Définissez cette option ou handler, pas les deux.

handler?:

(ctx) => ScheduleOverrides | null | undefined

Calcule le déclenchement au moment où il survient. Renvoyez les surcharges à appliquer ou null pour ignorer ce déclenchement. Ne rien renvoyer n’applique aucune surcharge, ce qui fait échouer le déclenchement, car le mode handler ne possède aucun prompt stocké. Définissez cette option ou prompt, pas les deux.

timezone?:

string

Fuseau horaire IANA dans lequel le cron est évalué (par exemple, America/New_York). Utilise par défaut le fuseau horaire du processus hôte, qui varie selon le déploiement ; définissez-le donc explicitement pour tout ce qui est sensible à l’heure de la journée. Les transitions d’heure d’été sont gérées par les règles de fuseau horaire : 0 9 * * * reste donc à 9 h locale pendant le changement.

name?:

string

Libellé libre affiché dans Studio et filtrable via mastra.schedules.list({ name }).

threadId?:

string

Envoie le déclenchement comme signal dans un thread existant au lieu de démarrer une nouvelle exécution. Nécessite resourceId.

resourceId?:

string

Propriétaire du thread cible. Obligatoire lorsque threadId est défini.

signalType?:

'user' | 'state' | 'reactive' | 'notification' | 'user-message' | 'system-reminder'

= 'notification'

Catégorie de signal du déclenchement. Uniquement pour les schedules avec thread.

tagName?:

string

= 'schedule'

Balise XML sous laquelle le signal est rendu ; un déclenchement atteint ainsi l’agent sous la forme <schedule>…</schedule>.

attributes?:

Record<string, string | number | boolean | null>

Attributs rendus sur la balise XML du signal.

providerOptions?:

Record<string, unknown>

Options du fournisseur fusionnées dans la charge utile du signal de schedule à chaque déclenchement. Doivent être compatibles JSON.

ifActive?:

ScheduleIfActive

Action à effectuer lorsque le thread cible est déjà en streaming : deliver, persist ou discard. Uniquement pour les schedules avec thread.

ifIdle?:

ScheduleIfIdle

Action à effectuer lorsque le thread cible est inactif : wake, persist ou discard. Uniquement pour les schedules avec thread.

status?:

'active' | 'paused'

= 'active'

État avec lequel la ligne est créée. S’applique uniquement lors de la première création, car la synchronisation ne modifie jamais status afin qu’une mise en pause via l’API survive à un redéploiement. Modifier cette valeur dans le code ultérieurement n’a aucun effet sur une schedule existante.

metadata?:

Record<string, unknown>

Données arbitraires compatibles JSON stockées avec la ligne de schedule.

Tester une schedule en développement

Les schedules se déclenchent selon leur cadence cron, ce qui n’est pas pratique pendant les itérations. Déclenchez-en plutôt une à la demande à l’aide de son ID :

# List schedules to find the id
curl http://localhost:4111/api/schedules

# Fire one now, out-of-band from its cron
curl -X POST http://localhost:4111/api/schedules/<scheduleId>/run

Cela enregistre un déclencheur avec triggerKind: "manual" et n’avance pas nextFireAt ; la cadence normale n’est donc pas affectée. Studio liste les mêmes schedules et leur historique de déclenchements.

Les ID stockés sont placés dans un espace de noms et encodés pour les URL. billing/sweep de l’agent support devient fsa_support__billing%2Fsweep ; copiez donc l’ID depuis la réponse de liste au lieu de le construire manuellement.

Enregistrement et cycle de vie

Mastra synchronise les schedules déclarées avec le stockage des schedules au démarrage, puis à nouveau chaque fois qu’un agent est enregistré. Déclarer une schedule suffit à démarrer le scheduler, sans nécessiter scheduler: { enabled: true }.

La synchronisation compare chaque schedule déclarée à sa ligne stockée et n’écrit que ce qui a changé :

• Un nouveau fichier de schedule crée une ligne.
• Modifier cron ou timezone corrige la ligne et recalcule la prochaine heure de déclenchement ; une schedule modifiée ne se déclenche donc jamais selon son ancienne cadence.
• Supprimer ou renommer un fichier de schedule supprime sa ligne.
• Mettre une schedule en pause via l’API survit à un redéploiement. La synchronisation ne modifie délibérément pas status.

La synchronisation ne supprime que les lignes appartenant aux agents enregistrés dans le processus actuel ; un processus qui ne contient qu’un sous-ensemble de vos agents ne supprime donc jamais les schedules des autres. Lorsqu’un agent est entièrement supprimé du projet, ses lignes restantes sont nettoyées lors de leur prochain déclenchement, lorsque le scheduler ne trouve aucun agent à exécuter.

Les schedules créées à l’exécution par mastra.schedules.create(...) résident dans un espace de noms distinct et ne sont jamais touchées par cette synchronisation.

Limites

Agents racines uniquement. Les schedules doivent être déclarées sur un agent de niveau supérieur. Un répertoire schedules/ sous subagents/ provoque une erreur de build, car les sous-agents sont connectés à leur parent au lieu d’être enregistrés sur l’instance Mastra ; le scheduler ne pourrait donc jamais en résoudre un comme cible. Attribuez la schedule au parent et laissez-le déléguer.

Stockage requis. Les schedules sont des lignes persistées ; l’instance doit donc avoir un stockage configuré. Les lignes d’un stockage en mémoire ne survivent pas à un redémarrage.

Hébergement. Le scheduler s’exécute comme worker en arrière-plan dans le processus Mastra ; il a donc besoin d’un hôte qui maintient ce processus actif. Les serveurs Node de longue durée et les conteneurs conviennent. Les environnements qui gèlent ou recyclent le processus entre les requêtes, y compris la plupart des plateformes de fonctions serverless, manqueront des déclenchements. Utilisez plutôt le cron de la plateforme pour appeler le point de terminaison d’exécution.

Agents définis par le code. Un répertoire d’agent dont config.ts exporte new Agent({...}) est utilisé tel quel ; son répertoire schedules/ est donc ignoré avec un avertissement. Utilisez mastra.schedules.create(...) pour ces agents.

Exemple

Un agent de support avec deux schedules : un récapitulatif hebdomadaire fixe et un passage nocturne qui ne s’exécute que lorsqu’il y a quelque chose à faire.

Scheduled support agent

src/mastra/agents/
└── support/
    ├── config.ts
    ├── instructions.md
    └── schedules/
        ├── weekly-digest.md
        └── billing/
            └── sweep.ts

src/mastra/agents/support/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

src/mastra/agents/support/schedules/weekly-digest.md

---
cron: '0 9 * * 1'
timezone: 'America/New_York'
---

Summarize the past week's tickets and post the digest to the team channel.

src/mastra/agents/support/schedules/billing/sweep.ts

import { defineSchedule } from '@mastra/core/agent'

export default defineSchedule({
  cron: '0 3 * * *',
  timezone: 'America/New_York',
  handler: async () => {
    const overdue = await findOverdueInvoices()
    if (overdue.length === 0) return null
    return { prompt: `Draft reminders for ${overdue.length} overdue invoices.` }
  },
})