> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # 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](https://mastra.zisheng.pro/fr/docs/long-running-agents/signals) dans un thread, soit comme exécution [`agent.generate()`](https://mastra.zisheng.pro/fr/reference/agents/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`](https://mastra.zisheng.pro/fr/reference/schedules/overview), 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](https://mastra.zisheng.pro/fr/docs/workflows/scheduled-workflows) ; transmettez `workflowId` à la place de `agentId` pour planifier un Workflow. > **Remarque:** Les planifications nécessitent un adaptateur de [stockage](https://mastra.zisheng.pro/fr/docs/storage/overview) qui implémente le domaine des planifications. Consultez la [référence de `mastra.schedules`](https://mastra.zisheng.pro/fr/reference/schedules/overview) 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. ```typescript 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 : ```typescript // 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`](https://www.npmjs.com/package/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](https://mastra.zisheng.pro/fr/docs/long-running-agents/signals) 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`. ```typescript 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()`](https://mastra.zisheng.pro/fr/docs/long-running-agents/signals) 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](https://mastra.zisheng.pro/fr/reference/schedules/overview). ```typescript 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 … 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. ```typescript 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`](https://mastra.zisheng.pro/fr/reference/schedules/overview). ### 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 : ```typescript 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](https://mastra.zisheng.pro/fr/docs/workflows/scheduled-workflows) 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. ```typescript 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)`](https://mastra.zisheng.pro/fr/reference/schedules/overview) 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](https://mastra.zisheng.pro/fr/reference/client-js/agents) 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. ```typescript 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`](https://mastra.zisheng.pro/fr/reference/schedules/overview) : référence de l'API pour créer et gérer les planifications. - [Signaux](https://mastra.zisheng.pro/fr/docs/long-running-agents/signals) : mécanisme de livraison utilisé par les planifications avec thread. - [Workflows planifiés](https://mastra.zisheng.pro/fr/docs/workflows/scheduled-workflows) : déclarer une planification cron dans une définition de Workflow.