Geplante Deployments

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



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 Agenten-Konfiguration und eine Umgebungskonfiguration und akzeptieren optional Dateien, GitHub, Memory Stores und Vaults.
• Deployments erfordern außerdem ein initiales user.message-Event, das die Arbeit der 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 ausgefüllten schedule.upcoming_runs_at mit den nächsten anstehenden Auslösezeitpunkten, damit du bestätigen kannst, dass dein Zeitplan korrekt eingerichtet 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 basieren auf dem exakt konfigurierten Zeitplan. Um die Last zu verteilen, können Deployments jedoch einen Jitter von bis zu 10 Sekunden anwenden.

Pro Organisation werden maximal 1.000 geplante Deployments 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 (Sommerzeit): Cron-Zeitpläne verwenden wörtliches Wall-Clock-Matching, sodass "0 20 * * *" in America/New_York um 20
  Uhr Ortszeit ausgelöst wird, unabhängig davon, ob EST oder EDT gilt.



Deployment Runs

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 eingeschränkt ist. Jeder Versuch, ein Deployment auszuführen, erzeugt einen deployment run-Datensatz (Deployment-Ausführung), sodass du Erfolge und Fehler unabhängig vom Session-Lebenszyklus nachverfolgen kannst.

Erfolgreiche Deployments erzeugen aktive Sessions, und ein erfolgreicher Deployment Run 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 Runs für ein Deployment wie folgt auf:

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

Du kannst zusätzlich nach Deployment Runs mit Fehlern filtern:

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

Ein fehlgeschlagener Run 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 einen einzelnen Run anhand der ID abzurufen, rufe GET /v1/deployment_runs/{deployment_run_id} auf. Ein deployment_run-Webhook-Event trägt die Run-ID als data.id.



Deployment-Lebenszyklus verwalten

Jede Lebenszyklusänderung löst ein Webhook-Event aus, sodass du auf ein pausiertes, fortgesetztes oder archiviertes Deployment reagieren kannst, ohne zu pollen; siehe den Tab „Deployment events".

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

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

Unpause setzt den Zeitplan ab dem nächsten geplanten Zeitpunkt 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-Run ohne Wiederholungsversuch aufgezeichnet; der Zeitplan versucht es beim nächsten geplanten Zeitpunkt erneut. Ratenlimits bei zugrunde liegenden API-Aufrufen innerhalb einer Session werden von der Session selbst behandelt.

Wenn der Agent eines Deployments archiviert oder gelöscht wurde, wird das Deployment im selben Vorgang automatisch archiviert; es wird kein Deployment Run aufgezeichnet. Wenn ein vom Agenten referenzierter Subagent archiviert wurde, zeichnet der nächste Auslöser einen fehlgeschlagenen Run 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 einen fehlgeschlagenen Run auf und das Deployment wird automatisch pausiert. Der paused_reason.error.type des Deployments spiegelt den error.type des fehlgeschlagenen Runs wider.



Einen manuellen Run auslösen

Um ein Deployment außerhalb seines Zeitplans auszuführen, rufe den run-Endpunkt auf. Dies erstellt sofort eine Session und schreibt einen Deployment Run 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"