Selbst gehostete Worker überwachen und Fehler beheben

Die Überwachungsaufrufe auf dieser Seite werden von deinen Überwachungs- oder Betriebstools ausgeführt und mit deinem Claude-API-Key authentifiziert. Die Worker-Helfer übernehmen die Schleife zum Beanspruchen und Aufrechterhalten von Arbeitselementen, sodass du diese Endpunkte nicht direkt aufrufst.

Warteschlangentiefe auslesen

client.beta.environments.work.stats() gibt den Warteschlangenstatus für eine Umgebung zurück:

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

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

Eine Sitzung ordnungsgemäß stoppen

Verwende client.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 bemerkt 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.

Übergib force=True, um das Arbeitselement sofort als stopped zu markieren, anstatt auf die Bestätigung des Workers zu warten.

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, liste die Arbeitselemente der Umgebung über die Environments-Work-Endpunkte auf.

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)

Worker ordnungsgemäß stoppen

Ein Worker, der abgebrochen wird, während eine Sitzung läuft, stoppt seine laufende Arbeit, bevor er sich beendet. Wenn an die Sitzung Memory Stores angehängt sind, überspringt der Worker die abschließende Synchronisierung, lädt aber dennoch geänderte Dateien hoch und entfernt die Store-Verzeichnisse.

Ein beendeter (gekillter) Prozess 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 gibt das Arbeitselement frei.
   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 lass mindestens 30 Sekunden Zeit, bevor du ihn hart beendest. Der abschließende Upload kann so lange dauern. Docker sendet standardmäßig 10 Sekunden nach dem Stoppsignal SIGKILL. Erhöhe dieses Limit mit --stop-timeout bei docker run oder mit der Termination Grace Period deines Orchestrators.

Wenn ein Worker beendet wird, bevor sein Teardown ausgeführt wird, gehen alle Memory-Änderungen verloren, die noch nicht synchronisiert wurden. Entferne 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 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 und depth unter Warteschlangentiefe auslesen.

Memory Stores lassen sich nicht einbinden

Der Worker protokolliert Fehler beim Einbinden und bei der Hintergrundsynchronisierung, anstatt sie an die Sitzung zu melden. Nur Ablehnungen wegen Schreibschutz erreichen den Agenten, und zwar als Tool-Fehler (siehe Schreibgeschützte Stores und Konflikte).

Wenn der Worker beim Beanspruchen einer Sitzung einen Memory Store nicht einbinden kann, lässt er das Arbeitselement fehlschlagen. Die Sitzung gibt kein Fehlerereignis aus und bleibt im Leerlauf.

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.

Ein gekapselter MCP-Tool-Aufruf hängt

Ohne Timeout auf dem MCP-Client wird ein hängender Aufruf an einen gekapselten MCP-Server erst dann zu einem Fehlerergebnis, wenn eine Absicherung greift: