mastra.schedules

Ajouté dans : @mastra/core@1.50.0

mastra.schedules est le service CRUD des planifications cron persistantes. Utilisez-le pour créer, répertorier, mettre à jour, suspendre, reprendre, exécuter manuellement et supprimer les planifications des Agents ou des Workflows.

Pour découvrir les modèles d'utilisation et les concepts, consultez Schedules.

Exemple d'utilisation

Créez une planification d'Agent :

src/mastra/schedules.ts

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

Créez une planification de Workflow :

src/mastra/schedules.ts

const schedule = await mastra.schedules.create({
  workflowId: 'daily-report',
  cron: '0 9 * * *',
  inputData: { reportType: 'summary' },
})

Schedules nécessite un adaptateur de Storage qui implémente le domaine des planifications. Les adaptateurs pris en charge comprennent @mastra/libsql, @mastra/pg, @mastra/mysql, @mastra/mongodb, @mastra/convex et @mastra/spanner.

Méthodes

Création de planifications

create(input)

Crée une planification d'Agent ou de Workflow. Transmettez agentId pour créer une planification d'Agent, ou workflowId pour créer une planification de Workflow.

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

Entrée d'une planification d'Agent

id?:

string

Identifiant stable facultatif de la planification. La valeur est normalisée sous la forme agent_<slug>. Lorsqu'elle est omise, Mastra génère un identifiant agent_<uuid>.

agentId:

string

Identifiant de l'Agent à exécuter à chaque déclenchement de la planification.

cron:

string

Expression cron de la planification. Accepte les expressions cron en 5, 6 ou 7 parties ainsi que les alias Croner.

prompt:

string

Prompt envoyé à l'Agent à chaque déclenchement de la planification.

name?:

string

Libellé libre permettant de distinguer plusieurs planifications sur le même Agent ou fil de discussion.

timezone?:

string

Fuseau horaire IANA utilisé pour déterminer les heures de déclenchement cron, par exemple America/New_York.

threadId?:

string

Fil de discussion qui reçoit le signal planifié. Lorsqu'il est omis, chaque déclenchement s'exécute sans fil au moyen de agent.generate().

resourceId?:

string

Identifiant de ressource des planifications associées à un fil. Obligatoire lorsque threadId est défini.

signalType?:

AgentSignalType

Type de signal des déclenchements de planification associés à un fil. Utilise par défaut notification.

tagName?:

string

Nom de la balise XML utilisée pour afficher le signal planifié. Utilise par défaut schedule.

attributes?:

AgentSignalAttributes

Attributs affichés sur la balise XML du signal planifié.

providerOptions?:

Record<string, unknown>

Options du Provider compatibles JSON, fusionnées dans le payload du signal de planification à chaque déclenchement.

ifActive?:

ScheduleIfActive

Comportement lorsque le fil cible diffuse activement un flux. Nécessite threadId.

ifIdle?:

ScheduleIfIdle

Comportement lorsque le fil cible est inactif. Nécessite threadId.

metadata?:

Record<string, unknown>

Métadonnées arbitraires stockées avec la ligne de planification.

status?:

'active' | 'paused'

= 'active'

État initial du cycle de vie. Utilise par défaut active.

Entrée d'une planification de Workflow

id?:

string

Identifiant stable facultatif de la planification. La valeur est normalisée sous la forme schedule_<slug>. Lorsqu'elle est omise, Mastra génère un identifiant schedule_<uuid>.

workflowId:

string

Identifiant du Workflow à démarrer à chaque déclenchement de la planification.

cron:

string

Expression cron de la planification. Accepte les expressions cron en 5, 6 ou 7 parties ainsi que les alias Croner.

timezone?:

string

Fuseau horaire IANA utilisé pour déterminer les heures de déclenchement cron.

inputData?:

unknown

Données d'entrée transmises au Run du Workflow.

initialState?:

unknown

État initial du Workflow pour le Run planifié.

requestContext?:

Record<string, unknown>

Contexte de requête transmis au Run du Workflow.

metadata?:

Record<string, unknown>

Métadonnées arbitraires stockées avec la ligne de planification.

status?:

'active' | 'paused'

= 'active'

État initial du cycle de vie. Utilise par défaut active.

Lecture des planifications

get(id)

Récupère une planification à partir de son identifiant. Les identifiants bruts des planifications d'Agents sont également résolus sous la forme normalisée agent_<slug>.

const schedule = await mastra.schedules.get('pinger')

list(filter?)

Répertorie les planifications. Sans filtre, renvoie les planifications d'Agents et de Workflows.

const schedules = await mastra.schedules.list({
  agentId: 'pinger',
  status: 'active',
})

filter?:

ListSchedulesFilter

Filtres facultatifs de l'opération de listage.

ListSchedulesFilter

agentId?:

string

Renvoie uniquement les planifications de cet Agent.

workflowId?:

string

Renvoie uniquement les planifications de ce Workflow.

threadId?:

string

Renvoie uniquement les planifications d'Agents de ce fil de discussion.

resourceId?:

string

Renvoie uniquement les planifications d'Agents de cette ressource.

name?:

string

Renvoie uniquement les planifications d'Agents portant ce libellé.

status?:

'active' | 'paused'

Renvoie uniquement les planifications possédant cet état.

Mise à jour des planifications

update(id, patch)

Met à jour une planification. La modification de cron ou timezone recalcule la prochaine heure de déclenchement. Le passage de status de paused à active la recalcule également.

const updated = await mastra.schedules.update('pinger', {
  cron: '*/30 * * * *',
  prompt: 'Give me a status update every 30 minutes.',
})

Les patchs de planifications d'Agents peuvent mettre à jour cron, timezone, prompt, name, signalType, tagName, attributes, providerOptions, ifActive, ifIdle, metadata et status. threadId et resourceId ne peuvent pas être modifiés par patch. Créez une nouvelle planification lorsque le fil cible doit changer.

Les patchs de planifications de Workflows peuvent mettre à jour cron, timezone, inputData, initialState, requestContext, metadata et status. Les champs de patch propres aux Agents, tels que prompt, signalType et ifIdle, lèvent une erreur sur les planifications de Workflows.

Cycle de vie

pause(id)

Suspend une planification. La suspension est durable et idempotente.

const paused = await mastra.schedules.pause('pinger')

resume(id)

Reprend une planification suspendue et recalcule la prochaine heure de déclenchement à partir de l'heure actuelle.

const active = await mastra.schedules.resume('pinger')

run(id)

Déclenche immédiatement une planification une fois, sans modifier sa cadence cron.

const run = await mastra.schedules.run('pinger')

Pour les planifications d'Agents, claimId utilise manual_<scheduleId>_<timestamp>. Pour les planifications de Workflows, claimId utilise sched_<scheduleId>_<timestamp> et est réutilisé comme identifiant du Run du Workflow.

delete(id)

Supprime une planification. La suppression d'une planification inexistante ne fait rien.

await mastra.schedules.delete('pinger')

Comportement des planifications

• Les identifiants des planifications d'Agents utilisent le préfixe agent_. Ceux des planifications de Workflows créées au moyen de mastra.schedules.create() utilisent le préfixe schedule_.
• Les planifications d'Agents associées à un fil nécessitent resourceId lorsque threadId est défini.
• signalType, ifActive, ifIdle et resourceId nécessitent threadId.
• Les planifications de Workflows n'acceptent pas les champs de patch propres aux Agents, tels que prompt, signalType ou ifIdle.
• run() publie immédiatement un déclenchement manuel sans modifier la cadence cron stockée.