Selbst gehostete Sandboxes

Standardmäßig führt Managed Agents Tools und Code in von Anthropic verwalteten Cloud-Sandboxes aus. Selbst gehostete Sandboxes belassen die Orchestrierung auf Anthropics Seite, verlagern aber die Tool-Ausführung in Infrastruktur, die du kontrollierst, sodass der Code des Agents, das Dateisystem und der Netzwerk-Egress deine Umgebung nie verlassen.

Die Tool-Ausführung bleibt auf deinem Host: das Dateisystem, das der Agent liest und schreibt, die Prozesse, die er startet, und das Netzwerk, das er erreichen kann, stehen alle unter deiner Kontrolle. Tool-Eingaben und -Ausgaben fließen weiterhin zur Control Plane von Anthropic (wo Claude läuft), damit das Modell die Ergebnisse sehen und entscheiden kann, was als Nächstes zu tun ist. Siehe das Sicherheitsmodell für die vollständige Datenflussgrenze.



Unterschiede zu Cloud-Umgebungen

Self-Hosting eignet sich gut, wenn der Agent mit Daten arbeiten muss, die deine Netzwerkgrenze nicht verlassen dürfen, interne Dienste erreichen muss, die nicht öffentlich routbar sind, oder unter den eigenen Compliance- und Audit-Kontrollen deiner Organisation laufen muss.

Für Zero Data Retention und HIPAA-BAA-Eignung siehe API und Datenspeicherung.



Wann mit MCP-Tunneln kombinieren

Self-Hosting steuert, wo der Code des Agents ausgeführt wird. MCP-Tunnel steuern, wie Anthropic MCP-Server in deinem Netzwerk erreicht. Sie sind unabhängig voneinander: Eine Session, die in Anthropics Cloud-Sandboxes läuft, kann private MCP-Server trotzdem über einen Tunnel erreichen, und eine selbst gehostete Session kann entweder getunnelte oder öffentliche MCP-Server verwenden. Verwende beides, wenn sowohl Ausführung als auch Tool-Zugriff innerhalb deiner Grenze bleiben sollen. Um dem Agent Tools von einem MCP-Server in deinem Netzwerk zu geben, ohne einen Tunnel zu betreiben, kannst du den Server auch als Custom Tools wrappen, die von deinem Worker bereitgestellt werden.



Environment Worker

Ein Environment Worker ist ein Prozess, den du auf deiner eigenen Infrastruktur ausführst. Er empfängt Tool-Ausführungsanfragen von Anthropic und führt sie lokal aus. Die self_hosted-Umgebung fungiert als Arbeitswarteschlange: Wenn ihr eine Session zugewiesen wird, stellt Anthropic die Session als Work Item in die Warteschlange. Dein Worker beansprucht Work Items aus dieser Warteschlange, erzeugt für jedes einen Ausführungskontext, lädt die Skills des Agents herunter (wiederverwendbare, dateisystembasierte Ressourcen, die dem Agent domänenspezifisches Fachwissen geben), führt die Tool-Aufrufe aus und sendet die Ergebnisse zurück.

Work Items werden durch Polling der Warteschlange der Umgebung beansprucht: entweder durch einen Always-on-Worker, der kontinuierlich pollt, oder einen Webhook-getriggerten Handler, der bei session.status_run_started aufwacht und mit dem Polling beginnt.

Sowohl die CLI als auch das SDK liefern vorgefertigte Worker mit. Die ant-CLI unterstützt nur das Always-on-Muster; das SDK unterstützt sowohl Always-on als auch Webhook-getriggert. Beide sind konfigurierbar: siehe Self-hosted Worker in der Referenz für CLI-Flags und SDK-Helper auf dieser Seite für die SDK-Optionen. Für mehr Kontrolle rufe die Environments-Work-Endpunkte direkt auf und implementiere deinen eigenen Worker.



Sandbox-Dateisystem

• /workspace: das systemweite Standard-Arbeitsverzeichnis für Tool-Ausführung und Skill-Download. Das --workdir-Flag der CLI verwendet standardmäßig das aktuelle Verzeichnis; übergib --workdir /workspace, um dem Systemstandard zu entsprechen. Skills werden nach <workdir>/skills/<name>/ heruntergeladen. Wenn du ein anderes Arbeitsverzeichnis verwendest, aktualisiere den System-Prompt deines Agents, damit Claude die Skill-Dateien finden kann.
• Outputs: Bei selbst gehosteten Umgebungen lässt der System-Prompt der Session die /mnt/session/outputs-Anweisung weg, die bei von Anthropic verwalteten Sandboxes verwendet wird, sodass finale Ergebnisse dort landen, wo der Agent sie in deinem Sandbox-Dateisystem schreibt, typischerweise unterhalb des Arbeitsverzeichnisses.



Bevor du beginnst

Du benötigst:

• Einen bestehenden Agent. Wenn du keinen hast, schließe zuerst den Quickstart ab und notiere dir seine Agent-ID.
• Einen Linux-Host mit /bin/bash an genau diesem Pfad. Das Bash-Tool des Workers ruft es direkt auf, ohne PATH zu konsultieren. Das TypeScript-SDK benötigt zusätzlich unzip und tar im PATH sowie Node.js 22 oder höher; die Python- und Go-SDKs verwenden ihre Standardbibliotheken für die Archivextraktion und haben keine zusätzlichen Binary-Anforderungen.
• Die ant-CLI oder ein Anthropic-SDK (Python, TypeScript oder Go) auf dem Worker-Host.
• Zwei Credentials: Ein Environment Key (in der Console in den folgenden Schritten generiert) authentifiziert den Worker gegenüber seiner Warteschlange; dein Claude-API-Key erstellt Sessions und liest Warteschlangenstatistiken von außerhalb des Worker-Hosts. Die Key-Generierung ist nur in der Console möglich.



Einen Worker ausführen

Wähle Always-on für das einfachste Setup: Ein lang laufender Prozess pollt die Warteschlange kontinuierlich und benötigt nur ausgehendes HTTPS. Wähle Webhook-getriggert, um das Betreiben eines Idle-Pollers zu vermeiden; dies erfordert einen Webhook-Endpunkt, den Anthropic erreichen kann (siehe Webhooks für Endpunkt-Setup und Signaturverifizierung).



SDK-Helper

Das SDK bietet drei Helper auf unterschiedlichen Kontrollebenen. EnvironmentWorker deckt die meisten Anwendungsfälle ab; greife auf die Low-Level-Helper zurück, wenn du deinen eigenen Prozess pro Session starten oder Tools gegen eine bereits beanspruchte Session ausführen musst.

• EnvironmentWorker: der Out-of-the-Box-Worker. Übernimmt Polling, Setup und Ausführung von Anfang bis Ende.
  • .run(): läuft unbegrenzt und nimmt Sessions auf, sobald sie eintreffen.
  • .handle_item(): verarbeitet ein einzelnes beanspruchtes Work Item und beendet sich. Übergib die Work-, Session- und Environment-Identifier explizit oder lass sie aus den ANTHROPIC_*-Variablen lesen, die ant beta:worker poll --on-work für den gestarteten Prozess setzt.
• work.poller(): pollt die Arbeitswarteschlange für dich und übergibt dir jede beanspruchte Session. Verwende dies, wenn du entscheiden möchtest, was für jede Session passiert, zum Beispiel das Starten einer Sandbox statt der In-Process-Ausführung von Tools.
  • drain: ob das Polling beendet werden soll, sobald die Warteschlange leer ist, statt auf neue Arbeit zu warten.
  • block_ms: wie lange auf eintreffende Arbeit gewartet werden soll, bevor zurückgekehrt wird, in Millisekunden. Muss zwischen 1 und 999 liegen (Wartezeit pro Poll; der Helper pollt automatisch erneut). Übergib null (None in Python, param.Null[int64]() in Go) für eine nicht-blockierende Prüfung; das Weglassen des Parameters verwendet den Standard-Long-Poll von 999 ms.
  • reclaim_older_than_ms: beanspruche Work Items erneut, die beansprucht, aber innerhalb dieser Anzahl von Millisekunden nie bestätigt wurden.
  • auto_stop: ob für jedes Work Item ein Stop-Signal gesendet werden soll, sobald dein Schleifenkörper damit fertig ist. Der Go-Poller hat kein Opt-out und sendet das Stop-Signal immer, also blockiere im Schleifenkörper, bis die Session abgeschlossen ist, statt dich abzukoppeln.
• client.beta.sessions.events.tool_runner(): führt Tool-Aufrufe für eine einzelne Session aus, gegeben die Session-ID und eine Tool-Liste. Verwende dies, wenn du die Arbeit bereits beansprucht hast und nur die Ausführungsschicht benötigst.

Verwende den Work-Poller direkt, wenn du deinen eigenen Prozess pro Session starten möchtest, zum Beispiel das Hochfahren einer Sandbox für jede beanspruchte Session:

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Ersetze dies durch deinen eigenen sitzungsbezogenen Sandbox-Launcher. Übergib
    # ANTHROPIC_ENVIRONMENT_KEY an die gestartete Sandbox, niemals
    # deinen API-Key.
    print(f"claimed session {work.data.id}")


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:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

AgentToolContext ist der Ausführungskontext für Tool-Aufrufe. Er definiert das Arbeitsverzeichnis und die Pfadrichtlinie und kann die Skills der Session herunterladen. beta_agent_toolset_20260401(env) nimmt einen AgentToolContext entgegen und gibt die Standard-Tool-Implementierungen zurück (bash, read, write, edit, glob, grep).

Mit EnvironmentWorker: beide werden automatisch verwaltet. Übergib eine tools-Factory, um die Tool-Liste anzupassen:

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

Mit work.poller() und tool_runner(): übergib eine Tool-Liste als tools an client.beta.sessions.events.tool_runner(). 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)



Überprüfe, ob der Worker verbunden ist

Bestätige von einer separaten Shell aus, mit ANTHROPIC_API_KEY gesetzt auf deinen Claude-API-Key (nicht den Environment Key), dass workers_polling mindestens 1 ist:

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

Wenn workers_polling bei 0 bleibt, erreicht der Worker die Warteschlange nicht: Bestätige, dass ANTHROPIC_ENVIRONMENT_KEY und ANTHROPIC_ENVIRONMENT_ID auf dem Worker-Host gesetzt sind. Siehe Warteschlangentiefe lesen für die vollständige Stats-Antwort und Beispiele in anderen Sprachen.



Eine Session starten

Sobald dein Worker läuft, erstelle eine Session, die auf die Umgebung abzielt. Setze AGENT_ID auf die Agent-ID, die du in Bevor du beginnst notiert hast. Die Session gelangt in die Arbeitswarteschlange der Umgebung und wartet dort, bis ein Worker sie beansprucht; wenn kein Worker verbunden ist, bleibt die Session in der Warteschlange, statt fehlzuschlagen.

Anthropic mountet keine Dateien oder GitHub-Repositories in selbst gehostete Sandboxes. Um sessionspezifische Dateien verfügbar zu machen, übergib Dateireferenzen (wie einen S3-Pfad oder Commit-SHA) im metadata-Feld der Session. Das beanspruchte Work Item trägt nicht die Metadaten der Session, aber es trägt die Session-ID: Dein Spawn-Skript oder --on-work-Handler ruft die Session ab (GET /v1/sessions/{session_id}), um das metadata-Feld zu lesen, und stellt dann die Dateien im Arbeitsverzeichnis bereit, bevor die Tool-Ausführung beginnt.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

Siehe Self-hosted Worker in der Referenz für die vollständige Liste der CLI-Flags und SDK-Helper für die SDK-Helper-Optionen.



Custom Tools aus deiner Sandbox bereitstellen

Custom Tools sind Tools, die dein eigener Code ausführt: Der Agent gibt ein agent.custom_tool_use-Event aus und wartet auf ein passendes user.custom_tool_result. Der Worker kann dieser Code sein, und weil er in deiner Sandbox läuft, erreicht das Tool die internen Dienste, Credentials und den Netzwerk-Egress, die du für die Sandbox konfiguriert hast, und nichts darüber hinaus. Der Environment Key autorisiert das Senden von Custom-Tool-Ergebnissen, sodass dein Claude-API-Key nicht auf dem Worker-Host liegen muss.

Der Worker beantwortet nur die bei ihm registrierten Tools. Ein Custom Tool, das auf dem Agent deklariert, aber bei keinem Worker oder Client registriert ist, lässt die Session mit einem requires_action-Stop-Reason pausieren, bis etwas sein Ergebnis sendet; siehe Custom-Tool-Aufrufe verarbeiten für den Event-Ablauf.



Einen MCP-Server als Custom Tools wrappen

Der MCP-Connector verbindet sich von Anthropics Seite aus mit MCP-Servern, sodass ein Server einen HTTP-Endpunkt bereitstellen muss, den Anthropic erreichen kann, direkt oder über einen MCP-Tunnel. Um einen Server zu verwenden, den nur dein Netzwerk erreichen kann, mache stattdessen den Worker zum MCP-Client und deklariere die Tools des Servers als Custom Tools. Der MCP-Server benötigt keine eingehende Konnektivität von außerhalb deines Netzwerks; Anthropic erhält die Tool-Definitionen, die du auf dem Agent deklarierst, die Eingabe jedes Aufrufs und das Ergebnis, das dein Worker zurücksendet. Zur Laufzeit ruft das Modell ein gewrapptes Tool wie jedes andere Custom Tool auf:

1. Der Agent gibt ein agent.custom_tool_use-Event aus.
2. Der Worker leitet innerhalb deiner Sandbox den Aufruf über seine offene MCP-Session an den Server in deinem Netzwerk weiter.
3. Der Worker sendet die Antwort des Servers als user.custom_tool_result.

Die Client-seitigen MCP-Helper der SDKs konvertieren die Tools des Servers in die ausführbaren Tools, die der Worker akzeptiert; installiere ein MCP-SDK neben dem Anthropic-SDK (pip install "anthropic[mcp]" "mcp>=1.24", npm install @modelcontextprotocol/sdk, go get github.com/modelcontextprotocol/go-sdk). Die Beispiele verbinden sich ohne Authentifizierung; um Credentials zu senden, konfiguriere den HTTP-Client oder die Request-Optionen, die du dem MCP-Transport übergibst (http_client in Python, requestInit in TypeScript, HTTPClient in Go).

Beachte Folgendes, wenn du einen MCP-Server wrappst:

• Tools werden deklariert, nicht zur Laufzeit entdeckt. Der Worker listet die Tools des MCP-Servers einmal beim Start auf und kann einer laufenden Session keine Tools hinzufügen. Wenn sich die Tools des Servers ändern, deklariere sie erneut, auf dem Agent oder auf einer inaktiven Session über Agent-Konfiguration aktualisieren, und starte den Worker neu.
• Namen und Beschreibungen müssen zur Managed-Agents-API passen. Custom-Tool-Namen sind pro Agent eindeutig und verwenden Buchstaben, Ziffern, Unterstriche und Bindestriche (1–128 Zeichen); eine nicht-leere Beschreibung ist erforderlich; und das tools-Array eines Agents nimmt höchstens 128 Einträge auf (jedes gewrappte Tool ist ein Eintrag, und das eingebaute Toolset ist ein weiterer). Die API lehnt eine Deklaration ab, die einen Tool-Namen wiederverwendet, ein Custom Tool nach einem eingebauten Agent-Tool wie bash oder read benennt oder das reservierte mcp__-Präfix verwendet. Die MCP-Helper behalten die Namen und Beschreibungen des Servers bei, also benenne um oder kürze, wo nötig. Wenn zwei Server denselben Tool-Namen bereitstellen, definiere den Wrapper selbst unter einem präfixierten Namen und lass ihn den ursprünglichen Tool-Namen des Servers aufrufen.
• Die meisten Schemas werden unverändert durchgereicht. Die API akzeptiert die JSON-Schema-Schlüsselwörter, die MCP-Server üblicherweise ausgeben, wie additionalProperties und title. Sie lehnt Referenz-Schlüsselwörter wie $ref überall im input_schema eines Custom Tools ab, also inline die Schemas, die Generatoren wie pydantic in $defs auslagern. Sie lehnt auch oneOf, anyOf und allOf auf oberster Ebene ab sowie Property-Namen außerhalb von Buchstaben, Ziffern, Unterstrichen, Punkten und Bindestrichen (1–64 Zeichen).
• Tool-Fehler tauchen als Fehler-Tool-Ergebnisse auf. Wenn der MCP-Server einen Tool-Fehler meldet, sendet der Worker ein Fehler-Tool-Ergebnis, auf das das Modell reagieren kann. MCP-Inhalte ohne Tool-Ergebnis-Äquivalent, wie Audio-Blöcke und Ressourcen-Links, tauchen ebenfalls als Fehler auf. Setze ein Timeout auf dem MCP-Client für einen schnelleren und klareren Fehler, wie es das Python-Worker-Beispiel mit read_timeout_seconds tut. Ohne eines wird ein hängender Aufruf erst dann zu einem Fehlerergebnis, wenn das Standard-Request-Timeout des TypeScript-MCP-SDKs auslöst (etwa eine Minute) oder wenn der eigene Backstop des Workers greift: etwa zweieinhalb Minuten in Python und zwei Minuten in Go, wo der Worker einen Tool-Aufruf abbricht, der seinen 120-Sekunden-Standard überschreitet, und ein Fehlerergebnis sendet.
• Wrappe Server, die du betreibst oder denen du vertraust. Name, Beschreibung und Ergebnisse eines gewrappten Tools gelangen wie bei jedem anderen Tool in den Kontext des Modells: nicht vertrauenswürdige Eingaben, die beeinflussen können, was der Agent mit seinen anderen Tools macht, einschließlich bash auf dem Worker-Host. Deklariere nur die Tools, die der Agent verwenden soll.
• Berechtigungsrichtlinien gelten nicht für Custom Tools. Berechtigungsrichtlinien regeln die eingebauten und MCP-Toolsets; der Worker führt jeden gewrappten Tool-Aufruf aus, den das Modell macht, also baue jeden Genehmigungsschritt in deinen eigenen Tool-Code ein.



Monitoring und Betrieb

Diese Aufrufe laufen von deinem Monitoring- oder Operations-Tooling aus, authentifiziert mit deinem Claude-API-Key, um die Worker-Flotte zu beobachten und zu verwalten. Die Claim- und Keep-Alive-Schleife wird innerhalb der Worker-Helper abgewickelt, sodass du diese Endpunkte nicht direkt aufrufst.



Warteschlangentiefe lesen

work.stats gibt den Warteschlangenzustand für eine Umgebung zurück:

• depth ist die Anzahl der Items, die darauf warten, beansprucht zu werden. Skaliere deine Worker-Flotte oder alarmiere bei Rückstau basierend auf diesem Wert.
• pending ist die Anzahl der Items, die von einem Worker beansprucht, aber noch nicht bestätigt wurden. Die Worker-Helper bestätigen jedes Item, bevor sie es verarbeiten, sodass dieser Wert im Normalbetrieb nahe null bleibt; ein anhaltend von null abweichender Wert bedeutet, dass ein Worker zwischen Beanspruchen und Bestätigen hängen geblieben ist.
• oldest_queued_at ist der Zeitstempel des ältesten Items, das noch in der Warteschlange ist, wartend auf Beanspruchung oder beansprucht, aber noch nicht bestätigt, oder null, wenn es keines gibt.
• workers_polling ist die Anzahl der Worker, die in den letzten 30 Sekunden gepollt haben. Verwende dies für Liveness-Alerting.

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 Session ordnungsgemäß beenden

Verwende work.stop, um den Worker, der eine bestimmte Session bearbeitet, aufzufordern, diese herunterzufahren. Standardmäßig wechselt das Work-Item in den Status stopping: Der Worker bemerkt dies bei seinem nächsten Lease-Heartbeat, bricht den laufenden Tool-Aufruf der Session ab und bestätigt das Herunterfahren, woraufhin das Work-Item den Status stopped erhält. Übergib force: true im Request-Body (mit der CLI übergib --force), um das Work-Item sofort als stopped zu markieren, anstatt auf die Bestätigung des Workers zu warten.

Da diese Aufrufe von deinen Operations-Tools und nicht vom Worker-Host aus ausgeführt werden, wird ANTHROPIC_WORK_ID nicht automatisch gesetzt. Setze sie auf die ID des Ziel-Work-Items, bevor du die folgenden Beispiele ausführst. Um die ID eines Work-Items zu finden, liste die Work-Items 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)



Nächste Schritte