Déployer des workers auto-hébergés
Choisissez comment les workers de sandbox auto-hébergés réclament le travail et où les sessions s’exécutent, puis exécutez un worker toujours actif ou déclenchez des workers à partir de webhooks.
Le démarrage rapide des sandboxes auto-hébergées exécute un worker de la CLI ant qui interroge la file en continu et exécute chaque session dans un seul processus. Cette page vous aide à choisir un modèle de déploiement, puis présente les workers toujours actifs et les workers déclenchés par webhook.
Choisir un modèle de déploiement
Lors du déploiement de workers, vous devez faire deux choix : comment le worker réclame le travail, et où chaque session s’exécute.
Comment le worker réclame le travail :
- Toujours actif : Un processus de longue durée interroge la file en continu. Le processus n’effectue que des requêtes HTTPS sortantes, vous n’exposez donc aucun point de terminaison à Anthropic.
- Déclenché par webhook : Un gestionnaire se réveille sur
session.status_run_startedet commence à interroger la file. Cela évite un « poller » (processus d’interrogation) inactif, mais nécessite un point de terminaison de webhook accessible par Anthropic.
Où chaque session s’exécute :
- Dans le processus : Le worker qui réclame une session exécute également ses appels d’outils, dans un répertoire de travail partagé unique.
- Une sandbox par session : Un poller lance une nouvelle sandbox pour chaque session réclamée. Choisissez cette option pour une isolation plus forte : un système de fichiers neuf, des limites de ressources ou des contrôles réseau par session. Consultez Exécuter une sandbox par session, qui couvre également le chart Helm pour Kubernetes.
Les workers CLI et SDK prennent en charge différentes combinaisons :
| Capacité | CLI ant | SDK (Python, TypeScript, Go) |
|---|---|---|
| Interrogation permanente | Oui | Oui |
| Déclenché par webhook | Non | Oui |
| Une sandbox par session | Oui | Oui |
| Magasins de mémoire | Oui, avec les paramètres de synchronisation par défaut | Oui, avec une synchronisation configurable |
| Outils personnalisés | Non | Oui |
Consultez la référence des workers auto-hébergés pour chaque option de la CLI et du SDK.
Pour plus de contrôle, appelez directement les points de terminaison de travail d’environnement et implémentez votre propre worker. Votre worker fait alors ce que font les workers du SDK. Entre autres, il acquitte chaque élément de travail, envoie des heartbeats et télécharge les skills de l’agent. Il n’exécute que les appels d’outils autorisés par la politique d’autorisation de la session. Il renvoie chaque résultat sous forme d’événement user.tool_result ou user.custom_tool_result. À la fin, il arrête l’élément. Utilisez comme référence le code source du worker dans le SDK Python, le SDK TypeScript ou le SDK Go.
Exécuter un worker toujours actif
Ces exemples utilisent /workspace comme répertoire de travail du worker. Le répertoire doit exister avant le démarrage du worker. Sur un nouvel hôte, créez-le et accordez à l’utilisateur du worker un accès en écriture, comme dans l’étape « Démarrer le worker » de Exécuter votre première session.
Sur macOS, mkdir ne peut pas créer /workspace, car le volume racine est en lecture seule. Créez plutôt ~/workspace, comme le montre cette étape. À la place de /workspace, utilisez le chemin complet affiché par echo ~/workspace, car le SDK ne développe pas ~.
Démarrez un worker qui interroge la file en continu. Il s’authentifie avec la clé d’environnement du démarrage rapide :
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())
# Annuler la tâche, plutôt que tuer le processus, permet au worker d'arrêter son
# élément de travail en cours et de téléverser les fichiers mémoire modifiés avant de quitter.
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())Déclencher des workers à partir de webhooks
S’abonner aux webhooks de session
Dans la Claude Console, définissez un point de terminaison de webhook qui écoute les événements
session.status_run_started. Consultez S’abonner aux webhooks pour plus de détails.Exporter la clé de signature du webhook
En plus de l’ID et de la clé d’environnement de Exécuter votre première session, exportez la clé de signature du webhook sur l’hôte de votre gestionnaire. Le gestionnaire l’utilise pour vérifier les charges utiles entrantes.
export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."Implémenter le gestionnaire de webhook
Démarrez le worker lorsque
session.status_run_startedse déclenche. Le gestionnaire vide la file et transmet chaque élément de travail récupéré àhandle_item()(dans les SDK Python, TypeScript et Go). Cette méthode télécharge les skills, exécute les appels d’outils, renvoie les résultats, puis se termine.Les exemples utilisent
/workspacecomme répertoire de travail. Avant de démarrer le gestionnaire, créez ce répertoire sur l’hôte du gestionnaire. Assurez-vous que l’utilisateur du gestionnaire peut y écrire, comme dans l’étape « Démarrer le worker » de Exécuter votre première session.PythonPour vérifier les signatures des webhooks, installez l’extra webhooks :
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, ) # Annulé par shutdown() afin qu'un élément de travail en cours puisse téléverser les fichiers mémoire modifiés et # supprimer ses répertoires de magasin avant la fin du processus. inflight: set[asyncio.Task[None]] = set() # Attendez ceci depuis le hook d'arrêt de l'hôte, tel qu'un arrêt de lifespan ASGI (le code après # `yield` dans un lifespan FastAPI), qu'uvicorn exécute sur SIGTERM. uvicorn laisse les requêtes ouvertes # se terminer avant ce hook ; définissez donc --timeout-graceful-shutdown pour borner l'attente. 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: # Protégé : une livraison abandonnée ou expirée ne doit pas annuler l'élément ; c'est shutdown() qui le fait. 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, # Le secret par session est ce qui permet au worker de monter les magasins de mémoire de la session. work_secret=work.secret, )Dans les SDK Python, TypeScript et Go,
handle_item()a besoin du secret de l’élément de travail pour monter les magasins de mémoire. Un worker qui interroge la file avecrun()dispose déjà du secret. Ce gestionnaire réclame lui-même chaque élément ; il transmet donc le secret dans l’argumentwork_secret. Consultez Transmettre le secret de l’élément de travail.
Ce gestionnaire exécute chaque élément réclamé dans un seul processus, et il exécute simultanément les éléments issus de livraisons de webhook distinctes. Ces sessions partagent un même système de fichiers, y compris /workspace et /mnt/memory. Si vos sessions attachent le même magasin de mémoire, consultez Isoler les sessions qui partagent un magasin.
Étapes suivantes
Lancez des sandboxes avec le chart Helm sur Kubernetes, un script de lancement ou le poller du SDK.
Consultez la profondeur de la file, arrêtez proprement les sessions et les workers, et corrigez les défaillances courantes.
Modèle de responsabilité partagée pour les environnements de sandbox auto-hébergés.
Disponibilité
Claude API
- Statut
- Bêta
- API
- Managed Agents
- En-tête bêta
- Nécessite
- Modèles
- Tous les modèles
Claude Platform on AWS
- Statut
- Bêta
- API
- Managed Agents
- En-tête bêta
- Nécessite
- Modèles
- Tous les modèles
Traitement des données
Présentation du traitement des donnéesPoints de terminaison concernés
/v1/agents/v1/sessions/v1/environments
Non éligible à la ZDR, sauf pour Managed Agents auto-hébergé. Les sessions sont des ressources avec état ; les transcriptions persistent jusqu’à ce que vous les supprimiez. En savoir plus
Non éligible à HIPAA. S’applique à toutes les sous-fonctionnalités de Managed Agents.
Cette page vous a-t-elle été utile ?