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 deployment pianificati e vault in Claude Managed Agents sul blog.

Crea 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 ciascuna sessione.
• Nello 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 è 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 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 usano la corrispondenza letterale con l'orario 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.

Imposta 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 vincola 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: va 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": null e impostato nuovamente in seguito.

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

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

Esecuzioni del deployment

I deployment possono non 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), 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 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 del 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 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 riporta l'ID dell'esecuzione come 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, ripreso o archiviato senza polling; consulta la scheda Deployment events.

Pause sopprime le attivazioni pianificate da quel momento in avanti; le sessioni in esecuzione provenienti 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 ripresa lo azzera.

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

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

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à alla creazione della sessione vengono registrate immediatamente come 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, 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, la successiva attivazione registra un'esecuzione fallita con error.type: "agent_archived_error" e il deployment viene messo automaticamente in pausa in modo che tu possa aggiornare l'agente e riprendere. Altri errori irrecuperabili nella 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.

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

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