Planifications

Ajouté dans : @mastra/core@1.50.0

beta

Cette fonctionnalité est en bêta. Des changements incompatibles peuvent survenir sans hausse de version majeure tant que l’API n’est pas stable.

Une planification exécute un Agent selon une cadence cron. À chaque déclenchement, Mastra envoie un prompt à l'Agent, soit comme signal dans un thread, soit comme exécution agent.generate() sans thread. Utilisez les planifications pour les tâches récurrentes d'un Agent, telles que les résumés quotidiens, les vérifications périodiques ou les relances programmées dans une conversation.

Les planifications sont persistantes : elles survivent aux redémarrages et aux redéploiements. Gérez-les à l'exécution au moyen de mastra.schedules, l'interface canonique pour les opérations de création, lecture, mise à jour et suppression (CRUD). Cette même interface gère également les planifications de Workflow ; transmettez workflowId à la place de agentId pour planifier un Workflow.

remarque

Les planifications nécessitent un adaptateur de stockage qui implémente le domaine des planifications. Consultez la référence de mastra.schedules pour connaître les adaptateurs pris en charge et le comportement de l'API.

Démarrage rapide

La planification suivante exécute l'Agent pinger toutes les heures. Elle n'utilise aucun thread ; chaque déclenchement correspond donc à une exécution agent.generate() isolée.

src/mastra/schedules.ts

import { Mastra } from '@mastra/core'
import { Agent } from '@mastra/core/agent'
import { LibSQLStore } from '@mastra/libsql'

const pinger = new Agent({
  id: 'pinger',
  name: 'Pinger',
  instructions: 'Report the current system status in one sentence.',
  model: 'openai/gpt-5.6-sol',
})

const mastra = new Mastra({
  agents: { pinger },
  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
})

await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 * * * *',
  prompt: 'Give me a status update.',
})

Mastra démarre le planificateur lors de la création de la première planification, puis déclenche l'Agent selon l'expression cron indiquée.

Cadence

Les planifications se déclenchent selon une expression cron. Le champ cron accepte une expression cron standard en cinq, six ou sept parties, validée lors de la création ou de la mise à jour de la planification.

Les alias de croner fonctionnent également, par exemple @hourly, @daily, @weekly, @monthly et @midnight. Pour combiner un jour et une heure, écrivez directement le champ cron :

// Every weekday at 9am
await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 9 * * 1-5',
  prompt: 'Start-of-day check.',
})

Définissez timezone sur un fuseau horaire IANA, par exemple America/New_York, afin que les heures de déclenchement ne dépendent pas des paramètres régionaux de l'hôte. Si cette valeur est omise, l'expression cron est interprétée dans le fuseau horaire local de l'hôte.

Pour construire des expressions cron plus lisibles, vous pouvez utiliser une bibliothèque telle que cron-time-generator, puis transmettre son résultat à cron.

Planifications avec ou sans thread

Une planification d'Agent se déclenche selon l'un de deux modes, déterminé par la présence ou l'absence d'un threadId.

Sans thread

Sans threadId, chaque déclenchement correspond à une exécution agent.generate() isolée. Rien n'est écrit dans un thread de conversation. Ce mode, le plus simple, convient aux contrôles d'état, aux rapports et aux autres tâches qui ne nécessitent pas le contexte d'une conversation.

Avec thread

Avec un threadId, la planification envoie un signal dans ce thread, de sorte que le prompt rejoint la conversation de l'Agent. Les planifications avec thread nécessitent un resourceId en plus du threadId.

src/mastra/schedules.ts

await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 9 * * *',
  prompt: 'Summarize anything new since yesterday.',
  threadId: 'thread-123',
  resourceId: 'user-456',
})

Les planifications avec thread acceptent des champs supplémentaires qui contrôlent le comportement du signal, notamment son type, la balise XML, les attributs de la balise et le comportement de livraison lorsque le thread est actif ou inactif. Ces champs reprennent les options acceptées par agent.sendSignal() et restent sérialisables en JSON afin d'être conservés avec la planification.

Ces champs nécessitent un threadId. Pour connaître la forme complète des entrées avec thread, consultez la référence des entrées de planification d'Agent.

await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 9 * * *',
  prompt: 'Summarize anything new since yesterday.',
  threadId: 'thread-123',
  resourceId: 'user-456',
  tagName: 'check-in', // renders as <check-in>…</check-in>
  attributes: { source: 'cron' },
  ifActive: { behavior: 'discard' }, // skip if the thread is mid-stream
  ifIdle: {
    behavior: 'wake', // wake the agent if the thread is idle
    streamOptions: { requestContext: { locale: 'en-US' } },
  },
})

providerOptions est fusionné avec la charge utile du signal à chaque déclenchement et s'applique aux planifications avec ou sans thread.

Gérer les planifications

Utilisez mastra.schedules pour toutes les opérations liées aux planifications. Le service permet de créer, lire, mettre à jour, suspendre, reprendre, exécuter manuellement et supprimer les planifications.

const schedule = await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 * * * *',
  prompt: 'Status check.',
})

await mastra.schedules.pause(schedule.id)
await mastra.schedules.resume(schedule.id)
await mastra.schedules.run(schedule.id) // Fire once now, off-schedule

pause et resume sont persistants. run déclenche immédiatement la planification une fois sans modifier sa cadence. Pour la liste complète des méthodes, des filtres et des champs de mise à jour, consultez la référence de mastra.schedules.

Planifications de Workflow

Le même service crée des planifications qui exécutent un Workflow à la place d'un Agent. Transmettez workflowId et les champs propres au Workflow :

await mastra.schedules.create({
  workflowId: 'daily-report',
  cron: '0 9 * * *',
  inputData: { userId: 'system' },
})

Les planifications de Workflow ainsi créées sont indépendantes du champ déclaratif schedule de createWorkflow. Consultez les Workflows planifiés pour la forme déclarative et les vues de Studio.

Identifiants personnalisés

Transmettez id lorsque vous avez besoin d'un identifiant prévisible pour rechercher, mettre à jour ou supprimer la planification ultérieurement.

await mastra.schedules.create({
  id: 'nightly-summary',
  agentId: 'pinger',
  cron: '0 9 * * *',
  prompt: 'Summarize anything new since yesterday.',
})

Consultez la référence de create(input) pour les règles de normalisation des identifiants et le comportement en cas de doublon.

Depuis le client

Les mêmes opérations sont disponibles depuis @mastra/client-js via les routes /api/schedules. Vous pouvez donc gérer les planifications depuis un processus distinct ou une interface utilisateur. Consultez la référence des planifications d'Agent de client-js pour la liste des méthodes du client.

Hooks de cycle de vie

Les hooks permettent d'exécuter du code à des moments clés du cycle de vie d'une planification d'Agent, par exemple pour calculer des paramètres au moment du déclenchement ou réagir au résultat. Configurez-les dans le constructeur Mastra, sous schedules. Les hooks forment un ensemble unique et plat exécuté pour les planifications de tous les Agents ; le contexte de chaque hook contient l'agentId déclenché, ce qui permet d'adapter le comportement à chaque Agent. Les hooks sont définis au niveau de Mastra et s'appliquent donc aux Agents définis dans le code comme à ceux stockés.

src/mastra/index.ts

const mastra = new Mastra({
  agents: { pinger },
  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
  schedules: {
    prepare: async ({ agentId, schedule, trigger }) => {
      // Return overrides, null to skip this fire, or undefined for defaults
      return { prompt: `Status as of ${trigger.firedAt.toISOString()}` }
    },
    onFinish: async ({ agentId, outcome, runId }) => {
      // Runs on any non-error, non-abort outcome
    },
    onError: async ({ agentId, phase, error }) => {
      // Runs when prepare, the signal, or the agent run threw
    },
    onAbort: async ({ agentId, runId }) => {
      // Runs when the run was aborted mid-stream
    },
  },
})

Les hooks disponibles sont les suivants :

• prepare : s'exécute avant le déclenchement. Renvoyez un objet pour remplacer des paramètres tels que prompt ou threadId, null pour ignorer le déclenchement, ou undefined pour utiliser les valeurs par défaut enregistrées.
• onFinish : s'exécute une fois pour chaque déclenchement ayant atteint un état terminal qui n'est ni une erreur ni un abandon.
• onError : s'exécute après un échec dans prepare ou dans le signal, ainsi qu'en cas d'échec de l'exécution de l'Agent.
• onAbort : s'exécute lorsque l'exécution est interrompue au milieu du flux.

Le contexte de chaque hook comprend agentId, l'Agent déclenché par la planification, ainsi que schedule et trigger.

Les exceptions des hooks sont interceptées et journalisées. Elles ne réacheminent jamais le worker et ne déclenchent aucun autre hook.

Voir aussi

• mastra.schedules : référence de l'API pour créer et gérer les planifications.
• Signaux : mécanisme de livraison utilisé par les planifications avec thread.
• Workflows planifiés : déclarer une planification cron dans une définition de Workflow.