Referenz für selbst gehostete Worker
Referenz für selbst gehostete Sandbox-Worker: ant-CLI-Flags, Umgebungsvariablen, Host-Anforderungen, Dateisystempfade und Optionen der SDK-Helfer.
Diese Seite dokumentiert die vorgefertigten Worker, die eine self_hosted-Umgebung bedienen. Für aufgabenorientierte Leitfäden beginne mit Selbst gehostete Sandboxes und Selbst gehostete Worker bereitstellen.
CLI-Befehle und Flags
| Befehl | Beschreibung |
|---|---|
ant beta:worker poll | Beansprucht Arbeitselemente aus der Warteschlange der Umgebung und führt jede Sitzung im Prozess aus. Mit --on-work ruft es stattdessen für jedes Arbeitselement dein Skript auf. |
ant beta:worker run | Verarbeitet eine beanspruchte Sitzung und beendet sich. Verwende es als Einstiegspunkt einer Sandbox pro Sitzung. |
| Flag | Beschreibung |
|---|---|
--environment-id | Die Umgebung, die nach Arbeit abgefragt wird. Wird auch aus ANTHROPIC_ENVIRONMENT_ID gelesen. |
--environment-key | Authentifiziert den Worker bei dieser Umgebung. Wird auch aus ANTHROPIC_ENVIRONMENT_KEY gelesen. |
--workdir | Verzeichnis, in das der Worker Skills herunterlädt und in dem Tools Dateien lesen und schreiben. Standardmäßig . (das aktuelle Verzeichnis). Das Verzeichnis muss existieren, bevor der Worker startet. |
--on-work | Skript, das für jedes beanspruchte Arbeitselement aufgerufen wird, anstatt Tools im Prozess auszuführen. Erhält Sitzungsdetails als Umgebungsvariablen und das Arbeitselement als JSON über die Standardeingabe. |
--max-idle | Wie lange der Worker wartet, während eine Sitzung im Leerlauf ist, bevor sich ant beta:worker run beendet oder ant beta:worker poll zum nächsten Arbeitselement übergeht. Leerlaufzeit mit einem requires_action-Stop-Grund zählt nicht. Standardmäßig 60s. Setze den Wert auf 0, um das Timeout zu deaktivieren. Mit einem --on-work-Skript ignoriert ant beta:worker poll dieses Flag. Übergib es stattdessen an den ant beta:worker run-Befehl, den dein Skript startet. |
--log-format | Format der Log-Ausgabe. Verwende json für die strukturierte Log-Erfassung. Standardmäßig text. |
Umgebungsvariablen
| Variable | Beschreibung | Gesetzt von |
|---|---|---|
ANTHROPIC_ENVIRONMENT_ID | Die Umgebung, deren Warteschlange der Worker bedient. | Dir, auf dem Worker-Host. Der Poller übergibt sie an das --on-work-Skript. |
ANTHROPIC_ENVIRONMENT_KEY | Authentifiziert den Worker bei seiner Warteschlange. | Dir, auf dem Worker-Host. Der Poller übergibt sie an das --on-work-Skript. |
ANTHROPIC_SESSION_ID | Die Sitzung, die ein beanspruchtes Arbeitselement repräsentiert. | Dem Poller, für das --on-work-Skript. |
ANTHROPIC_WORK_ID | Das beanspruchte Arbeitselement. | Dem Poller, für das --on-work-Skript. |
ANTHROPIC_WORK_SECRET | Das Secret des Arbeitselements für seine Sitzung. | Dir. Der Poller setzt sie nicht. Siehe Das Secret des Arbeitselements weiterleiten. |
ANTHROPIC_BASE_URL | Überschreibt den Standard-API-Endpunkt. Optional. | Dir, auf dem Worker-Host. |
ANTHROPIC_WEBHOOK_SIGNING_KEY | Verifiziert eingehende Webhook-Payloads. | Dir, auf einem Webhook-Handler-Host. |
Host-Anforderungen
| Worker | Anforderung |
|---|---|
| Alle Worker | Ein Linux- oder macOS-Host mit /bin/bash unter genau diesem Pfad. Das bash-Tool des Workers führt es direkt aus, ohne PATH zu berücksichtigen. Unter macOS ist das die System-Bash 3.2. |
| TypeScript SDK | unzip und tar im PATH sowie Node.js 22 oder neuer. |
| Python und Go SDKs | Keine zusätzlichen Binärdateien. Diese SDKs verwenden ihre Standardbibliotheken zum Entpacken von Archiven. |
Memory Stores bringen eigene Anforderungen mit.
Unter macOS ist das Root-Volume schreibgeschützt, daher kann mkdir das Verzeichnis /workspace nicht erstellen. Setze das Arbeitsverzeichnis des Workers auf ein Verzeichnis, in das du schreiben kannst, etwa ein workspace-Verzeichnis in deinem Home-Verzeichnis. Um Memory Stores unter macOS zu verwenden, bereite zuerst den macOS-Host vor.
Sandbox-Dateisystem
| Pfad | Inhalt |
|---|---|
/workspace | Das Arbeitsverzeichnis in den Beispielen auf den Seiten zu selbst gehosteten Sandboxes. Es ist nicht der Standard des Workers: Der Worker verwendet das aktuelle Verzeichnis, sofern du nicht --workdir oder workdir setzt. Die Cloud-Sandboxes von Anthropic legen Skills und Repositorys in /workspace ab. Wenn du ein anderes Arbeitsverzeichnis verwendest, aktualisiere den System-Prompt deines Agenten, damit Claude die Skill-Dateien finden kann. |
<workdir>/skills/<name>/ | Die heruntergeladenen Skills des Agenten. |
/mnt/memory/<store>/ | Eine lokale Kopie jedes angehängten Memory Stores, ein Verzeichnis pro Store. Die API gibt den vollständigen Pfad jedes Verzeichnisses im Feld mount_path der Memory-Store-Ressource der Sitzung zurück (zum Beispiel /mnt/memory/user-preferences/). |
Der Worker erstellt die Memory-Store-Verzeichnisse, wenn er eine Sitzung beansprucht. Er entfernt sie, wenn er mit dieser Sitzung fertig ist oder wenn du den Worker ordnungsgemäß stoppst. Dadurch werden nur die lokalen Kopien entfernt, und die Memories bleiben im Store.
Skills können ausführbare Dateien enthalten, die der Agent direkt ausführen kann. Die CLI- und SDK-Worker behalten beim Entpacken die im Skill-Bundle hinterlegten Ausführungsberechtigungen bei. Wenn du Skills selbst herunterlädst, setze ihre Ausführungsberechtigungen selbst.
Wann der Worker mit einer Sitzung fertig ist
Der Worker ist in jedem dieser Fälle mit einer Sitzung fertig:
- Die Sitzung endet.
- Du stoppst das Arbeitselement der Sitzung.
- Die Sitzung bleibt für die Dauer des Leerlauflimits des Workers im Leerlauf. Die Sitzung selbst bleibt offen. Wenn du ihr dann ein neues Event sendest, etwa eine Benutzernachricht, beansprucht derselbe Worker oder ein anderer die Sitzung. Dieser Worker lädt die Stores erneut herunter.
Das Leerlauflimit beträgt standardmäßig 60 Sekunden. Um es zu ändern, verwende --max-idle für den ant-CLI-Worker oder max_idle für EnvironmentWorker. Das cma-sandboxes-Helm-Chart startet seine Worker stattdessen mit einem Limit von 30 Minuten. Um dieses Limit zu ändern, ändere die Einstellung sandbox.idleTimeout des Charts.
Endgültige Ergebnisse
Selbst gehostete Sandboxes haben kein /mnt/session/outputs-Verzeichnis. In den Cloud-Sandboxes von Anthropic weist der System-Prompt der Sitzung den Agenten an, endgültige Ergebnisse dorthin zu kopieren. In selbst gehosteten Umgebungen lässt der System-Prompt diese Anweisung weg. Endgültige Ergebnisse bleiben dort, wo der Agent sie ablegt, typischerweise unterhalb des Arbeitsverzeichnisses, und der Worker lädt sie nicht hoch.
Um endgültige Ergebnisse an einem Ort zu sammeln, gib im System-Prompt deines Agenten den vollständigen Pfad eines Verzeichnisses an. Wähle ein Verzeichnis, in das die Datei-Tools des Workers schreiben können:
- Innerhalb des Arbeitsverzeichnisses: Zum Beispiel
/workspace/outputs, wenn das Arbeitsverzeichnis/workspaceist. - An einem anderen Ort, nur mit einem SDK-Worker: Füge das Verzeichnis zu
allowed_rootshinzu. Siehe AgentToolContext und das Agent-Toolset.
SDK-Helfer
Die Python-, TypeScript- und Go-SDKs bieten drei Helfer mit unterschiedlichem Kontrollgrad:
| Helfer | Was er tut | Verwende ihn, wenn |
|---|---|---|
EnvironmentWorker | Übernimmt Polling, Einrichtung und Tool-Ausführung von Anfang bis Ende. | In den meisten Fällen. |
work.poller() | Fragt die Arbeitswarteschlange ab und übergibt dir jede beanspruchte Sitzung. | Du bestimmst, wie jede Sitzung behandelt wird, zum Beispiel durch das Starten einer Sandbox, anstatt Tools im Prozess auszuführen. |
client.beta.sessions.events.tool_runner() | Führt Tool-Aufrufe für eine einzelne Sitzung aus, anhand der Sitzungs-ID und einer Tool-Liste. | Du hast die Arbeit bereits beansprucht und musst nur die Tools ausführen. |
EnvironmentWorker
| Methode | Beschreibung |
|---|---|
run() | Läuft unbegrenzt und übernimmt Sitzungen, sobald sie eintreffen. |
handle_item() | Verarbeitet ein Arbeitselement, das bereits von einem Poller beansprucht wurde. Der Poller kann ant beta:worker poll --on-work oder dein eigener Code sein. Die Methode kehrt zurück, wenn der Worker mit der Sitzung des Elements fertig ist. Du kannst work_id, session_id, environment_id und work_secret übergeben. Für jeden Wert, den du weglässt, liest die Methode die entsprechende ANTHROPIC_*-Variable. |
| Option | Beschreibung |
|---|---|
tools | Eine Factory, die den AgentToolContext der Sitzung erhält und die Tool-Liste zurückgibt. Standardmäßig das Standard-Agent-Toolset. |
max_idle | Wie lange der Worker wartet, während eine Sitzung im Leerlauf ist, bevor er mit der Sitzung fertig ist. Leerlaufzeit mit einem requires_action-Stop-Grund zählt nicht. Standardmäßig 60 Sekunden. Um 5 Minuten zu warten, setze den Wert auf 300. Um das Limit zu deaktivieren, setze den Wert auf None. |
memory_sync_interval | Die kürzeste Zeit zwischen zwei Synchronisierungen der angehängten Memory Stores während der Sitzung. Der Worker prüft das Intervall nach jedem Aufruf eines Tools, das in deiner Sandbox läuft, nicht per Timer. Standardmäßig 15 Sekunden. Siehe Synchronisierungsintervall. |
memory_sync_deletions | Ob Dateien, die der Agent lokal löscht, auch aus dem Store gelöscht werden. Siehe Löschungen. |
EnvironmentWorker verwaltet den AgentToolContext und das Toolset automatisch. Übergib eine tools-Factory, um die Tool-Liste anzupassen:
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic, beta_async_tool
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_bash_tool
@beta_async_tool
async def get_order_status(order_id: str) -> str:
"""Look up an order in the internal fulfillment system by order ID."""
return f"Order {order_id}: shipped"
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
async with AsyncAnthropic(auth_token=environment_key) as client:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
# Liste jedes Tool auf, das der Agent aufrufen kann. Der Worker beantwortet kein anderes Tool.
tools=lambda env: [beta_bash_tool(env), get_order_status],
)
task = asyncio.create_task(worker.run())
loop = asyncio.get_running_loop()
for signum in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(signum, task.cancel)
with contextlib.suppress(asyncio.CancelledError):
await task
asyncio.run(main())Work-Poller
| Option | Beschreibung |
|---|---|
drain | Ob das Polling beendet wird, sobald die Warteschlange leer ist, anstatt auf neue Arbeit zu warten. |
block_ms | Wie lange jede Abfrage auf eintreffende Arbeit wartet, bevor sie zurückkehrt, in Millisekunden. Muss zwischen 1 und 999 liegen. Der Helfer fragt automatisch erneut ab. Übergib None für eine nicht blockierende Prüfung. Standardmäßig ein Long-Poll von 999 ms. |
reclaim_older_than_ms | Beansprucht Arbeitselemente erneut, die beansprucht, aber innerhalb dieser Anzahl von Millisekunden nie bestätigt wurden. |
auto_stop | Ob der Poller für jedes Arbeitselement ein Stoppsignal sendet, sobald dein Schleifenrumpf damit fertig ist. Standardmäßig True. Setze es in den zwei Fällen, die auf diese Tabelle folgen, auf False. |
Setze auto_stop in zwei Fällen auf False:
- Deine Schleife ruft
handle_item()auf, das den Stopp selbst sendet. - Deine Schleife startet eine Sandbox für das Element und macht weiter. Der Worker in dieser Sandbox muss den Stopp senden, wenn die Arbeit der Sitzung endet, wie es
ant beta:worker runundhandle_item()tun.
Ein vollständiges Beispiel findest du unter Sandboxes aus dem SDK-Poller starten.
Sitzungs-Tool-Runner
client.beta.sessions.events.tool_runner() nimmt eine Tool-Liste als tools entgegen. Um diese Liste zu erstellen, richte AgentToolContext selbst ein und rufe beta_agent_toolset_20260401(env) auf:
from anthropic.lib.tools.agent_toolset import (
AgentToolContext,
beta_agent_toolset_20260401,
)
async with AgentToolContext(
workdir="/workspace", client=client, session_id=work.data.id
) as env:
# Skills heruntergeladen nach /workspace/skills/<name>/
tools = beta_agent_toolset_20260401(env)AgentToolContext und das Agent-Toolset
AgentToolContext ist der Ausführungskontext für Tool-Aufrufe. Er definiert das Arbeitsverzeichnis und die Pfadrichtlinie und kann die Skills der Sitzung herunterladen.
| Option | Beschreibung |
|---|---|
allowed_roots | Verzeichnisse, zusätzlich zum Arbeitsverzeichnis, die die Datei-Tools (read, write, edit, glob, grep) erreichen können. |
read_only_roots | Verzeichnisse, unterhalb derer write und edit Pfade ablehnen. |
EnvironmentWorker fügt die Memory-Store-Verzeichnisse der Sitzung selbst zu allowed_roots hinzu und die Verzeichnisse von Stores, die mit access: "read_only" angehängt sind, zu read_only_roots.
Die Eingrenzung ist nur eine Schutzvorkehrung für die Datei-Tools, keine Sandbox. Sie schränkt bash nicht ein.
beta_agent_toolset_20260401(env) nimmt einen AgentToolContext entgegen und gibt die Standard-Tool-Implementierungen (bash, read, write, edit, glob, grep) zurück.
War diese Seite hilfreich?