Selbst gehostete Worker überwachen und Fehler beheben
Lies die Warteschlangentiefe aus, stoppe Sitzungen und Worker, ohne Arbeit zu verlieren, und behebe häufige Fehler bei selbst gehosteten Sandboxes.
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.
Warteschlangentiefe auslesen
client.beta.environments.work.stats() gibt den Warteschlangenstatus für eine Umgebung zurück:
| Feld | Bedeutung | Verwende es, um |
|---|---|---|
depth | Elemente, die darauf warten, beansprucht zu werden. | deine Worker-Flotte zu skalieren oder bei einem Rückstau zu alarmieren. |
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 | Zeitstempel des ältesten Elements, das sich noch in der Warteschlange befindet, entweder wartend auf Beanspruchung oder beansprucht, aber noch nicht bestätigt. None, wenn es kein solches Element gibt. | zu sehen, wie lange das älteste Element bereits wartet. |
workers_polling | Worker, die in den letzten 30 Sekunden gepollt haben. | bei Ausfall der Worker zu alarmieren. |
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 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, 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 auflistenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. mit dem Umgebungsschlüssel auf, gesendet als Authorization: Bearer $ANTHROPIC_ENVIRONMENT_KEY. Dieser Endpunkt lehnt den API-Key deiner Organisation ab.
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, fährt diese Sitzung herunter, bevor er sich beendet – genauso wie beim Stoppen einer Sitzung. Wenn an die Sitzung Memory Stores 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:
-
Stelle sicher, dass SIGTERM und SIGINT den Worker abbrechen. Wie das geht, hängt vom Worker ab:
Worker Was zu tun ist antCLINichts. 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 EnvironmentWorkerinstalliert 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. -
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 210beidocker runoder 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 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 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.
| 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 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. 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. |
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. Folge unter macOS stattdessen Einen macOS-Host vorbereiten. |
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-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.
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:
| 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 |
War diese Seite hilfreich?