Selbst gehostete Worker bereitstellen
Wähle, wie selbst gehostete Sandbox-Worker Arbeit beanspruchen und wo Sitzungen laufen, und führe dann einen dauerhaft aktiven Worker aus oder löse Worker über Webhooks aus.
Der Schnellstart für selbst gehostete Sandboxes führt einen ant-CLI-Worker aus, der kontinuierlich pollt und jede Sitzung in einem Prozess ausführt. Diese Seite hilft dir, ein Bereitstellungsmuster zu wählen, und behandelt dann dauerhaft aktive und per Webhook ausgelöste Worker.
Ein Bereitstellungsmuster wählen
Beim Bereitstellen von Workern musst du zwei Entscheidungen treffen: wie der Worker Arbeit beansprucht und wo jede Sitzung läuft.
Wie der Worker Arbeit beansprucht:
- Dauerhaft aktiv: Ein langlebiger Prozess pollt die Warteschlange kontinuierlich. Der Prozess sendet nur ausgehende HTTPS-Anfragen, sodass du keinen Endpunkt für Anthropic freigibst.
- Per Webhook ausgelöst: Ein Handler wird bei
session.status_run_startedaktiviert und beginnt mit dem Polling. Dadurch wird ein untätiger Poller vermieden, es ist jedoch ein Webhook-Endpunkt erforderlich, den Anthropic erreichen kann.
Wo jede Sitzung läuft:
- Im Prozess: Der Worker, der eine Sitzung beansprucht, führt auch deren Tool-Aufrufe aus, in einem gemeinsamen Arbeitsverzeichnis.
- Sandbox pro Sitzung: Ein Poller startet für jede beanspruchte Sitzung eine neue Sandbox. Wähle dies für stärkere Isolation: ein frisches Dateisystem, Ressourcenlimits oder Netzwerkkontrollen pro Sitzung. Siehe Eine Sandbox pro Sitzung ausführen, wo auch das Helm-Chart für Kubernetes behandelt wird.
Die CLI- und SDK-Worker unterstützen unterschiedliche Kombinationen:
| Fähigkeit | ant CLI | SDK (Python, TypeScript, Go) |
|---|---|---|
| Dauerhaft aktives Polling | Ja | Ja |
| Per Webhook ausgelöst | Nein | Ja |
| Sandbox pro Sitzung | Ja | Ja |
| Memory Stores | Ja, mit Standard-Synchronisierungseinstellungen | Ja, mit konfigurierbarer Synchronisierung |
| Benutzerdefinierte Tools | Nein | Ja |
Siehe Referenz für selbst gehostete Worker für jedes CLI-Flag und jede SDK-Option.
Für mehr Kontrolle rufe die Environments-Work-Endpunkte direkt auf und implementiere deinen eigenen Worker. Dein Worker übernimmt dann die Aufgaben der SDK-Worker. Unter anderem bestätigt er jedes Arbeitselement, sendet Heartbeats und lädt die Skills des Agenten herunter. Er führt nur die Tool-Aufrufe aus, die die „permission policy“ (Berechtigungsrichtlinie) der Sitzung erlaubt. Er gibt jedes Ergebnis als user.tool_result- oder user.custom_tool_result-Event zurück. Am Ende stoppt er das Arbeitselement. Verwende den Quellcode des Workers im Python-SDK, im TypeScript-SDK oder im Go-SDK als Referenz.
Einen dauerhaft aktiven Worker ausführen
Diese Beispiele verwenden /workspace als Arbeitsverzeichnis des Workers. Das Verzeichnis muss existieren, bevor der Worker startet. Erstelle es auf einem neuen Host und gib dem Benutzer des Workers Schreibzugriff, wie im Schritt „Den Worker starten“ von Deine erste Sitzung ausführen.
Unter macOS kann mkdir das Verzeichnis /workspace nicht erstellen, weil das Root-Volume schreibgeschützt ist. Erstelle stattdessen ~/workspace, wie es dieser Schritt zeigt. Verwende anstelle von /workspace den vollständigen Pfad, den echo ~/workspace ausgibt, da das SDK ~ nicht expandiert.
Starte einen Worker, der die Warteschlange kontinuierlich pollt. Er authentifiziert sich mit dem Umgebungsschlüssel aus dem Schnellstart:
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
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,
workdir="/workspace",
)
task = asyncio.create_task(worker.run())
# Das Abbrechen des Tasks statt des Beendens des Prozesses lässt den Worker sein
# laufendes Arbeitselement stoppen und geänderte Memory-Dateien hochladen, bevor er beendet wird.
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())Worker über Webhooks auslösen
Sitzungs-Webhooks abonnieren
Definiere in der Claude Console einen Webhook-Endpunkt, der auf
session.status_run_started-Events hört. Siehe Webhooks abonnieren für Details.Den Webhook-Signaturschlüssel exportieren
Exportiere zusammen mit der Environment-ID und dem Key aus Deine erste Sitzung ausführen den Webhook-Signaturschlüssel auf deinem Handler-Host. Der Handler verwendet ihn, um eingehende Payloads zu verifizieren.
export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."Den Webhook-Handler implementieren
Starte den Worker, wenn
session.status_run_startedausgelöst wird. Der Handler leert die Warteschlange und übergibt jedes übernommene Arbeitselement anhandle_item()(in den Python-, TypeScript- und Go-SDKs). Diese Methode lädt Skills herunter, führt Tool-Aufrufe aus, sendet Ergebnisse zurück und kehrt zurück.Die Beispiele verwenden
/workspaceals Arbeitsverzeichnis. Bevor du den Handler startest, erstelle dieses Verzeichnis auf dem Handler-Host. Stelle sicher, dass der Benutzer des Handlers in das Verzeichnis schreiben kann, wie im Schritt „Den Worker starten“ von Deine erste Sitzung ausführen.PythonUm Webhook-Signaturen zu verifizieren, installiere das Webhooks-Extra:
pip install "anthropic[webhooks]".import asyncio import os import anthropic import standardwebhooks # installed by the anthropic[webhooks] extra environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"] environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"] client = anthropic.AsyncAnthropic( auth_token=environment_key, ) # Wird von shutdown() abgebrochen, damit ein laufendes Arbeitselement geänderte Memory-Dateien hochladen und # seine Store-Verzeichnisse entfernen kann, bevor der Prozess endet. inflight: set[asyncio.Task[None]] = set() # Rufe dies mit await im Shutdown-Hook des Hosts auf, etwa beim ASGI-Lifespan-Shutdown (der Code nach # `yield` in einem FastAPI-Lifespan), den uvicorn bei SIGTERM ausführt. uvicorn lässt offene Requests # abschließen, bevor dieser Hook läuft; setze daher --timeout-graceful-shutdown, um die Wartezeit zu begrenzen. async def shutdown() -> None: for task in inflight: task.cancel() await asyncio.gather(*inflight, return_exceptions=True) async def handle(raw: bytes, headers: dict[str, str]) -> tuple[dict[str, str], int]: try: event = client.beta.webhooks.unwrap(raw.decode(), headers=headers) except standardwebhooks.WebhookVerificationError: return {"error": "signature verification failed"}, 401 if event.data.type != "session.status_run_started": return {"status": "ignored"}, 200 task = asyncio.create_task(run_queued_work()) inflight.add(task) task.add_done_callback(inflight.discard) try: # Abgeschirmt: Eine abgebrochene oder zeitüberschrittene Zustellung darf das Element nicht abbrechen; das tut shutdown(). await asyncio.shield(task) except asyncio.CancelledError: return {"status": "shutting down"}, 503 return {"status": "ok"}, 200 async def run_queued_work() -> None: async for work in client.beta.environments.work.poller( environment_id=environment_id, environment_key=environment_key, block_ms=None, reclaim_older_than_ms=2000, drain=True, auto_stop=False, ): await client.beta.environments.work.worker(workdir="/workspace").handle_item( work_id=work.id, environment_id=environment_id, session_id=work.data.id, environment_key=environment_key, # Über das Secret pro Sitzung kann der Worker die Memory-Stores der Sitzung einbinden. work_secret=work.secret, )In den Python-, TypeScript- und Go-SDKs benötigt
handle_item()das Secret des Arbeitselements, um Memory Stores einzubinden. Ein Worker, der mitrun()pollt, hat das Secret bereits. Dieser Handler beansprucht jedes Arbeitselement selbst und übergibt das Secret daher im Argumentwork_secret. Siehe Das Secret des Arbeitselements weiterleiten.
Dieser Handler führt jedes beanspruchte Arbeitselement in einem Prozess aus, und er führt Arbeitselemente aus separaten Webhook-Zustellungen gleichzeitig aus. Diese Sitzungen teilen sich ein Dateisystem, einschließlich /workspace und /mnt/memory. Wenn deine Sitzungen denselben Memory Store anhängen, siehe Sitzungen isolieren, die sich einen Store teilen.
Nächste Schritte
Starte Sandboxes mit dem Helm-Chart auf Kubernetes, einem Spawn-Skript oder dem SDK-Poller.
Lies die Warteschlangentiefe aus, stoppe Sitzungen und Worker sauber und behebe häufige Fehler.
Modell der geteilten Verantwortung für selbst gehostete Sandbox-Umgebungen.
Verfügbarkeit
Claude API
- Status
- Beta
- API
- Managed Agents
- Beta-Header
- Erfordert
- Modelle
- Alle Modelle
Claude Platform on AWS
- Status
- Beta
- API
- Managed Agents
- Beta-Header
- Erfordert
- Modelle
- Alle Modelle
Datenverarbeitung
Übersicht über die DatenverarbeitungZutreffende Endpunkte
/v1/agents/v1/sessions/v1/environments
Nicht für ZDR berechtigt, außer bei selbst gehosteten Managed Agents. Sitzungen sind zustandsbehaftete Ressourcen; Transkripte bleiben erhalten, bis du sie löschst. Mehr erfahren
Nicht für HIPAA berechtigt. Gilt für alle Unterfunktionen von Managed Agents.
War diese Seite hilfreich?