---
title: Selbst gehostete Worker überwachen und Fehler beheben
url: https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-operations
description: Lies die Warteschlangentiefe aus, stoppe Sitzungen und Worker, ohne Arbeit zu verlieren, und behebe häufige Fehler bei selbst gehosteten Sandboxes.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: Nicht für ZDR berechtigt, außer bei selbst gehosteten Managed Agents. Sitzungen sind zustandsbehaftete Ressourcen; Transkripte bleiben erhalten, bis du sie löschst.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
    Claude Models on Google Cloud (Anthropic managed):
      availability: beta
      note: Du schreibst deinen eigenen Worker, der die Environments-Work-Endpunkte aufruft.
---

Die Aufrufe für Warteschlangenstatistiken und zum Stoppen auf dieser Seite werden von deinen Überwachungs- oder Betriebstools ausgeführt und mit dem API-Key deiner Organisation authentifiziert. Die Worker-Helfer übernehmen die Schleife zum Beanspruchen und Aufrechterhalten von Arbeitselementen, sodass du diese Endpunkte nicht direkt aufrufst.

<Warning>
  Die Endpunkte für Warteschlangenstatistiken und zum Stoppen akzeptieren entweder den API-Key deiner Organisation oder den Umgebungsschlüssel. Rufe sie von außerhalb des Worker-Hosts mit dem API-Key deiner Organisation auf. Wenn du `ANTHROPIC_API_KEY` auf dem Worker-Host setzt, wird eine organisationsweite Anmeldeinformation für Tool-Aufrufe des Agenten offengelegt.
</Warning>

## Warteschlangentiefe auslesen

`GET /v1/environments/{environment_id}/work/stats` (python, typescript, ruby: `client.beta.environments.work.stats()`; go, csharp: `client.Beta.Environments.Work.Stats()`; java: `client.beta().environments().work().stats()`; php: `$client->beta->environments->work->stats()`; cli: `ant beta:environments:work stats`) gibt den Warteschlangenstatus für eine Umgebung zurück:

| Feld | Bedeutung | Verwende es, um |
| ----- | ----- | ----- |
| `depth` (csharp, go: `Depth`) | Elemente, die darauf warten, beansprucht zu werden. | deine Worker-Flotte zu skalieren oder bei einem Rückstau zu alarmieren. |
| `pending` (csharp, go: `Pending`) | Elemente, die von einem Worker beansprucht, aber noch nicht bestätigt wurden. Die Worker-Helfer bestätigen jedes Element, bevor sie es verarbeiten, daher bleibt dieser Wert im Normalbetrieb nahe null. | einen Worker zu erkennen, der zwischen Beanspruchen und Bestätigen hängen geblieben ist: Alarmiere bei einem anhaltend von null verschiedenen Wert. |
| `oldest_queued_at` (java, php: `oldestQueuedAt`; csharp, go: `OldestQueuedAt`) | Zeitstempel des ältesten Elements, das sich noch in der Warteschlange befindet, entweder wartend auf Beanspruchung oder beansprucht, aber noch nicht bestätigt. `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`), wenn es kein solches Element gibt. | zu sehen, wie lange das älteste Element bereits wartet. |
| `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) | Worker, die in den letzten 30 Sekunden gepollt haben. | bei Ausfall der Worker zu alarmieren. |

<CodeGroup>
  ```bash cURL
  curl -sS "https://api.anthropic.com/v1/environments/$ANTHROPIC_ENVIRONMENT_ID/work/stats" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "anthropic-version: 2026-10-21"
  ```

  ```bash CLI
  ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"
  ```

  ```python Python
  import os

  import anthropic

  client = anthropic.Anthropic()

  stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
  print(f"depth={stats.depth} pending={stats.pending}")
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";

  const client = new Anthropic();

  const stats = await client.beta.environments.work.stats(process.env.ANTHROPIC_ENVIRONMENT_ID!);

  console.log(`depth=${stats.depth} pending=${stats.pending}`);
  ```

  ```csharp C#
  using Anthropic;

  var client = new AnthropicClient();

  var environmentId = Environment.GetEnvironmentVariable("ANTHROPIC_ENVIRONMENT_ID")!;

  var stats = await client.Beta.Environments.Work.Stats(environmentId);

  Console.WriteLine($"depth={stats.Depth} pending={stats.Pending}");
  ```

  ```go Go
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  )

  func main() {
  	client := anthropic.NewClient()
  	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")

  	stats, err := client.Beta.Environments.Work.Stats(
  		context.Background(),
  		environmentID,
  		anthropic.BetaEnvironmentWorkStatsParams{},
  	)
  	if err != nil {
  		panic(err)
  	}

  	fmt.Printf("depth=%d pending=%d\n", stats.Depth, stats.Pending)
  }
  ```

  ```java Java
  import com.anthropic.client.AnthropicClient;
  import com.anthropic.client.okhttp.AnthropicOkHttpClient;
  import com.anthropic.models.beta.environments.work.BetaSelfHostedWorkQueueStats;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      BetaSelfHostedWorkQueueStats stats = client.beta()
          .environments()
          .work()
          .stats(System.getenv("ANTHROPIC_ENVIRONMENT_ID"));

      IO.println("depth=" + stats.depth() + " pending=" + stats.pending());
  }
  ```

  ```php PHP
  <?php

  use Anthropic\Client;

  $client = new Client();

  $stats = $client->beta->environments->work->stats(getenv('ANTHROPIC_ENVIRONMENT_ID'));

  printf("depth=%d pending=%d\n", $stats->depth, $stats->pending);
  ```

  ```ruby Ruby
  require "anthropic"

  client = Anthropic::Client.new

  stats = client.beta.environments.work.stats(ENV.fetch("ANTHROPIC_ENVIRONMENT_ID"))

  puts "depth=#{stats.depth} pending=#{stats.pending}"
  ```
</CodeGroup>

```json
{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}
```

## Eine Sitzung ordnungsgemäß stoppen

Verwende `POST /v1/environments/{environment_id}/work/{work_id}/stop` (python, typescript, ruby: `client.beta.environments.work.stop()`; go, csharp: `client.Beta.Environments.Work.Stop()`; java: `client.beta().environments().work().stop()`; php: `$client->beta->environments->work->stop()`; cli: `ant beta:environments:work stop`), um den Worker, der eine bestimmte Sitzung bearbeitet, aufzufordern, sie zu beenden.

Standardmäßig wechselt das Arbeitselement in den Status `stopping`. Der Worker erkennt dies bei seinem nächsten Lease-Heartbeat, bricht den laufenden Tool-Aufruf der Sitzung ab und bestätigt das Herunterfahren. Das Arbeitselement wechselt dann in den Status `stopped`. Ein Python-SDK-Worker lässt stattdessen zuerst den laufenden Tool-Aufruf abschließen, was bis zu 2,5 Minuten dauern kann.

Übergib `force: true` (python: `force=True`; csharp: `Force = true`; go: `BetaSelfHostedWorkStopRequest: anthropic.BetaSelfHostedWorkStopRequestParam{Force: anthropic.Bool(true)}`; java: `.force(true)`; cli: `--force`), um das Arbeitselement sofort als `stopped` zu markieren, anstatt auf die Bestätigung des Workers zu warten. Ein erzwungener Stopp beendet einen laufenden Tool-Aufruf nicht früher, da der Worker den Stopp weiterhin erst bei seinem nächsten Heartbeat bemerkt.

Da diese Aufrufe von deinen Betriebstools und nicht vom Worker-Host ausgeführt werden, wird `ANTHROPIC_WORK_ID` nicht automatisch gesetzt. Setze die Variable auf die ID des Ziel-Arbeitselements, bevor du die folgenden Beispiele ausführst. Um die ID eines Arbeitselements zu finden, rufe [Arbeitselemente auflisten](https://platform.claude.com/docs/de/api/beta/environments/work/list) mit dem Umgebungsschlüssel auf, gesendet als `Authorization: Bearer $ANTHROPIC_ENVIRONMENT_KEY`. Dieser Endpunkt lehnt den API-Key deiner Organisation ab.

<CodeGroup>
  ```bash cURL
  curl -sS "https://api.anthropic.com/v1/environments/$ANTHROPIC_ENVIRONMENT_ID/work/$ANTHROPIC_WORK_ID/stop" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{}'
  ```

  ```bash CLI
  ant beta:environments:work stop \
    --environment-id "$ANTHROPIC_ENVIRONMENT_ID" \
    --work-id "$ANTHROPIC_WORK_ID"
  ```

  ```python Python
  import os

  import anthropic

  client = anthropic.Anthropic()

  work = client.beta.environments.work.stop(
      os.environ["ANTHROPIC_WORK_ID"],
      environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
  )
  print(work.state)
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";

  const client = new Anthropic();

  const work = await client.beta.environments.work.stop(process.env.ANTHROPIC_WORK_ID!, {
    environment_id: process.env.ANTHROPIC_ENVIRONMENT_ID!
  });

  console.log(work.state);
  ```

  ```csharp C#
  using Anthropic;

  var client = new AnthropicClient();

  var work = await client.Beta.Environments.Work.Stop(
      Environment.GetEnvironmentVariable("ANTHROPIC_WORK_ID")!,
      new()
      {
          EnvironmentID = Environment.GetEnvironmentVariable("ANTHROPIC_ENVIRONMENT_ID")!
      }
  );

  Console.WriteLine(work.State);
  ```

  ```go Go
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  )

  func main() {
  	client := anthropic.NewClient()

  	work, err := client.Beta.Environments.Work.Stop(
  		context.Background(),
  		os.Getenv("ANTHROPIC_WORK_ID"),
  		anthropic.BetaEnvironmentWorkStopParams{
  			EnvironmentID: os.Getenv("ANTHROPIC_ENVIRONMENT_ID"),
  		},
  	)
  	if err != nil {
  		panic(err)
  	}
  	fmt.Println(work.State)
  }
  ```

  ```java Java
  import com.anthropic.client.AnthropicClient;
  import com.anthropic.client.okhttp.AnthropicOkHttpClient;
  import com.anthropic.models.beta.environments.work.BetaSelfHostedWork;
  import com.anthropic.models.beta.environments.work.BetaSelfHostedWorkStopRequest;
  import com.anthropic.models.beta.environments.work.WorkStopParams;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      BetaSelfHostedWork work = client.beta().environments().work().stop(
          WorkStopParams.builder()
              .environmentId(System.getenv("ANTHROPIC_ENVIRONMENT_ID"))
              .workId(System.getenv("ANTHROPIC_WORK_ID"))
              .betaSelfHostedWorkStopRequest(BetaSelfHostedWorkStopRequest.builder().build())
              .build()
      );

      IO.println(work.state());
  }
  ```

  ```php PHP
  <?php

  use Anthropic\Client;

  $client = new Client();

  $work = $client->beta->environments->work->stop(
      getenv('ANTHROPIC_WORK_ID'),
      environmentID: getenv('ANTHROPIC_ENVIRONMENT_ID'),
  );

  echo $work->state . "\n";
  ```

  ```ruby Ruby
  require "anthropic"

  client = Anthropic::Client.new

  work = client.beta.environments.work.stop(
    ENV.fetch("ANTHROPIC_WORK_ID"),
    environment_id: ENV.fetch("ANTHROPIC_ENVIRONMENT_ID")
  )

  puts work.state
  ```
</CodeGroup>

## Worker ordnungsgemäß stoppen

Ein Worker, der abgebrochen wird, während eine Sitzung läuft, fährt diese Sitzung herunter, bevor er sich beendet – genauso wie beim [Stoppen einer Sitzung](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-operations#stop-a-session-gracefully). Wenn an die Sitzung [Memory Stores](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory) angehängt sind, lädt der Worker dennoch neue und geänderte Dateien hoch und entfernt die Store-Verzeichnisse. Er sendet keine Löschungen, sodass eine Memory, die der Agent gelöscht hat, im Store verbleibt, sofern eine frühere Synchronisierung sie nicht bereits aus dem Store gelöscht hat.

Ein Prozess, der abrupt endet, führt kein Teardown aus. So stoppst du einen Worker sauber:

1. **Stelle sicher, dass SIGTERM und SIGINT den Worker abbrechen.** Wie das geht, hängt vom Worker ab:

   | Worker | Was zu tun ist |
   | ----- | ----- |
   | `ant` CLI | Nichts. Die CLI verarbeitet beide Signale selbst: Sie bricht jeden laufenden Tool-Aufruf ab, sendet ihr Fehlerergebnis und markiert das Arbeitselement als `stopped`. |
   | SDK-Worker, der ein eigener Prozess ist | `EnvironmentWorker` installiert keine Signal-Handler. Brich den Worker aus einem Signal-Handler heraus ab, wie es die Beispiele für eigenständige Worker tun. |
   | SDK-Worker innerhalb eines Webhook-Servers | Brich den Worker aus dem eigenen Shutdown-Hook des Servers heraus ab, wie es die Webhook-Beispiele tun. Der Worker darf die Signale des Servers nicht übernehmen. |

2. **Stoppe den Worker mit SIGTERM und gib ihm Zeit zum Abschließen, bevor du ihn hart beendest.** Der Worker braucht Zeit, um einen laufenden Tool-Aufruf zu beenden und geänderte Dateien in einen Memory Store hochzuladen. Docker sendet standardmäßig 10 Sekunden nach dem Stoppsignal SIGKILL. Erhöhe dieses Limit mit `--stop-timeout 60` (python: `--stop-timeout 210`) bei `docker run` oder setze die „termination grace period“ (Schonfrist beim Beenden) deines Orchestrators auf dieselbe Anzahl an Sekunden.

Wenn ein Worker stoppt, bevor sein Teardown ausgeführt wird, verlierst du alle Memory-Änderungen, die noch nicht synchronisiert wurden. Lösche auf einem langlebigen Host außerdem das übrig gebliebene Store-Verzeichnis unter `/mnt/memory/` vor der nächsten Sitzung, die diesen Store anhängt. Eine Sandbox, die eine einzige Sitzung bedient und danach verworfen wird, benötigt keine Bereinigung.

## Fehlerbehebung

### Der Worker verbindet sich nicht

Wenn `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) bei 0 bleibt, erreicht der Worker die Warteschlange nicht. Vergewissere dich, dass `ANTHROPIC_ENVIRONMENT_KEY` und `ANTHROPIC_ENVIRONMENT_ID` auf dem Worker-Host gesetzt sind.

### Eine Sitzung bleibt in der Warteschlange

Kein Worker beansprucht Arbeit. Eine Sitzung in der Warteschlange wartet, anstatt fehlzuschlagen. Prüfe `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) und `depth` (csharp, go: `Depth`) unter [Warteschlangentiefe auslesen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-operations#read-queue-depth).

### Memory Stores lassen sich nicht einbinden oder synchronisieren

Wo ein Memory-Store-Fehler sichtbar wird, hängt von seiner Art ab:

* **Ein Fehler beim Einbinden:** Wenn der Worker beim Beanspruchen einer Sitzung einen Memory Store nicht einbinden kann, schreibt er den Fehler in sein Log und lässt das Arbeitselement fehlschlagen. Die Sitzung gibt kein Fehlerereignis aus und bleibt im Leerlauf.
* **Ein Fehler bei der Synchronisierung:** Der Worker schreibt den Fehler in sein Log und meldet ihn nicht an die Sitzung.
* **Ein abgelehnter Schreibvorgang in einen schreibgeschützten Store:** Der Agent erhält einen Tool-Fehler. Siehe [Schreibgeschützte Stores und Konflikte](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory#read-only-stores-and-conflicts).

| Symptom | Ursache | Lösung |
| ----- | ----- | ----- |
| Das Worker-Log enthält `the work item carried no sessions token` (in Go den Fehler `ErrSessionMemoryNoToken`), und das Arbeitselement schlägt fehl. | Das sitzungsspezifische `secret` (csharp, go: `Secret`) des Arbeitselements hat den Worker nicht erreicht. Entweder hat dein Code es nicht weitergeleitet, oder Memory Stores auf selbst gehosteten Sandboxes sind für deine Organisation nicht aktiviert. | [Leite das Secret des Arbeitselements weiter](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-per-session#forward-the-work-items-secret). Wenn der Worker in einem einzigen Prozess pollt und Sitzungen ausführt und dies trotzdem protokolliert, wende dich an den Support. |
| Das Worker-Log enthält `something already exists at the memory store's path`. | Eine andere Sitzung auf demselben Dateisystem verwendet diesen Pfad. Oder der Worker einer vorherigen Sitzung wurde beendet, bevor sein Teardown ausgeführt wurde, sodass das Verzeichnis zurückgeblieben ist. | Prüfe, ob ein Worker noch eine Sitzung ausführt, die diesen Pfad verwendet. Falls ja, entferne das Verzeichnis nicht: Der Worker entfernt es, wenn er mit der Sitzung fertig ist. Falls nicht, entferne das Verzeichnis, das in der Log-Zeile genannt wird. Darin enthaltene Änderungen, die noch nicht synchronisiert wurden, gehen verloren. Um zwei solche Sitzungen gleichzeitig auszuführen, siehe [Sitzungen isolieren, die sich einen Store teilen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory#isolate-sessions-that-share-a-store). |
| Das Worker-Log enthält `cannot create the memory store's folder` und `the worker host must make this mount path writable`. | Der Benutzer, unter dem der Worker läuft, kann unter `/mnt/memory` keine Verzeichnisse erstellen. | Erstelle `/mnt/memory` und weise es mit `chown` diesem Benutzer zu. Siehe [Den Host vorbereiten](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). Folge unter macOS stattdessen [Einen macOS-Host vorbereiten](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host). |
| Die Sitzung verharrt, kurz nachdem ein Worker sie beansprucht hat, im Status `idle` mit dem Stop-Grund `requires_action` und ohne Fehlerereignis. | Der Worker hat das Arbeitselement fehlschlagen lassen, weil er aus einem der vorstehenden Gründe einen Memory Store nicht einbinden konnte. | Behebe die Ursache auf dem Host und sende dann ein [`user.interrupt`](https://platform.claude.com/docs/de/managed-agents/events-and-streaming#interrupt-the-agent)-Ereignis. Die Arbeit der Sitzung wird erneut in die Warteschlange gestellt, und der nächste Worker, der sie beansprucht, versucht das Einbinden erneut. |

### Ein benutzerdefinierter Tool-Aufruf kehrt nie zurück

Wenn die Sitzung mit dem Stop-Grund `requires_action` pausiert bleibt, bedient kein Worker oder Client dieses Tool. Siehe [Ein benutzerdefiniertes Tool bereitstellen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-custom-tools#serve-a-custom-tool).

### Ein gekapselter MCP-Tool-Aufruf hängt

Ohne Timeout auf dem MCP-Client wird ein hängender Aufruf an einen [gekapselten MCP-Server](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-custom-tools#wrap-an-mcp-server-as-custom-tools) erst dann zu einem Fehlerergebnis, wenn eine Absicherung greift:

| SDK | Absicherung | Greift nach |
| ----- | ----- | ----- |
| Python | Das eigene Tool-Aufruf-Limit des Workers | Etwa 2,5 Minuten |
| TypeScript | Das Standard-Request-Timeout des MCP SDK | Etwa eine Minute |
| Go | Der Worker bricht einen Tool-Aufruf ab, der sein Standardlimit überschreitet | 120 Sekunden |
