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 Skills heruntergeladen werden und in dem Tools Dateien lesen und schreiben. Standardmäßig . (das aktuelle Verzeichnis). |
--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 gewartet wird, nachdem die Sitzung mit einem end_turn-„stop reason“ (Stop-Grund) in den Leerlauf gegangen ist, bevor heruntergefahren wird. Standardmäßig 60s. |
--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 sitzungsspezifische Secret des Arbeitselements. | 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-Host mit /bin/bash genau unter diesem Pfad. Das Bash-Tool des Workers ruft es direkt auf, ohne PATH zu konsultieren. |
| 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.
Sandbox-Dateisystem
| Pfad | Inhalt |
|---|---|
/workspace | Das systemweite Standard-Arbeitsverzeichnis für die Tool-Ausführung und den Skill-Download. 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>/ | Ein Verzeichnis pro angehängtem Memory Store, unter dem mount_path des Stores (zum Beispiel /mnt/memory/user-preferences/). Der Worker erstellt diese Verzeichnisse, wenn er die Sitzung beansprucht, und entfernt sie, wenn die Sitzung endet. |
In selbst gehosteten Umgebungen lässt der System-Prompt der Sitzung die /mnt/session/outputs-Anweisung weg, die in von Anthropic verwalteten Sandboxes verwendet wird. Endgültige Ergebnisse landen dort, wo der Agent sie in deinem Sandbox-Dateisystem ablegt, typischerweise unterhalb des Arbeitsverzeichnisses.
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 den Skill-Download manuell implementierst, bist du selbst für das Setzen der Ausführungsberechtigungen verantwortlich.
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 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, was für jede Sitzung passiert, zum Beispiel 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 benötigst nur die Ausführungsschicht. |
EnvironmentWorker
| Methode | Beschreibung |
|---|---|
run() | Läuft unbegrenzt und übernimmt Sitzungen, sobald sie eintreffen. |
handle_item() | Verarbeitet ein einzelnes beanspruchtes Arbeitselement und kehrt zurück. Übergib die Arbeits-, Sitzungs- und Umgebungskennungen sowie das work_secret explizit, oder lass es die ANTHROPIC_*-Variablen lesen. |
| Option | Beschreibung |
|---|---|
tools | Eine Factory, die den AgentToolContext der Sitzung erhält und die Tool-Liste zurückgibt. Standardmäßig das Standard-Agent-Toolset. |
memory_sync_interval | Wie oft angehängte Memory Stores während der Sitzung mit dem Server abgeglichen werden. 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:
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])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 für jedes Arbeitselement ein Stoppsignal gesendet wird, sobald dein Schleifenrumpf damit fertig ist. Setze es auf False, wenn das, was das Arbeitselement ausführt, den Stopp selbst sendet. handle_item() tut das, ebenso eine von dir gestartete Sandbox, die den Stopp-Aufruf übernimmt. |
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.
Was this page helpful?