Deployment pianificati

Un "scheduled deployment" (deployment pianificato) consente a un agente di avviare sessioni in modo autonomo, permettendo il completamento di attività con una cadenza prevedibile. Puoi creare e gestire i deployment con la Deployments API, parte dell'API di Claude.



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 opzionalmente file, GitHub, memory store e vault.
• I deployment richiedono inoltre un evento iniziale user.message che avvia il lavoro della sessione.
• Nello schedule, definisci una expression cron e una timezone. La granularità massima supportata è a livello di minuto.

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 si basano sulla pianificazione esatta configurata. Tuttavia, per distribuire il carico, i deployment possono applicare un jitter fino a 10 secondi.

È 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 utilizzano la corrispondenza letterale dell'ora 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 del 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 del deployment riuscita contiene il session_id associato. Per seguire il ciclo di vita di una sessione, traccia gli eventi della sessione tramite l'event stream o i webhook. Le modifiche al ciclo di vita del deployment e l'esito di ogni esecuzione pianificata vengono inoltre 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:

Puoi inoltre filtrare le esecuzioni del deployment con errori:

Un'esecuzione fallita include un error con un type che descrive perché 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 trasporta l'ID dell'esecuzione come suo data.id.



Gestione del ciclo di vita del deployment

Ogni modifica al 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.

Pause (pausa) sopprime le attivazioni pianificate da quel momento in poi; le sessioni in esecuzione da un'esecuzione del deployment precedente continuano a essere eseguite. Le esecuzioni manuali tramite l'endpoint run sono comunque consentite mentre il deployment è in pausa. Mettere in pausa imposta paused_reason su {"type": "manual"}; riattivare lo cancella.

Unpause (riattivazione) riprende la pianificazione dalla prossima occorrenza pianificata. Le attivazioni mancate non vengono recuperate retroattivamente.

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



Comportamento in caso di errore

Le risposte di limite di velocità sulla 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 sono gestiti dalla sessione stessa.

Se l'agente di un deployment è stato archiviato o eliminato, il deployment viene automaticamente archiviato nella stessa operazione; non viene registrata alcuna esecuzione del deployment. Se un subagente referenziato dall'agente è stato archiviato, la successiva attivazione 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 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 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". Ciò ti consente di testare un deployment prima di impegnarti con la pianificazione.