Geplante Deployments

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

Den Kontext zur Einführung und Beispiele dafür, was Teams nach Zeitplänen ausführen, findest du im Blogbeitrag scheduled deployments and vaults in Claude Managed Agents.

Ein geplantes Deployment erstellen

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

• Deployments erfordern eine Agentenkonfiguration 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, eine user.message oder ein user.define_outcome, das die Arbeit jeder Session startet. In einer Deployment-Datei für ant apply wird der Text unterhalb des Frontmatters zu dieser user.message.
• Im schedule definierst du eine Cron-expression und eine timezone. Die feinste unterstützte Granularität liegt auf Minutenebene.

ant apply deployment.md

---
name: Weekly compliance scan
agent: agent_011CYm1BLqPXpQRk5khsSXrs
environment_id: env_01595EKxaaTTGwwY3kyXdtbs
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
---

Run the weekly compliance scan.

Die Antwort enthält ein Deployment-Objekt mit einem befüllten schedule.upcoming_runs_at, das die nächsten anstehenden Auslösezeitpunkte enthält, 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 spiegeln exakt den konfigurierten Zeitplan wider. Um die Last zu verteilen, wird bei der tatsächlichen Ausführung jedoch ein „jitter" (zufällige Verzögerung) 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. Wende dich an den Anthropic-Support, wenn du mehr benötigst.

Alle Parameter und das Antwortschema findest du in der Create Deployment-Referenz.

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").
• Sommerzeit (DST): Cron-Zeitpläne verwenden einen wörtlichen Abgleich mit der Ortszeit, 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 Struktur wie ein Session-Budget. Das Deployment kopiert die Obergrenze auf jede Session, die es startet, sodass das Budget jede Ausführung einzeln begrenzt, statt 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 Session mit Budget: 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=None entfernt und später erneut festgelegt werden.

Das folgende Beispiel legt ein Budget für ein bestehendes Deployment fest:

ant apply deployment.md

---
name: Weekly compliance scan
agent: agent_011CYm1BLqPXpQRk5khsSXrs
environment_id: env_01595EKxaaTTGwwY3kyXdtbs
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
budget:
  type: limit
  max_list_cost:
    amount: "2000"
    currency: USD
---

Run the weekly compliance scan.

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 Datensatz für einen „deployment run" (Deployment-Ausführung), sodass 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, beobachte die Session-Events über den Event-Stream oder über Webhooks. Änderungen am Deployment-Lebenszyklus und das Ergebnis jeder geplanten Ausführung werden ebenfalls als Webhook-Events zugestellt; sie sind in den Tabs „Deployment events" und „Deployment run events" unter Unterstützte Event-Typen aufgeführt.

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

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
):
    print(run.created_at, run.session_id or run.error.type)

Zusätzlich kannst du nach Deployment-Ausführungen mit Fehlern filtern:

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
    has_error=True,
):
    print(run.created_at, run.error.type, run.error.message)

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 List Deployment Runs-Referenz.

{
  "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 data.id.

Den Deployment-Lebenszyklus verwalten

Jede Änderung am 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".

Pausieren unterdrückt geplante Auslösungen ab sofort; laufende Sessions aus einer früheren Deployment-Ausführung werden weiter ausgeführt. Manuelle Ausführungen über den run-Endpunkt sind auch im pausierten Zustand weiterhin möglich. Das Pausieren setzt paused_reason auf {"type": "manual"}; das Fortsetzen entfernt diesen Wert wieder.

client.beta.deployments.pause(deployment.id)

Fortsetzen nimmt den Zeitplan ab dem nächsten geplanten Zeitpunkt wieder auf. Verpasste Auslösungen werden nicht nachgeholt.

client.beta.deployments.unpause(deployment.id)

Archivieren ist im Gegensatz zum Pausieren endgültig: Der Zeitplan wird beendet und das Deployment kann nicht mehr geändert werden.

client.beta.deployments.archive(deployment.id)

Verhalten bei Fehlern

Ratenlimit-Antworten bei der Session-Erstellung werden sofort als Ausführung mit session_rate_limited_error ohne erneuten Versuch erfasst; 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 wurde, wird das Deployment im selben Vorgang automatisch archiviert. Wenn der Agent gelöscht wurde, erkennt die nächste geplante Auslösung den fehlenden Agenten und archiviert das Deployment automatisch. In beiden Fällen wird keine Deployment-Ausführung erfasst. Wenn ein vom Agenten referenzierter Subagent archiviert wurde, erfasst die nächste Auslösung eine fehlgeschlagene Ausführung mit error.type: "agent_archived_error", und das Deployment wird automatisch pausiert, damit du den Agenten aktualisieren und fortsetzen kannst. Andere nicht behebbare Fehler bei der Session-Erstellung, etwa eine archivierte Umgebung oder ein archivierter Vault, verhalten sich genauso: Die Auslösung erfasst eine fehlgeschlagene Ausführung und das Deployment wird automatisch pausiert. Der paused_reason.error.type des Deployments entspricht dem error.type der fehlgeschlagenen Ausführung.

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.

run = client.beta.deployments.run(deployment.id)