Déploiements planifiés

Un « scheduled deployment » (déploiement planifié) permet à un agent de démarrer des sessions de manière autonome, ce qui permet d'accomplir des 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.

Pour connaître le contexte de lancement et des exemples de ce que les équipes exécutent selon des planifications, consultez l'article déploiements planifiés et coffres-forts dans Claude Managed Agents sur le blog.

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 en option des fichiers, GitHub, des magasins de mémoire et des coffres-forts. Un déploiement qui cible un environnement auto-hébergé peut attacher des magasins de mémoire ; les ressources file et github_repository nécessitent un environnement cloud. Le formulaire de déploiement de la Claude Console ne propose pas actuellement de magasins de mémoire pour les environnements auto-hébergés ; attachez-les plutôt via l'API ou un SDK.
• Les déploiements nécessitent également au moins un événement initial, un user.message ou un user.define_outcome, qui lance le travail de chaque session.
• Dans le schedule, vous définissez une expression cron et un timezone. La granularité maximale prise en charge est à 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 dont le champ schedule.upcoming_runs_at est renseigné avec 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 prochaines exécutions reflètent exactement la planification configurée. Cependant, afin de répartir la charge, l'exécution réelle applique une gigue (jitter) pouvant atteindre 15 % de l'intervalle entre les exécutions, avec un minimum de 5 secondes et un maximum de 9 minutes.

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

Consultez la référence Create Deployment pour l'ensemble des paramètres et le schéma de réponse.

Sémantique du cron et des fuseaux horaires

• 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é (DST) : les planifications cron utilisent une correspondance littérale avec l'heure locale affichée, de sorte que "0 20 * * *" dans America/New_York se déclenche à 20 h 00 heure locale, que l'heure EST ou EDT soit en vigueur.

Définir un budget pour chaque exécution

Transmettez l'objet facultatif budget lorsque vous créez ou mettez à jour le déploiement. Il a la même forme qu'un budget de session. Le déploiement copie le plafond sur chaque session qu'il démarre, de sorte que le budget limite chaque exécution séparément plutôt que d'agir comme un plafond cumulatif sur l'ensemble des exécutions : un déploiement avec un plafond de "2000" peut dépenser jusqu'à environ 20 $ à chaque exécution.

Une session démarrée par le déploiement se comporte exactement comme n'importe quelle autre session budgétée : elle se met en pause avec budget_reached lorsque son propre coût au tarif public atteint le plafond. La modification du budget du déploiement s'applique aux exécutions démarrées par la suite ; une session déjà en cours conserve le plafond avec lequel elle a démarré, que vous pouvez modifier via la session elle-même. Contrairement à un budget de session, le budget d'un déploiement peut être supprimé avec "budget": null puis redéfini ultérieurement.

L'exemple suivant définit un budget sur un déploiement existant :

curl --fail-with-body -sS "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2000", "currency": "USD"}
  }
}
EOF

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 de « deployment run » (exécution de déploiement), ce qui vous permet de suivre les réussites et les échecs indépendamment du cycle de vie des sessions.

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 des déploiements 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 d'un déploiement comme suit :

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

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

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

Une exécution en échec inclut un error avec un type décrivant la raison pour laquelle 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 filtrage 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 exécution unique par son 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.

Gérer le cycle de vie des déploiements

Chaque changement de cycle de vie émet un événement webhook, ce qui vous permet de réagir à un déploiement mis en pause, réactivé ou archivé sans interrogation périodique ; 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 réactivation l'efface.

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

Unpause (réactivation) 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 (archivage), contrairement à pause, est définitif : la planification prend fin 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 immédiatement enregistrées 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é, le déploiement est automatiquement archivé au cours de la même opération. Si l'agent a été supprimé, le prochain déclenchement planifié détecte l'agent manquant et archive automatiquement le déploiement. Dans les deux cas, 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 en échec 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, comme un environnement ou un coffre-fort archivé, se comportent de la même manière : le déclenchement enregistre une exécution en échec et le déploiement est automatiquement mis en pause. Le champ paused_reason.error.type du déploiement reflète le error.type de l'exécution en échec.

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"