Deployment pianificati

Un scheduled deployment (deployment pianificato) consente a un agente di avviare sessioni in modo autonomo, permettendo il completamento delle attività con una cadenza prevedibile. Crea 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 su 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 una schedule.

• I deployment richiedono la configurazione dell'agente e la configurazione dell'ambiente, e accettano opzionalmente file, GitHub, memory store e vault.
• I deployment richiedono inoltre almeno un evento iniziale, un user.message o user.define_outcome, che avvia il lavoro di ogni sessione.
• Nella schedule, definisci una expression cron e una timezone. La granularità massima supportata è a livello di minuto.

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 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 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 timezone

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



Esecuzioni dei deployment

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

I deployment riusciti generano sessioni attive, e un'esecuzione di 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 consegnati 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:

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

Puoi inoltre filtrare le esecuzioni dei deployment con errori:

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

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 contiene l'ID dell'esecuzione come suo data.id.



Gestione del ciclo di vita del deployment

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

Pause sopprime i trigger pianificati da quel momento in poi; le sessioni in esecuzione da un'esecuzione di deployment precedente continuano a essere eseguite. Le esecuzioni manuali tramite l'endpoint run sono ancora consentite durante la pausa. La messa in pausa imposta paused_reason su {"type": "manual"}; la riattivazione lo cancella.

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

Unpause riprende la pianificazione dalla prossima occorrenza pianificata. I trigger mancati non vengono recuperati.

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

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

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



Comportamento in caso di errore

Le risposte di limite di velocità nella creazione della sessione vengono registrate immediatamente come un'esecuzione session_rate_limited_error senza nuovi tentativi; la pianificazione riprova alla prossima occorrenza pianificata. I limiti di velocità sulle chiamate API sottostanti all'interno di una sessione vengono 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, il prossimo trigger pianificato 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, il prossimo trigger registra un'esecuzione fallita con error.type: "agent_archived_error" e il deployment viene automaticamente messo in pausa così puoi aggiornare l'agente e riprendere. Altri errori irrecuperabili nella creazione della sessione, come un ambiente o un vault archiviato, si comportano allo stesso modo: il trigger registra un'esecuzione fallita e il deployment viene automaticamente messo in pausa. Il paused_reason.error.type del deployment rispecchia l'error.type dell'esecuzione fallita.



Attivare 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". Questo ti consente di testare un deployment prima di impegnarti con la pianificazione.

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