Déploiements planifiés

Un déploiement planifié permet à un agent de lancer des sessions de manière autonome, permettant l'accomplissement de tâches selon une cadence prévisible.



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 éventuellement des fichiers, GitHub, des magasins de mémoire et des coffres-forts.
• Les déploiements nécessitent également un événement user.message initial 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é avec les prochains horaires 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 prochaines exécutions sont basés sur la planification exacte configurée. Cependant, pour répartir la charge, les déploiements peuvent appliquer une gigue 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.



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 à 20h00 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, 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.

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 en outre filtrer sur 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 une 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).

{
  "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"
}



Gestion du cycle de vie du déploiement

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 à {"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 déclenchement suivant 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.



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"