Déploiements planifiés

Un déploiement planifié permet à un agent de démarrer des sessions de manière autonome, permettant l'accomplissement de tâches selon une cadence prévisible. Vous créez et gérez les déploiements avec l'API Deployments, qui fait partie de l'API Claude.



Créer un déploiement planifié

Lors de la création d'un déploiement, vous transmettez les configurations de session requises pour l'exécution, en plus d'un schedule.

• Les déploiements nécessitent une configuration d'agent et une configuration d'environnement, et acceptent facultativement des fichiers, GitHub, des magasins de mémoire et des coffres-forts.
• Les déploiements nécessitent également un événement initial user.message qui démarre le travail de la session.
• Dans le schedule, vous définissez une expression cron et un timezone. La granularité maximale prise en charge est au niveau de la minute.

DEPLOYMENT_ID=$(ant beta:deployments create <<YAML | jq -er '.id'
name: Weekly compliance scan
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
  - type: user.message
    content:
      - type: text
        text: Run the weekly compliance scan.
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
YAML
)

La réponse inclut un objet de déploiement avec un champ schedule.upcoming_runs_at renseigné contenant les prochaines heures de déclenchement, afin de confirmer que votre planification a été correctement définie.

{
  "id": "depl_01xyz",
  "status": "active",
  "paused_reason": null,
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York",
    "last_run_at": null,
    "upcoming_runs_at": [
      "2026-05-09T00:00:00Z",
      "2026-05-16T00:00:00Z",
      "2026-05-23T00:00:00Z"
    ]
  }
}

Les horodatages des exécutions à venir sont basés sur la planification exacte configurée. Cependant, pour répartir la charge, les déploiements peuvent appliquer une variation aléatoire (jitter) allant jusqu'à 10 secondes.

Un maximum de 1 000 déploiements planifiés est pris en charge par organisation. Contactez le support Anthropic si vous en avez besoin de davantage.

Consultez la référence Create Deployment pour obtenir la liste complète des paramètres et le schéma de réponse.



Sémantique cron et fuseau horaire

• Expression : Cron POSIX standard (minute hour day-of-month month day-of-week). Vous pouvez générer et valider ces expressions cron dans la Claude Console.
• Fuseau horaire : Identifiant de fuseau horaire IANA (par exemple, "America/Los_Angeles").
• Heure d'été : Les planifications cron utilisent une correspondance littérale avec l'heure locale, donc "0 20 * * *" dans America/New_York se déclenche à 20 h 00 heure locale, que l'heure EST ou EDT soit en vigueur.



Exécutions de déploiement

Les déploiements peuvent échouer à se déclencher pour diverses raisons : par exemple, si la ressource environment a été archivée, ou si la création de session est soumise à une limite de débit. Chaque tentative d'exécution d'un déploiement génère un enregistrement d'exécution de déploiement (deployment run), vous permettant de suivre les succès et les échecs indépendamment du cycle de vie de la session.

Les déploiements réussis génèrent des sessions actives, et une exécution de déploiement réussie contient le session_id associé. Pour suivre le cycle de vie d'une session, suivez les événements de session via le flux d'événements ou les webhooks. Les changements de cycle de vie du déploiement et le résultat de chaque exécution planifiée sont également transmis sous forme d'événements webhook, répertoriés dans les onglets Deployment events et Deployment run events de la section Types d'événements pris en charge.

Listez toutes les exécutions de déploiement pour un déploiement comme suit :

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID"

Vous pouvez également filtrer les exécutions de déploiement comportant des erreurs :

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID" --has-error

Une exécution échouée inclut un error avec un type décrivant pourquoi la création de session a été rejetée (par exemple, environment_archived_error, agent_archived_error ou session_rate_limited_error). Consultez la référence List Deployment Runs pour tous les paramètres de filtre et le schéma de réponse.

{
  "type": "deployment_run",
  "id": "drun_01abc124",
  "deployment_id": "depl_01xyz",
  "trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
  "session_id": null,
  "error": {
    "type": "environment_archived_error",
    "message": "environment `env_01abc` is archived"
  },
  "agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 },
  "created_at": "2026-05-09T00:00:01Z"
}

Pour récupérer une seule exécution par ID, appelez GET /v1/deployment_runs/{deployment_run_id}. Un événement webhook deployment_run transporte l'ID de l'exécution dans son champ data.id.



Gestion du cycle de vie du déploiement

Chaque changement de cycle de vie émet un événement webhook, afin que vous puissiez réagir à un déploiement mis en pause, repris ou archivé sans avoir à interroger l'API ; consultez l'onglet Deployment events.

Pause supprime les déclenchements planifiés à partir de ce moment ; les sessions en cours issues d'une exécution de déploiement antérieure continuent de s'exécuter. Les exécutions manuelles via le point de terminaison run restent autorisées pendant la pause. La mise en pause définit paused_reason sur {"type": "manual"} ; la reprise l'efface.

ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"

Unpause reprend la planification à partir de la prochaine occurrence planifiée. Les déclenchements manqués ne sont pas rattrapés.

ant beta:deployments unpause --deployment-id "$DEPLOYMENT_ID"

Archive, contrairement à pause, est définitif : la planification se termine et le déploiement ne peut plus être modifié.

ant beta:deployments archive --deployment-id "$DEPLOYMENT_ID"



Comportement en cas d'échec

Les réponses de limite de débit lors de la création de session sont enregistrées immédiatement comme une exécution session_rate_limited_error sans nouvelle tentative ; la planification réessaie à la prochaine occurrence planifiée. Les limites de débit sur les appels API sous-jacents au sein d'une session sont gérées par la session elle-même.

Si l'agent d'un déploiement a été archivé ou supprimé, le déploiement est automatiquement archivé dans la même opération ; aucune exécution de déploiement n'est enregistrée. Si un sous-agent référencé par l'agent a été archivé, le prochain déclenchement enregistre une exécution échouée avec error.type: "agent_archived_error" et le déploiement est automatiquement mis en pause afin que vous puissiez mettre à jour l'agent et reprendre. Les autres erreurs irrécupérables de création de session, telles qu'un environnement ou un coffre-fort archivé, se comportent de la même manière : le déclenchement enregistre une exécution échouée et le déploiement est automatiquement mis en pause. Le paused_reason.error.type du déploiement reflète le error.type de l'exécution échouée.



Déclencher une exécution manuelle

Pour exécuter un déploiement en dehors de sa planification, appelez le point de terminaison run. Cela crée immédiatement une session et écrit une exécution de déploiement avec trigger_context.type: "manual". Cela vous permet de tester un déploiement avant de vous engager sur la planification.

ant beta:deployments run --deployment-id "$DEPLOYMENT_ID"