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

# `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](https://mastra.zisheng.pro/fr/docs/long-running-agents/schedules).

## Exemple d'utilisation

Créez une planification d'Agent :

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

Créez une planification de Workflow :

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

```typescript
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'`): État initial du cycle de vie. Utilise par défaut active. (Default: `'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'`): État initial du cycle de vie. Utilise par défaut active. (Default: `'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>`.

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

#### `list(filter?)`

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

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

**filter** (`ListSchedulesFilter`): Filtres facultatifs de l'opération de listage.

**filter.agentId** (`string`): Renvoie uniquement les planifications de cet Agent.

**filter.workflowId** (`string`): Renvoie uniquement les planifications de ce Workflow.

**filter.threadId** (`string`): Renvoie uniquement les planifications d'Agents de ce fil de discussion.

**filter.resourceId** (`string`): Renvoie uniquement les planifications d'Agents de cette ressource.

**filter.name** (`string`): Renvoie uniquement les planifications d'Agents portant ce libellé.

**filter.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.

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

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

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

#### `run(id)`

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

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

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