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 die Tool-Ausführung aber in eine Infrastruktur, die du kontrollierst, sodass der Code, das Dateisystem und der ausgehende Netzwerkverkehr des Agenten 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 zu Anthropics Control Plane (wo Claude läuft), damit das Modell Ergebnisse sehen und entscheiden kann, was als Nächstes zu tun ist. Siehe das Sicherheitsmodell für die vollständige Datenfluss-Grenze.



Wie es sich von Cloud-Umgebungen unterscheidet

Self-Hosting ist eine gute Wahl, 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 soll.

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



Wann du mit MCP-Tunneln kombinieren solltest

Self-Hosting steuert, wo der Code des Agenten 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 weiterhin private MCP-Server über einen Tunnel erreichen, und eine selbst gehostete Session kann entweder getunnelte oder öffentliche MCP-Server verwenden. Verwende beides, wenn du möchtest, dass sowohl Ausführung als auch Tool-Zugriff innerhalb deiner Grenze bleiben. Um dem Agenten Tools von einem MCP-Server innerhalb deines Netzwerks zu geben, ohne einen Tunnel zu betreiben, kannst du den Server auch als Custom Tools kapseln, die von deinem Worker bereitgestellt werden.



Environment-Worker

Ein „environment worker" (Umgebungs-Worker) ist ein Prozess, den du auf deiner eigenen Infrastruktur betreibst. 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, startet für jedes einen Ausführungskontext, lädt die Skills des Agenten herunter (wiederverwendbare, dateisystembasierte Ressourcen, die dem Agenten 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.

Die CLI und das SDK liefern beide 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-Helfer 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 systemseitige 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 Agenten, damit Claude die Skill-Dateien finden kann.
• Outputs: In selbst gehosteten Umgebungen lässt der System-Prompt der Session die /mnt/session/outputs-Anweisung weg, die in 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 Agenten. Wenn du keinen hast, schließe zuerst den Schnellstart ab und notiere dir dessen Agent-ID.
• Einen Linux-Host mit /bin/bash unter 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 neuer; die Python- und Go-SDKs verwenden ihre Standardbibliotheken für die Archiv-Extraktion und haben keine zusätzlichen Binär-Anforderungen.
• Die ant-CLI oder ein Anthropic-SDK (Python, TypeScript oder Go) auf dem Worker-Host.
• Zwei Zugangsdaten: Ein Environment-Key (in den folgenden Schritten in der Console generiert) authentifiziert den Worker gegenüber seiner Warteschlange; dein Claude-API-Key erstellt Sessions und liest Warteschlangen-Statistiken von außerhalb des Worker-Hosts. Die Key-Generierung ist nur über die Console möglich.



Einen Worker ausführen

Wähle Always-on für das einfachste Setup: Ein langlaufender Prozess pollt die Warteschlange kontinuierlich und benötigt nur ausgehendes HTTPS. Wähle Webhook-getriggert, um keinen untätigen Poller laufen zu lassen; dies erfordert einen Webhook-Endpunkt, den Anthropic erreichen kann (siehe Webhooks für Endpunkt-Einrichtung und Signaturverifizierung).



SDK-Helfer

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

• EnvironmentWorker: der sofort einsatzbereite Worker. Übernimmt Polling, Setup und Ausführung von Anfang bis Ende.
  • .run(): läuft unbegrenzt und nimmt Sessions auf, sobald sie eintreffen.
  • .handle_item(): bearbeitet ein einzelnes beanspruchtes Work Item und beendet sich. Übergib die Work-, Session- und Environment-Bezeichner explizit oder lass ihn die ANTHROPIC_*-Variablen lesen, die ant beta:worker poll --on-work für den von ihm gestarteten Prozess setzt.
• work.poller(): pollt die Arbeitswarteschlange für dich und gibt 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 gestoppt werden soll, sobald die Warteschlange leer ist, statt auf neue Arbeit zu warten.
  • block_ms: wie lange auf das Eintreffen von Arbeit gewartet werden soll, bevor zurückgekehrt wird, in Millisekunden. Muss zwischen 1 und 999 liegen (Wartezeit pro Poll; der Helfer 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: beansprucht Work Items erneut, die beansprucht, aber nicht innerhalb dieser Anzahl von Millisekunden bestätigt wurden.
  • auto_stop: ob für jedes Work Item ein Stopp-Signal gesendet werden soll, sobald dein Schleifenkörper damit fertig ist. Der Go-Poller hat keine Opt-out-Möglichkeit und sendet das Stopp-Signal immer, blockiere also 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 Sandbox-Launcher pro Session. Ü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 Pfad-Richtlinie 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 auf deinen Claude-API-Key gesetzt (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 dir in Bevor du beginnst notiert hast. Die Session tritt in die Arbeitswarteschlange der Umgebung ein und wartet dort, bis ein Worker sie beansprucht; wenn kein Worker verbunden ist, bleibt die Session in der Warteschlange, statt fehlzuschlagen.

Anthropic bindet keine Dateien oder GitHub-Repositories in selbst gehostete Sandboxes ein. 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 enthält nicht die Metadaten der Session, aber es enthält 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-Helfer für die SDK-Helfer-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 innerhalb deiner Sandbox läuft, erreicht das Tool die internen Dienste, Zugangsdaten und den ausgehenden Netzwerkverkehr, 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 liegt.

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



Einen MCP-Server als Custom Tools kapseln

Der MCP-Connector verbindet sich von Anthropics Seite aus mit MCP-Servern, daher muss ein Server einen HTTP-Endpunkt bereitstellen, 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 Agenten deklarierst, die Eingabe jedes Aufrufs und das Ergebnis, das dein Worker zurücksendet. Zur Laufzeit ruft das Modell ein gekapseltes Tool wie jedes andere Custom Tool auf:

1. Der Agent gibt ein agent.custom_tool_use-Event aus.
2. Der Worker, innerhalb deiner Sandbox, leitet 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 clientseitigen MCP-Helfer 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 Zugangsdaten 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 kapselst:

• 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 Agenten oder auf einer untätigen Session über Aktualisieren der Agent-Konfiguration, 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 Beschreibung ist erforderlich (1–4.096 Zeichen); und das tools-Array eines Agenten nimmt höchstens 128 Einträge auf (jedes gekapselte 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-Helfer behalten die Namen und Beschreibungen des Servers bei, benenne also um oder kürze, wo nötig. Wenn zwei Server denselben Tool-Namen bereitstellen, definiere den Wrapper selbst unter einem Namen mit Präfix 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 außerdem oneOf, anyOf und allOf auf oberster Ebene ab sowie Eigenschaftsnamen außerhalb von Buchstaben, Ziffern, Unterstrichen, Punkten und Bindestrichen (1–64 Zeichen).
• Tool-Fehler erscheinen als Fehler-Tool-Ergebnisse. 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, erscheinen ebenfalls als Fehler. Setze einen Timeout auf dem MCP-Client für einen schnelleren und klareren Fehlschlag, wie es das Python-Worker-Beispiel mit read_timeout_seconds tut. Ohne einen solchen wird ein hängender Aufruf erst dann zu einem Fehlerergebnis, wenn der Standard-Request-Timeout des TypeScript-MCP-SDK 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.
• Kapsle Server, die du betreibst oder denen du vertraust. Name, Beschreibung und Ergebnisse eines gekapselten 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 tut, 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 gekapselten 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 Betriebs-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-Helfer 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-Helfer bestätigen jedes Item, bevor sie es verarbeiten, daher bleibt dieser Wert im Normalbetrieb nahe null; ein anhaltend von null verschiedener Wert bedeutet, dass ein Worker zwischen Beanspruchen und Bestätigen hängen geblieben ist.
• oldest_queued_at ist der Zeitstempel des ältesten Items, das sich noch in der Warteschlange befindet und darauf wartet, beansprucht zu werden, oder beansprucht, aber noch nicht bestätigt wurde, 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-Alarmierung.

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äß stoppen

Verwende work.stop, um den Worker, der eine bestimmte Session bearbeitet, aufzufordern, sie herunterzufahren. Standardmäßig wechselt das Work-Item in den Zustand 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 in den Zustand stopped übergeht. Übergib force: true im Request-Body (mit der CLI übergibst du --force), um das Work-Item sofort als stopped zu markieren, anstatt auf die Bestätigung des Workers zu warten.

Da diese Aufrufe von deinem Operations-Tooling und nicht vom Worker-Host 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