Geplante Deployments

Ein „scheduled deployment“ (geplantes Deployment) ermöglicht es einem Agenten, Sessions autonom zu starten, sodass Aufgaben in einem vorhersehbaren Rhythmus erledigt werden können. Du erstellst und verwaltest Deployments mit der Deployments API, die Teil der Claude API ist.

Den Kontext zur Einführung sowie Beispiele dafür, was Teams nach Zeitplänen ausführen, findest du im Blogbeitrag Geplante Deployments und Vaults in Claude Managed Agents.

Ein geplantes Deployment erstellen

Beim Erstellen eines Deployments übergibst du zusätzlich zu einem schedule die für die Ausführung erforderlichen Session-Konfigurationen.

• Deployments erfordern eine Agenten-Konfiguration und eine Umgebungskonfiguration und akzeptieren optional Dateien, GitHub, Memory Stores und Vaults. Ein Deployment, das auf eine selbst gehostete Umgebung abzielt, kann Memory Stores anhängen; file- und github_repository-Ressourcen erfordern eine Cloud-Umgebung. Das Deployment-Formular in der Claude Console bietet derzeit keine Memory Stores für selbst gehostete Umgebungen an; hänge sie stattdessen über die API oder ein SDK an.
• Deployments erfordern außerdem mindestens ein initiales Event, ein user.message oder user.define_outcome, das die Arbeit jeder Session startet.
• Im schedule definierst du eine Cron-expression und eine timezone. Die maximal unterstützte Granularität liegt auf Minutenebene.

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
)

Die Antwort enthält ein Deployment-Objekt mit einem befüllten schedule.upcoming_runs_at mit den nächsten anstehenden Auslösezeitpunkten, um zu bestätigen, dass dein Zeitplan korrekt gesetzt wurde.

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

Die Zeitstempel der anstehenden Ausführungen spiegeln den exakt konfigurierten Zeitplan wider. Um die Last zu verteilen, wird bei der tatsächlichen Ausführung jedoch ein Jitter von bis zu 15 % des Intervalls zwischen den Ausführungen angewendet, mit einem Minimum von 5 Sekunden und einem Maximum von 9 Minuten.

Pro Organisation werden maximal 1.000 geplante Deployments unterstützt. Kontaktiere den Anthropic-Support, wenn du mehr benötigst.

Die vollständigen Parameter und das Antwortschema findest du in der Referenz zu Create Deployment.

Cron- und Zeitzonen-Semantik

• Expression: Standard-POSIX-Cron (minute hour day-of-month month day-of-week). Du kannst diese Cron-Ausdrücke in der Claude Console generieren und validieren.
• Timezone: IANA-Zeitzonenbezeichner (zum Beispiel "America/Los_Angeles").
• DST: Cron-Zeitpläne verwenden einen wörtlichen Abgleich mit der Ortszeit (Wall-Clock), sodass "0 20 * * *" in America/New_York um 20:00 Uhr Ortszeit ausgelöst wird, unabhängig davon, ob EST oder EDT gilt.

Ein Budget für jede Ausführung festlegen

Übergib das optionale budget-Objekt, wenn du das Deployment erstellst oder aktualisierst. Es hat dieselbe Form wie ein Session-Budget. Das Deployment kopiert die Obergrenze auf jede Session, die es startet, sodass das Budget jede Ausführung separat begrenzt, anstatt als kumulative Obergrenze über alle Ausführungen hinweg zu wirken: Ein Deployment mit einer Obergrenze von "2000" kann bei jeder Ausführung bis zu etwa 20 $ ausgeben.

Eine vom Deployment gestartete Session verhält sich genau wie jede andere budgetierte Session: Sie pausiert mit budget_reached, wenn ihre eigenen Listenkosten die Obergrenze erreichen. Eine Änderung des Deployment-Budgets gilt für danach gestartete Ausführungen; eine bereits laufende Session behält die Obergrenze, mit der sie gestartet wurde, die du über die Session selbst ändern kannst. Anders als ein Session-Budget kann das Budget eines Deployments mit "budget": null entfernt und später erneut gesetzt werden.

Das folgende Beispiel setzt ein Budget für ein bestehendes Deployment:

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

Deployment-Ausführungen

Deployments können aus verschiedenen Gründen nicht ausgelöst werden: zum Beispiel, wenn die environment-Ressource archiviert wurde oder wenn die Session-Erstellung durch ein Ratenlimit begrenzt wird. Jeder Versuch, ein Deployment auszuführen, erzeugt einen „deployment run“-Datensatz (Deployment-Ausführung), mit dem du Erfolge und Fehlschläge unabhängig vom Session-Lebenszyklus nachverfolgen kannst.

Erfolgreiche Deployments erzeugen aktive Sessions, und eine erfolgreiche Deployment-Ausführung enthält die zugehörige session_id. Um den Lebenszyklus einer Session zu verfolgen, verfolge die Session-Events über den Event-Stream oder Webhooks. Änderungen im Deployment-Lebenszyklus und das Ergebnis jeder geplanten Ausführung werden ebenfalls als Webhook-Events zugestellt, aufgeführt in den Tabs „Deployment events“ und „Deployment run events“ unter Unterstützte Event-Typen.

Liste alle Deployment-Ausführungen eines Deployments wie folgt auf:

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

Du kannst zusätzlich nach Deployment-Ausführungen mit Fehlern filtern:

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

Eine fehlgeschlagene Ausführung enthält einen error mit einem type, der beschreibt, warum die Session-Erstellung abgelehnt wurde (zum Beispiel environment_archived_error, agent_archived_error oder session_rate_limited_error). Alle Filterparameter und das Antwortschema findest du in der Referenz zu List Deployment Runs.

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

Um eine einzelne Ausführung anhand ihrer ID abzurufen, rufe GET /v1/deployment_runs/{deployment_run_id} auf. Ein deployment_run-Webhook-Event trägt die Ausführungs-ID als data.id.

Den Deployment-Lebenszyklus verwalten

Jede Änderung im Lebenszyklus löst ein Webhook-Event aus, sodass du ohne Polling auf ein pausiertes, fortgesetztes oder archiviertes Deployment reagieren kannst; siehe den Tab „Deployment events“.

Pause unterdrückt geplante Auslöser ab diesem Zeitpunkt; laufende Sessions aus einer vorherigen Deployment-Ausführung werden weiter ausgeführt. Manuelle Ausführungen über den run-Endpunkt sind im pausierten Zustand weiterhin erlaubt. Das Pausieren setzt paused_reason auf {"type": "manual"}; das Fortsetzen löscht es.

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

Unpause setzt den Zeitplan ab dem nächsten geplanten Termin fort. Verpasste Auslöser werden nicht nachgeholt.

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

Archive ist im Gegensatz zu Pause endgültig: Der Zeitplan endet und das Deployment kann nicht mehr geändert werden.

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

Verhalten bei Fehlern

Ratenlimit-Antworten bei der Session-Erstellung werden sofort und ohne Wiederholungsversuch als session_rate_limited_error-Ausführung aufgezeichnet; der Zeitplan versucht es beim nächsten geplanten Termin erneut. Ratenlimits bei zugrunde liegenden API-Aufrufen innerhalb einer Session werden von der Session selbst behandelt.

Wenn der Agent eines Deployments archiviert wurde, wird das Deployment im selben Vorgang automatisch archiviert. Wenn der Agent gelöscht wurde, erkennt der nächste geplante Auslöser den fehlenden Agenten und archiviert das Deployment automatisch. In beiden Fällen wird keine Deployment-Ausführung aufgezeichnet. Wenn ein vom Agenten referenzierter Subagent archiviert wurde, zeichnet der nächste Auslöser eine fehlgeschlagene Ausführung mit error.type: "agent_archived_error" auf, und das Deployment wird automatisch pausiert, damit du den Agenten aktualisieren und fortsetzen kannst. Andere nicht behebbare Fehler bei der Session-Erstellung, wie eine archivierte Umgebung oder ein archivierter Vault, verhalten sich genauso: Der Auslöser zeichnet eine fehlgeschlagene Ausführung auf und das Deployment wird automatisch pausiert. Das paused_reason.error.type des Deployments spiegelt das error.type der fehlgeschlagenen Ausführung wider.

Eine manuelle Ausführung auslösen

Um ein Deployment außerhalb seines Zeitplans auszuführen, rufe den run-Endpunkt auf. Dadurch wird sofort eine Session erstellt und eine Deployment-Ausführung mit trigger_context.type: "manual" geschrieben. So kannst du ein Deployment testen, bevor du dich auf den Zeitplan festlegst.

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