Claude Platform Docs
Managed AgentsSelbst gehostete Sandboxes

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_started aktiviert 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ähigkeitant CLISDK (Python, TypeScript, Go)
Dauerhaft aktives PollingJaJa
Per Webhook ausgelöstNeinJa
Sandbox pro SitzungJaJa
Memory StoresJa, mit Standard-SynchronisierungseinstellungenJa, mit konfigurierbarer Synchronisierung
Benutzerdefinierte ToolsNeinJa

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

  1. 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.

  2. 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_..."
  3. Den Webhook-Handler implementieren

    Starte den Worker, wenn session.status_run_started ausgelöst wird. Der Handler leert die Warteschlange und übergibt jedes übernommene Arbeitselement an handle_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 /workspace als 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.

    Um 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 mit run() pollt, hat das Secret bereits. Dieser Handler beansprucht jedes Arbeitselement selbst und übergibt das Secret daher im Argument work_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

Vorgefertigte selbst gehostete Worker
Die Verfügbarkeitsanforderungen für Vorgefertigte selbst gehostete Worker sind auf allen unterstützten Plattformen gleich.
Status
Beta
API
  • Managed Agents
Beta-Header
Erfordert
Modelle
  • Alle Modelle

Zutreffende Endpunkte

  • /v1/agents
  • /v1/sessions
  • /v1/environments
Zero Data RetentionNicht berechtigt

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

HIPAANicht berechtigt

Nicht für HIPAA berechtigt. Gilt für alle Unterfunktionen von Managed Agents.

War diese Seite hilfreich?