---
title: Geplante Deployments
url: https://platform.claude.com/docs/de/managed-agents/scheduled-deployments
description: "Erstelle und verwalte Deployments mit der Claude API: Führe einen Agenten nach einem wiederkehrenden Cron-Zeitplan aus und prüfe seinen Ausführungsverlauf."
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

Ein **„scheduled deployment" (geplantes Deployment)** ermöglicht es einem [Agenten](https://platform.claude.com/docs/de/managed-agents/agent-setup), [Sessions](https://platform.claude.com/docs/de/managed-agents/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](https://claude.com/blog/whats-new-in-claude-managed-agents).

## Ein geplantes Deployment erstellen

Beim Erstellen eines Deployments übergibst du die für die Ausführung erforderlichen [Session-Konfigurationen](https://platform.claude.com/docs/de/managed-agents/sessions) sowie einen `schedule` (csharp, go: `Schedule`).

* Deployments erfordern eine [Agentenkonfiguration](https://platform.claude.com/docs/de/managed-agents/agent-setup) und eine [Umgebungskonfiguration](https://platform.claude.com/docs/de/managed-agents/environments) und akzeptieren optional [Dateien](https://platform.claude.com/docs/de/managed-agents/files), [GitHub](https://platform.claude.com/docs/de/managed-agents/github), [Memory Stores](https://platform.claude.com/docs/de/managed-agents/memory) und [Vaults](https://platform.claude.com/docs/de/managed-agents/vaults). Ein Deployment, das auf eine [selbst gehostete Umgebung](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory) 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` (csharp, go: `Schedule`) definierst du eine Cron-`expression` (csharp, go: `Expression`) und eine `timezone` (csharp, go: `Timezone`). Die feinste unterstützte Granularität liegt auf Minutenebene.

<Note>
  Auf [Claude Platform on AWS](https://platform.claude.com/docs/de/build-with-claude/claude-platform-on-aws) erstellt jede Ausführung ihre Session als IAM-Rolle in deinem AWS-Konto. Bevor du das Deployment erstellst, setze `execution_identity` auf dem Agenten auf `{"type": "aws_role", "role_arn": "arn:aws:iam::123456789012:role/example-role"}`. Das Erstellen eines Deployments für einen Agenten ohne dieses Feld gibt einen 400-Fehler zurück.

  * **Vertrauensrichtlinie:** Erlaube dem Service-Principal `aws-external-anthropic.amazonaws.com`, `sts:AssumeRole` und `sts:SetSourceIdentity` aufzurufen.
  * **Rollenberechtigungen:** Erlaube `aws-external-anthropic:CreateSession`, `sts:GetWebIdentityToken` und `sts:TagGetWebIdentityToken`.
  * **Aufruferberechtigungen:** Der IAM-Principal, der die Rolle auf dem Agenten setzt, benötigt `iam:PassRole` für diese Rolle. Die Rolle muss sich im selben AWS-Konto befinden. Keine [verwaltete Richtlinie](https://platform.claude.com/docs/de/api/claude-platform-on-aws-iam-actions#managed-policies) gewährt `iam:PassRole`.
</Note>

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/deployments?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 '{
      "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"
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply deployment.md
    ```

    <File filename="deployment.md">
      ```markdown
      ---
      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.
      ```
    </File>

    [`ant apply`](https://platform.claude.com/docs/de/cli-sdks-libraries/cli/apply) gibt die ID des neuen Deployments aus und speichert sie in `claude-lock.json`. Um das Deployment-Objekt anzuzeigen, führe `ant beta:deployments retrieve` aus.
  </CodeGroupItem>

  ```python Python
  deployment = client.beta.deployments.create(
      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",
      },
  )
  ```

  ```typescript TypeScript
  const deployment = await client.beta.deployments.create({
    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"
    }
  });
  ```

  ```csharp C#
  var deployment = await client.Beta.Deployments.Create(new()
  {
      Name = "Weekly compliance scan",
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      InitialEvents =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "Run the weekly compliance scan.",
                  },
              ],
          },
      ],
      Schedule = new BetaManagedAgentsScheduleParams
      {
          Type = BetaManagedAgentsScheduleParamsType.Cron,
          Expression = "0 20 * * 5",
          Timezone = "America/New_York",
      },
  });
  ```

  ```go Go
  deployment, err := client.Beta.Deployments.New(ctx, anthropic.BetaDeploymentNewParams{
  	Name:          "Weekly compliance scan",
  	Agent:         anthropic.BetaDeploymentNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
  	EnvironmentID: environment.ID,
  	InitialEvents: []anthropic.BetaManagedAgentsDeploymentInitialEventParamsUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "Run the weekly compliance scan.",
  				},
  			}},
  		},
  	}},
  	Schedule: anthropic.BetaManagedAgentsScheduleParams{
  		Type:       anthropic.BetaManagedAgentsScheduleParamsTypeCron,
  		Expression: "0 20 * * 5",
  		Timezone:   "America/New_York",
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var deployment = client.beta().deployments().create(
      DeploymentCreateParams.builder()
          .name("Weekly compliance scan")
          .agent(agent.id())
          .environmentId(environment.id())
          .addInitialEvent(
              BetaManagedAgentsUserMessageEventParams.builder()
                  .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
                  .addTextContent("Run the weekly compliance scan.")
                  .build()
          )
          .schedule(
              BetaManagedAgentsScheduleParams.builder()
                  .type(BetaManagedAgentsScheduleParams.Type.CRON)
                  .expression("0 20 * * 5")
                  .timezone("America/New_York")
                  .build()
          )
          .build()
  );
  ```

  ```php PHP
  $deployment = $client->beta->deployments->create(
      name: 'Weekly compliance scan',
      agent: $agent->id,
      environmentID: $environment->id,
      initialEvents: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'Run the weekly compliance scan.']],
          ],
      ],
      schedule: [
          'type' => 'cron',
          'expression' => '0 20 * * 5',
          'timezone' => 'America/New_York',
      ],
  );
  ```

  ```ruby Ruby
  deployment = client.beta.deployments.create(
    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"
    }
  )
  ```
</CodeGroup>

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.

```json
{
  "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](https://platform.claude.com/docs/de/api/beta/deployments/create).

### 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](https://platform.claude.com/workspaces/default/deployments) 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.

<Note>
  Ortszeiten, die am Tag der Umstellung auf Sommerzeit nicht existieren (etwa 2 Uhr morgens), werden nicht ausgelöst. Ortszeiten, die am Tag der Rückstellung auf Winterzeit zweimal vorkommen, werden zweimal ausgelöst. Plane außerhalb des Zeitfensters von 1–3 Uhr Ortszeit oder verwende UTC, wenn ausgelassene oder doppelte Ausführungen nicht akzeptabel sind.
</Note>

### Ein Budget für jede Ausführung festlegen

Übergib das optionale `budget` (csharp, go: `Budget`)-Objekt, wenn du das Deployment erstellst oder aktualisierst. Es hat dieselbe Struktur wie ein [Session-Budget](https://platform.claude.com/docs/de/managed-agents/budgets). 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](https://platform.claude.com/docs/de/managed-agents/budgets#when-a-session-reaches-its-budget). 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](https://platform.claude.com/docs/de/managed-agents/session-operations#updating-the-session-budget) kannst. Anders als ein Session-Budget kann das Budget eines Deployments mit `"budget": null` (python: `budget=None`; typescript: `budget: null`; ruby: `budget: nil`; go: `Budget: param.NullStruct[anthropic.BetaManagedAgentsBudgetLimitParam]()`; java: `.budget(Optional.empty())`; csharp: `Budget = null`; php: `requestOptions: ['extraBodyParams' => ['budget' => null]]`; cli: `--budget null`) entfernt und später erneut festgelegt werden.

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

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  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 '{
      "budget": {
        "type": "limit",
        "max_list_cost": {"amount": "2000", "currency": "USD"}
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply deployment.md
    ```

    <File filename="deployment.md">
      ```markdown
      ---
      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.
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  updated_deployment = client.beta.deployments.update(
      deployment.id,
      budget={
          "type": "limit",
          "max_list_cost": {"amount": "2000", "currency": "USD"},
      },
  )
  print(updated_deployment.budget.max_list_cost.amount)  # 2000
  ```

  ```typescript TypeScript
  const updatedDeployment = await client.beta.deployments.update(deployment.id, {
    budget: {
      type: "limit",
      max_list_cost: { amount: "2000", currency: "USD" }
    }
  });
  console.log(updatedDeployment.budget?.max_list_cost.amount); // 2000
  ```

  ```csharp C#
  var updatedDeployment = await client.Beta.Deployments.Update(deployment.ID, new()
  {
      Budget = new()
      {
          Type = BetaManagedAgentsBudgetLimitType.Limit,
          MaxListCost = new() { Amount = "2000", Currency = BetaCurrency.Usd },
      },
  });
  Console.WriteLine(updatedDeployment.Budget?.MaxListCost.Amount);  // 2000
  ```

  ```go Go
  updatedDeployment, err := client.Beta.Deployments.Update(ctx, deployment.ID, anthropic.BetaDeploymentUpdateParams{
  	Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
  		Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
  		MaxListCost: anthropic.BetaMonetaryAmountParam{
  			Amount:   "2000",
  			Currency: anthropic.BetaCurrencyUsd,
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(updatedDeployment.Budget.MaxListCost.Amount) // 2000
  ```

  ```java Java
  var updatedDeployment = client.beta().deployments().update(
      deployment.id(),
      DeploymentUpdateParams.builder()
          .budget(BetaManagedAgentsBudgetLimit.builder()
              .type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
              .maxListCost(BetaMonetaryAmount.builder()
                  .amount("2000")
                  .currency(BetaCurrency.USD)
                  .build())
              .build())
          .build()
  );
  IO.println(updatedDeployment.budget().orElseThrow().maxListCost().amount());  // 2000
  ```

  ```php PHP
  $updatedDeployment = $client->beta->deployments->update(
      $deployment->id,
      budget: [
          'type' => 'limit',
          'max_list_cost' => ['amount' => '2000', 'currency' => 'USD'],
      ],
  );
  echo "{$updatedDeployment->budget->maxListCost->amount}\n"; // 2000
  ```

  ```ruby Ruby
  updated_deployment = client.beta.deployments.update(
    deployment.id,
    budget: {
      type: "limit",
      max_list_cost: {amount: "2000", currency: "USD"}
    }
  )
  puts updated_deployment.budget.max_list_cost.amount # 2000
  ```
</CodeGroup>

## 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` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`). Um den Lebenszyklus einer Session zu verfolgen, beobachte die Session-Events über den [Event-Stream](https://platform.claude.com/docs/de/managed-agents/events-and-streaming) oder über [Webhooks](https://platform.claude.com/docs/de/managed-agents/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](https://platform.claude.com/docs/de/managed-agents/webhooks#supported-event-types) aufgeführt.

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

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID"
  ```

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

  ```typescript TypeScript
  for await (const run of client.beta.deploymentRuns.list({
    deployment_id: deployment.id
  })) {
    console.log(run.created_at, run.session_id ?? run.error?.type);
  }
  ```

  ```csharp C#
  var runs = await client.Beta.DeploymentRuns.List(
      new() { DeploymentID = deployment.ID }
  );
  await foreach (var run in runs.Paginate())
  {
      // Die Error-Union stellt .Message direkt bereit; der Diskriminator wird
      // aus .Json gelesen, bis ein gemeinsamer .Type-Accessor hinzugefügt wird.
      var outcome = run.SessionID ?? run.Error!.Json.GetProperty("type").GetString();
      Console.WriteLine($"{run.CreatedAt} {outcome}");
  }
  ```

  ```go Go
  runs := client.Beta.DeploymentRuns.ListAutoPaging(ctx, anthropic.BetaDeploymentRunListParams{
  	DeploymentID: anthropic.String(deployment.ID),
  })
  for runs.Next() {
  	run := runs.Current()
  	if run.SessionID != "" {
  		fmt.Println(run.CreatedAt.Format(time.RFC3339), run.SessionID)
  	} else {
  		fmt.Println(run.CreatedAt.Format(time.RFC3339), run.Error.Type)
  	}
  }
  if err := runs.Err(); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  for (var run : client.beta().deploymentRuns().list(
          DeploymentRunListParams.builder()
              .deploymentId(deployment.id())
              .build()).autoPager()) {
      // Die Error-Union stellt noch keine gemeinsamen .type()/.message()-
      // Accessoren bereit; .toString() enthält beides.
      IO.println(run.createdAt() + " "
          + run.sessionId().orElseGet(() -> run.error().orElseThrow().toString()));
  }
  ```

  ```php PHP
  foreach ($client->beta->deploymentRuns->list(
      deploymentID: $deployment->id,
  )->pagingEachItem() as $run) {
      $outcome = $run->sessionID ?? $run->error->type;
      echo "{$run->createdAt->format(DATE_ATOM)} {$outcome}\n";
  }
  ```

  ```ruby Ruby
  client.beta.deployment_runs.list(
    deployment_id: deployment.id
  ).auto_paging_each do
    puts "#{it.created_at} #{it.session_id || it.error.type}"
  end
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID&has_error=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

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

  ```python Python
  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)
  ```

  ```typescript TypeScript
  for await (const run of client.beta.deploymentRuns.list({
    deployment_id: deployment.id,
    has_error: true
  })) {
    console.log(run.created_at, run.error?.type, run.error?.message);
  }
  ```

  ```csharp C#
  var failedRuns = await client.Beta.DeploymentRuns.List(
      new() { DeploymentID = deployment.ID, HasError = true }
  );
  await foreach (var failedRun in failedRuns.Paginate())
  {
      var error = failedRun.Error!;
      var errorType = error.Json.GetProperty("type").GetString();
      Console.WriteLine($"{failedRun.CreatedAt} {errorType} {error.Message}");
  }
  ```

  ```go Go
  failedRuns := client.Beta.DeploymentRuns.ListAutoPaging(ctx, anthropic.BetaDeploymentRunListParams{
  	DeploymentID: anthropic.String(deployment.ID),
  	HasError:     anthropic.Bool(true),
  })
  for failedRuns.Next() {
  	failedRun := failedRuns.Current()
  	fmt.Println(failedRun.CreatedAt.Format(time.RFC3339), failedRun.Error.Type, failedRun.Error.Message)
  }
  if err := failedRuns.Err(); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  for (var run : client.beta().deploymentRuns().list(
          DeploymentRunListParams.builder()
              .deploymentId(deployment.id())
              .hasError(true)
              .build()).autoPager()) {
      IO.println(run.createdAt() + " " + run.error().orElseThrow());
  }
  ```

  ```php PHP
  foreach ($client->beta->deploymentRuns->list(
      deploymentID: $deployment->id,
      hasError: true,
  )->pagingEachItem() as $run) {
      echo "{$run->createdAt->format(DATE_ATOM)} {$run->error->type} {$run->error->message}\n";
  }
  ```

  ```ruby Ruby
  client.beta.deployment_runs.list(
    deployment_id: deployment.id,
    has_error: true
  ).auto_paging_each do
    puts "#{it.created_at} #{it.error.type} #{it.error.message}"
  end
  ```
</CodeGroup>

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](https://platform.claude.com/docs/de/api/beta/deployment_runs/list).

```json
{
  "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}`](https://platform.claude.com/docs/de/api/beta/deployment_runs/retrieve) auf. Ein [`deployment_run`-Webhook-Event](https://platform.claude.com/docs/de/managed-agents/webhooks#supported-event-types) enthält die Ausführungs-ID als `data.id`.

## Den Deployment-Lebenszyklus verwalten

Jede Änderung am Lebenszyklus löst ein [Webhook-Event](https://platform.claude.com/docs/de/managed-agents/webhooks#supported-event-types) 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.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/pause?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  client.beta.deployments.pause(deployment.id)
  ```

  ```typescript TypeScript
  await client.beta.deployments.pause(deployment.id);
  ```

  ```csharp C#
  await client.Beta.Deployments.Pause(deployment.ID);
  ```

  ```go Go
  if _, err := client.Beta.Deployments.Pause(ctx, deployment.ID, anthropic.BetaDeploymentPauseParams{}); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().deployments().pause(deployment.id());
  ```

  ```php PHP
  $client->beta->deployments->pause($deployment->id);
  ```

  ```ruby Ruby
  client.beta.deployments.pause(deployment.id)
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/unpause?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments unpause --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  client.beta.deployments.unpause(deployment.id)
  ```

  ```typescript TypeScript
  await client.beta.deployments.unpause(deployment.id);
  ```

  ```csharp C#
  await client.Beta.Deployments.Unpause(deployment.ID);
  ```

  ```go Go
  if _, err := client.Beta.Deployments.Unpause(ctx, deployment.ID, anthropic.BetaDeploymentUnpauseParams{}); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().deployments().unpause(deployment.id());
  ```

  ```php PHP
  $client->beta->deployments->unpause($deployment->id);
  ```

  ```ruby Ruby
  client.beta.deployments.unpause(deployment.id)
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/archive?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments archive --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  client.beta.deployments.archive(deployment.id)
  ```

  ```typescript TypeScript
  await client.beta.deployments.archive(deployment.id);
  ```

  ```csharp C#
  await client.Beta.Deployments.Archive(deployment.ID);
  ```

  ```go Go
  if _, err := client.Beta.Deployments.Archive(ctx, deployment.ID, anthropic.BetaDeploymentArchiveParams{}); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().deployments().archive(deployment.id());
  ```

  ```php PHP
  $client->beta->deployments->archive($deployment->id);
  ```

  ```ruby Ruby
  client.beta.deployments.archive(deployment.id)
  ```
</CodeGroup>

### 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](https://platform.claude.com/docs/de/api/beta/deployments/run) 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.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/run?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments run --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  run = client.beta.deployments.run(deployment.id)
  ```

  ```typescript TypeScript
  const run = await client.beta.deployments.run(deployment.id);
  ```

  ```csharp C#
  var manualRun = await client.Beta.Deployments.Run(deployment.ID);
  ```

  ```go Go
  manualRun, err := client.Beta.Deployments.Run(ctx, deployment.ID, anthropic.BetaDeploymentRunParams{})
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var run = client.beta().deployments().run(deployment.id());
  ```

  ```php PHP
  $run = $client->beta->deployments->run($deployment->id);
  ```

  ```ruby Ruby
  run = client.beta.deployments.run(deployment.id)
  ```
</CodeGroup>