--- title: Referenz für selbst gehostete Worker url: https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-reference description: "Referenz für selbst gehostete Sandbox-Worker: ant-CLI-Flags, Umgebungsvariablen, Host-Anforderungen, Dateisystempfade und Optionen der SDK-Helfer." featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Diese Seite dokumentiert die vorgefertigten Worker, die eine `self_hosted`-Umgebung bedienen. Für aufgabenorientierte Leitfäden beginne mit [Selbst gehostete Sandboxes](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes) und [Selbst gehostete Worker bereitstellen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-workers). ## 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)](https://platform.claude.com/docs/de/build-with-claude/handling-stop-reasons) 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](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). | | `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](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory#requirements) 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. | | `/skills//` | Die heruntergeladenen Skills des Agenten. | | `/mnt/memory//` | Ein Verzeichnis pro angehängtem Memory Store, unter dem `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) 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`](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-reference#environment-worker) | Übernimmt Polling, Einrichtung und Ausführung von Anfang bis Ende. | In den meisten Fällen. | | [`work.poller()` (go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-reference#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()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-reference#session-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()` (go: `Run()`) | Läuft unbegrenzt und übernimmt Sitzungen, sobald sie eintreffen. | | `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | Verarbeitet ein einzelnes beanspruchtes Arbeitselement und kehrt zurück. Übergib die Arbeits-, Sitzungs- und Umgebungskennungen sowie das `work_secret` (typescript: `workSecret`; go: `WorkSecret`) explizit, oder lass es die [`ANTHROPIC_*`-Variablen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-reference#environment-variables) lesen. | | Option | Beschreibung | | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools` (go: `ToolsFunc`) | Eine Factory, die den `AgentToolContext` der Sitzung erhält und die Tool-Liste zurückgibt. Standardmäßig das Standard-Agent-Toolset. | | `memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) | Wie oft angehängte Memory Stores während der Sitzung mit dem Server abgeglichen werden. Siehe [Synchronisierungsintervall](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory#sync-interval). | | `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) | Ob Dateien, die der Agent lokal löscht, auch aus dem Store gelöscht werden. Siehe [Löschungen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory#deletions). | `EnvironmentWorker` verwaltet den `AgentToolContext` und das Toolset automatisch. Übergib eine `tools` (go: `ToolsFunc`)-Factory, um die Tool-Liste anzupassen: ```python Python EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool]) ``` ```typescript TypeScript new EnvironmentWorker({ client, environmentId, environmentKey, tools: (ctx) => [betaBashTool(ctx), myCustomTool] }); ``` Das C#-SDK hat keinen `EnvironmentWorker`. Um Aufrufe benutzerdefinierter Tools aus deinem eigenen Code zu beantworten, sende jedes Ergebnis über den Event-Stream der Sitzung, wie unter [Ein Custom-Tool-Ergebnis zurückgeben](https://platform.claude.com/docs/de/managed-agents/events-and-streaming#return-a-custom-tool-result) beschrieben. ```go Go worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool { return []anthropic.BetaTool{agenttoolset.BetaBashTool(env), myCustomTool} }, }) ``` Das Java-SDK hat keinen `EnvironmentWorker`. Um Aufrufe benutzerdefinierter Tools aus deinem eigenen Code zu beantworten, sende jedes Ergebnis über den Event-Stream der Sitzung, wie unter [Ein Custom-Tool-Ergebnis zurückgeben](https://platform.claude.com/docs/de/managed-agents/events-and-streaming#return-a-custom-tool-result) beschrieben. Das PHP-SDK hat keinen `EnvironmentWorker`. Um Aufrufe benutzerdefinierter Tools aus deinem eigenen Code zu beantworten, sende jedes Ergebnis über den Event-Stream der Sitzung, wie unter [Ein Custom-Tool-Ergebnis zurückgeben](https://platform.claude.com/docs/de/managed-agents/events-and-streaming#return-a-custom-tool-result) beschrieben. Das Ruby-SDK hat keinen `EnvironmentWorker`. Um Aufrufe benutzerdefinierter Tools aus deinem eigenen Code zu beantworten, sende jedes Ergebnis über den Event-Stream der Sitzung, wie unter [Ein Custom-Tool-Ergebnis zurückgeben](https://platform.claude.com/docs/de/managed-agents/events-and-streaming#return-a-custom-tool-result) beschrieben. ### Work-Poller | Option | Beschreibung | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `drain` (go: `Drain`) | Ob das Polling beendet wird, sobald die Warteschlange leer ist, anstatt auf neue Arbeit zu warten. | | `block_ms` (typescript: `blockMs`; go: `BlockMs`) | 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 `null` (python: `None`; go: `param.Null[int64]()`) für eine nicht blockierende Prüfung. Standardmäßig ein Long-Poll von 999 ms. | | `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | Beansprucht Arbeitselemente erneut, die beansprucht, aber innerhalb dieser Anzahl von Millisekunden nie bestätigt wurden. | | `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | Ob für jedes Arbeitselement ein Stoppsignal gesendet wird, sobald dein Schleifenrumpf damit fertig ist. Setze es auf `false` (python: `False`; go: `param.NewOpt(false)`), wenn das, was das Arbeitselement ausführt, den Stopp selbst sendet. `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) 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](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-workers#launch-sandboxes-from-the-sdk-poller). ### Sitzungs-Tool-Runner `client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`) nimmt eine Tool-Liste als `tools` (go: `Tools`) entgegen. Um diese Liste zu erstellen, richte `AgentToolContext` selbst ein und rufe `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`) auf: ```python Python 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// tools = beta_agent_toolset_20260401(env) ``` ```typescript TypeScript import { setupSkills, betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node"; const ctx = { workdir: "/workspace", client, sessionId: work.data.id }; await setupSkills(ctx); const tools = betaAgentToolset20260401(ctx); ``` Das C#-SDK hat keinen `AgentToolContext`. ```go Go env := &agenttoolset.AgentToolContext{Workdir: "/workspace"} if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil { panic(err) } // Skills heruntergeladen nach /workspace/skills// tools := agenttoolset.BetaAgentToolset20260401(env) ``` Das Java-SDK hat keinen `AgentToolContext`. Das PHP-SDK hat keinen `AgentToolContext`. Das Ruby-SDK hat keinen `AgentToolContext`. ### 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` (typescript: `allowedRoots`; go: `AllowedRoots`) | Verzeichnisse, zusätzlich zum Arbeitsverzeichnis, die die Datei-Tools (`read`, `write`, `edit`, `glob`, `grep`) erreichen können. | | `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`) | Verzeichnisse, unterhalb derer `write` und `edit` Pfade ablehnen. | `EnvironmentWorker` fügt die Memory-Store-Verzeichnisse der Sitzung selbst zu `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`) hinzu und die Verzeichnisse von Stores, die mit `access: "read_only"` angehängt sind, zu `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`). Die Eingrenzung ist nur eine Schutzvorkehrung für die Datei-Tools, keine Sandbox. Sie schränkt `bash` nicht ein. `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`) nimmt einen `AgentToolContext` entgegen und gibt die Standard-Tool-Implementierungen (`bash`, `read`, `write`, `edit`, `glob`, `grep`) zurück.