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.

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 befüllten schedule.upcoming_runs_at mit den nächsten anstehenden Auslösezeitpunkten, um zu bestätigen, 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.

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

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-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 begrenzt ist. Jeder Versuch, ein Deployment auszuführen, erzeugt einen deployment run (Deployment-Ausführungsdatensatz), mit dem du Erfolge und Fehlschläge unabhängig vom Session-Lebenszyklus verfolgen 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.

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).

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

Verwaltung des Deployment-Lebenszyklus

Pause unterdrückt geplante Auslösungen ab diesem Zeitpunkt; laufende Sessions aus einem früheren Deployment-Run werden weiterhin ausgeführt. Manuelle Runs über den run-Endpunkt sind während der Pause weiterhin erlaubt. Das Pausieren setzt paused_reason auf {"type": "manual"}; das Aufheben der Pause löscht diesen Wert.

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

Unpause setzt den Zeitplan ab dem nächsten geplanten Termin fort. Verpasste Auslösungen 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 Termin 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 die nächste Auslösung einen fehlgeschlagenen Run mit error.type: "agent_archived_error" auf und das Deployment wird automatisch pausiert, damit du den Agenten aktualisieren und fortsetzen kannst.

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"