Geplante Deployments

Ein scheduled deployment (geplantes Deployment) ermöglicht es einem Agenten, Sessions autonom zu starten, wodurch die Erledigung von Aufgaben in einem vorhersehbaren Rhythmus ermöglicht wird. Du erstellst und verwaltest Deployments mit der Deployments API, einem Teil der Claude API.

Für den Launch-Kontext und Beispiele dafür, was Teams nach Zeitplänen ausführen, siehe geplante Deployments und Vaults in Claude Managed Agents im Blog.



Ein geplantes Deployment erstellen

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

• Deployments erfordern eine Agent-Konfiguration und eine Umgebungskonfiguration und akzeptieren optional Dateien, GitHub, Memory Stores und Vaults.
• 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 bevorstehenden 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 bevorstehenden 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.

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

Siehe die Create Deployment-Referenz für alle Parameter und das Antwortschema.



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 der lokalen Uhrzeit, sodass "0 20 * * *" in America/New_York um 20
  Uhr Ortszeit ausgelöst wird, unabhängig davon, ob EST oder EDT gilt.



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 einem Ratenlimit unterliegt. Jeder Versuch, ein Deployment auszuführen, erzeugt einen deployment run (Deployment-Ausführung)-Datensatz, 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 am Deployment-Lebenszyklus und das Ergebnis jeder geplanten Ausführung werden ebenfalls als Webhook-Events zugestellt, aufgelistet in den Tabs „Deployment events" und „Deployment run events" unter Unterstützte Event-Typen.

Liste alle Deployment-Ausführungen für ein Deployment 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). Siehe die List Deployment Runs-Referenz für alle Filterparameter und das Antwortschema.

{
  "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 enthält die Ausführungs-ID als seine data.id.



Verwaltung des Deployment-Lebenszyklus

Jede Lebenszyklusänderung löst ein Webhook-Event aus, sodass du auf ein pausiertes, fortgesetztes oder archiviertes Deployment reagieren kannst, ohne Polling zu betreiben; 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 während der Pause 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 wird beendet und das Deployment kann nicht mehr geändert werden.

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



Fehlerverhalten

Ratenlimit-Antworten bei der Session-Erstellung werden sofort als session_rate_limited_error-Ausführung ohne Wiederholung 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. Dies erstellt sofort eine Session und schreibt eine Deployment-Ausführung mit trigger_context.type: "manual". So kannst du ein Deployment testen, bevor du dich auf den Zeitplan festlegst.

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