Deployment pianificati

Uno "scheduled deployment" (deployment pianificato) consente a un agente di avviare sessioni in modo autonomo, permettendo il completamento di attività con una cadenza prevedibile. Crei e gestisci i deployment con la Deployments API, parte della Claude API.

Per il contesto del lancio ed esempi di ciò che i team eseguono secondo pianificazioni, consulta scheduled deployments and vaults in Claude Managed Agents sul blog.

Creare un deployment pianificato

Quando crei un deployment, passi le configurazioni di sessione necessarie per l'esecuzione, oltre a uno schedule.

• I deployment richiedono la configurazione dell'agente e la configurazione dell'ambiente, e accettano facoltativamente file, GitHub, memory store e vault. Un deployment che ha come destinazione un ambiente self-hosted può collegare memory store; le risorse file e github_repository richiedono un ambiente cloud. Il modulo di deployment della Claude Console attualmente non offre memory store per gli ambienti self-hosted; collegali invece tramite l'API o un SDK.
• I deployment richiedono inoltre almeno un evento iniziale, un user.message o un user.define_outcome, che avvia il lavoro di ogni sessione. In un file di deployment per ant apply, il testo sotto il frontmatter diventa quel user.message.
• Nello schedule, definisci una expression cron e un timezone. La granularità massima supportata è al livello del minuto.

ant apply deployment.md

---
name: Weekly compliance scan
agent: agent_011CYm1BLqPXpQRk5khsSXrs
environment_id: env_01595EKxaaTTGwwY3kyXdtbs
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
---

Run the weekly compliance scan.

La risposta include un oggetto deployment con un campo schedule.upcoming_runs_at popolato con i prossimi orari di attivazione, per confermare che la pianificazione sia stata impostata correttamente.

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

I timestamp delle prossime esecuzioni riflettono esattamente la pianificazione configurata. Tuttavia, per distribuire il carico, l'esecuzione effettiva applica un "jitter" (variazione casuale) fino al 15% dell'intervallo tra le esecuzioni, con un minimo di 5 secondi e un massimo di 9 minuti.

È supportato un massimo di 1.000 deployment pianificati per organizzazione. Contatta il supporto Anthropic se ne hai bisogno di più.

Consulta il riferimento Create Deployment per i parametri completi e lo schema della risposta.

Semantica di cron e fuso orario

• Espressione: cron POSIX standard (minute hour day-of-month month day-of-week). Puoi generare e convalidare queste espressioni cron nella Claude Console.
• Fuso orario: identificatore di fuso orario IANA (ad esempio, "America/Los_Angeles").
• Ora legale: le pianificazioni cron usano una corrispondenza letterale con l'ora locale, quindi "0 20 * * *" in America/New_York si attiva alle 20:00 ora locale indipendentemente dal fatto che sia in vigore EST o EDT.

Impostare un budget per ogni esecuzione

Passa l'oggetto facoltativo budget quando crei o aggiorni il deployment. Ha la stessa forma di un budget di sessione. Il deployment copia il limite su ogni sessione che avvia, quindi il budget limita ogni esecuzione separatamente anziché agire come tetto cumulativo tra le esecuzioni: un deployment con un limite di "2000" può spendere fino a circa $20 per ogni esecuzione.

Una sessione avviata dal deployment si comporta esattamente come qualsiasi altra sessione con budget: si mette in pausa con budget_reached quando il proprio costo di listino raggiunge il limite. La modifica del budget del deployment si applica alle esecuzioni avviate successivamente; una sessione già in esecuzione mantiene il limite con cui è stata avviata, che puoi modificare tramite la sessione stessa. A differenza di un budget di sessione, il budget di un deployment può essere rimosso con budget=None e reimpostato in seguito.

L'esempio seguente imposta un budget su un deployment esistente:

ant apply deployment.md

---
name: Weekly compliance scan
agent: agent_011CYm1BLqPXpQRk5khsSXrs
environment_id: env_01595EKxaaTTGwwY3kyXdtbs
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
budget:
  type: limit
  max_list_cost:
    amount: "2000"
    currency: USD
---

Run the weekly compliance scan.

Esecuzioni dei deployment

I deployment possono non attivarsi per diversi motivi: ad esempio, se la risorsa environment è stata archiviata, o se la creazione delle sessioni è soggetta a limite di velocità. Ogni tentativo di eseguire un deployment genera un record di "deployment run" (esecuzione del deployment), che ti consente di tracciare successi e fallimenti indipendentemente dal ciclo di vita della sessione.

I deployment riusciti generano sessioni attive, e un'esecuzione del deployment riuscita contiene il session_id associato. Per seguire il ciclo di vita di una sessione, traccia gli eventi della sessione tramite lo stream di eventi o i webhook. Anche le modifiche al ciclo di vita del deployment e l'esito di ogni esecuzione pianificata vengono recapitati come eventi webhook, elencati nelle schede Deployment events e Deployment run events di Tipi di eventi supportati.

Elenca tutte le esecuzioni di un deployment come segue:

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
):
    print(run.created_at, run.session_id or run.error.type)

Puoi inoltre filtrare le esecuzioni del deployment con errori:

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
    has_error=True,
):
    print(run.created_at, run.error.type, run.error.message)

Un'esecuzione fallita include un error con un type che descrive il motivo per cui la creazione della sessione è stata rifiutata (ad esempio, environment_archived_error, agent_archived_error o session_rate_limited_error). Consulta il riferimento List Deployment Runs per tutti i parametri di filtro e lo schema della risposta.

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

Per recuperare una singola esecuzione tramite ID, chiama GET /v1/deployment_runs/{deployment_run_id}. Un evento webhook deployment_run riporta l'ID dell'esecuzione come suo data.id.

Gestire il ciclo di vita del deployment

Ogni modifica del ciclo di vita emette un evento webhook, così puoi reagire a un deployment messo in pausa, riattivato o archiviato senza polling; consulta la scheda Deployment events.

Pausa sospende le attivazioni pianificate da quel momento in poi; le sessioni in esecuzione avviate da un'esecuzione precedente del deployment continuano a essere eseguite. Le esecuzioni manuali tramite l'endpoint run sono comunque consentite durante la pausa. La messa in pausa imposta paused_reason su {"type": "manual"}; la riattivazione lo cancella.

client.beta.deployments.pause(deployment.id)

Riattiva riprende la pianificazione dalla successiva occorrenza pianificata. Le attivazioni mancate non vengono recuperate.

client.beta.deployments.unpause(deployment.id)

Archivia, a differenza di pausa, è definitivo: la pianificazione termina e il deployment non può essere modificato.

client.beta.deployments.archive(deployment.id)

Comportamento in caso di errore

Le risposte di limite di velocità sulla creazione delle sessioni vengono registrate immediatamente come esecuzione session_rate_limited_error senza nuovi tentativi; la pianificazione riprova alla successiva occorrenza pianificata. I limiti di velocità sulle chiamate API sottostanti all'interno di una sessione sono gestiti dalla sessione stessa.

Se l'agente di un deployment è stato archiviato, il deployment viene archiviato automaticamente nella stessa operazione. Se l'agente è stato eliminato, la successiva attivazione pianificata rileva l'agente mancante e archivia automaticamente il deployment. In entrambi i casi non viene registrata alcuna esecuzione del deployment. Se un subagente referenziato dall'agente è stato archiviato, l'attivazione successiva registra un'esecuzione fallita con error.type: "agent_archived_error" e il deployment viene messo automaticamente in pausa, così puoi aggiornare l'agente e riprendere. Altri errori irrecuperabili di creazione della sessione, come un ambiente o un vault archiviato, si comportano allo stesso modo: l'attivazione registra un'esecuzione fallita e il deployment viene messo automaticamente in pausa. Il paused_reason.error.type del deployment rispecchia l'error.type dell'esecuzione fallita.

Avviare un'esecuzione manuale

Per eseguire un deployment al di fuori della sua pianificazione, chiama l'endpoint run. Questo crea immediatamente una sessione e scrive un'esecuzione del deployment con trigger_context.type: "manual". Ciò ti consente di testare un deployment prima di affidarti alla pianificazione.

run = client.beta.deployments.run(deployment.id)