Deployment pianificati

Un deployment pianificato consente a un agente di avviare sessioni in modo autonomo, permettendo il completamento delle attività con una cadenza prevedibile.

Crea un deployment pianificato

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

• I deployment richiedono la configurazione dell'agente e la configurazione dell'ambiente, e accettano facoltativamente file, GitHub, memory store e vault.
• I deployment richiedono anche un evento iniziale user.message che avvia il lavoro della sessione.
• Nella 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 tua 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ù.

Semantica di cron e fuso orario

• 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'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 una varietà di 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 esecuzione del deployment (deployment run), 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 attraverso il flusso di eventi o i webhook.

Elenca tutte le esecuzioni di un deployment come segue:

Puoi inoltre filtrare le esecuzioni dei 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).

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

Gestione del ciclo di vita del deployment

Pause sopprime le attivazioni pianificate 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.

Unpause riprende la pianificazione dalla prossima occorrenza pianificata. Le attivazioni mancate non vengono recuperate.

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

Comportamento in caso di fallimento

Le risposte di limite di velocità nella creazione delle sessioni 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 archiviato automaticamente nella stessa operazione; non viene registrata alcuna esecuzione del deployment. Se un subagente referenziato dall'agente è stato archiviato, la prossima attivazione registra un'esecuzione fallita con error.type: "agent_archived_error" e il deployment viene automaticamente messo in pausa in modo che tu possa aggiornare l'agente e riprendere.

Attiva 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.