Implementar workers autoalojados
Elige cómo los workers de sandbox autoalojados reclaman trabajo y dónde se ejecutan las sesiones, y luego ejecuta un worker siempre activo o activa workers desde webhooks.
El inicio rápido de sandboxes autoalojados ejecuta un worker de la CLI ant que sondea continuamente y ejecuta cada sesión en un solo proceso. Esta página te ayuda a elegir un patrón de implementación y luego cubre los workers siempre activos y los activados por webhook.
Elige un patrón de implementación
Al implementar workers, debes tomar dos decisiones: cómo el worker reclama trabajo y dónde se ejecuta cada sesión.
Cómo el worker reclama trabajo:
- Siempre activo: Un proceso de larga duración sondea la cola continuamente. El proceso solo realiza solicitudes HTTPS salientes, así que no expones ningún endpoint a Anthropic.
- Activado por webhook: Un controlador se activa con
session.status_run_startedy comienza a sondear. Esto evita un sondeador inactivo, pero requiere un endpoint de webhook al que Anthropic pueda acceder.
Dónde se ejecuta cada sesión:
- En proceso: El worker que reclama una sesión también ejecuta sus llamadas a herramientas, en un único directorio de trabajo compartido.
- Sandbox por sesión: Un sondeador lanza un sandbox nuevo para cada sesión reclamada. Elige esta opción para un aislamiento más fuerte: un sistema de archivos nuevo, límites de recursos o controles de red por sesión. Consulta Ejecutar un sandbox por sesión, que también cubre el chart de Helm para Kubernetes.
Los workers de la CLI y del SDK admiten diferentes combinaciones:
| Capacidad | CLI ant | SDK (Python, TypeScript, Go) |
|---|---|---|
| Sondeo siempre activo | Sí | Sí |
| Activado por webhook | No | Sí |
| Sandbox por sesión | Sí | Sí |
| Almacenes de memoria | Sí, con la configuración de sincronización predeterminada | Sí, con sincronización configurable |
| Herramientas personalizadas | No | Sí |
Consulta la referencia de workers autoalojados para ver cada flag de la CLI y cada opción del SDK.
Para tener más control, llama directamente a los endpoints de trabajo del entorno e implementa tu propio worker. Tu worker hace entonces lo que hacen los workers del SDK. Entre otras cosas, confirma cada elemento de trabajo, envía “heartbeats” (latidos) y descarga las skills del agente. Ejecuta solo las llamadas a herramientas que permite la política de permisos de la sesión. Devuelve cada resultado como un evento user.tool_result o user.custom_tool_result. Al final, detiene el elemento. Usa como referencia el código fuente del worker en el SDK de Python, el SDK de TypeScript o el SDK de Go.
Ejecuta un worker siempre activo
Estos ejemplos usan /workspace como directorio de trabajo del worker. El directorio debe existir antes de que se inicie el worker. En un host nuevo, créalo y dale al usuario del worker acceso de escritura, como en el paso “Inicia el worker” de Ejecuta tu primera sesión.
En macOS, mkdir no puede crear /workspace, porque el volumen raíz es de solo lectura. Crea ~/workspace en su lugar, como muestra ese paso. En lugar de /workspace, usa la ruta completa que imprime echo ~/workspace, porque el SDK no expande ~.
Inicia un worker que sondee la cola continuamente. Se autentica con la clave del entorno del inicio rápido:
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())
# Cancelar la tarea, en lugar de matar el proceso, permite que el worker detenga su
# elemento de trabajo en curso y suba los archivos de memoria modificados antes de salir.
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())Activa workers desde webhooks
Suscríbete a los webhooks de sesión
En la Claude Console, define un endpoint de webhook que escuche eventos
session.status_run_started. Consulta Suscribirse a webhooks para más detalles.Exporta la clave de firma del webhook
Junto con el ID y la clave del entorno de Ejecuta tu primera sesión, exporta la clave de firma del webhook en el host de tu controlador. El controlador la usa para verificar las cargas útiles entrantes.
export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."Implementa el controlador del webhook
Inicia el worker cuando se dispare
session.status_run_started. El controlador vacía la cola y entrega cada elemento de trabajo reclamado ahandle_item()(en los SDK de Python, TypeScript y Go). Ese método descarga las skills, ejecuta las llamadas a herramientas, publica los resultados y regresa.Los ejemplos usan
/workspacecomo directorio de trabajo. Antes de iniciar el controlador, crea ese directorio en el host del controlador. Asegúrate de que el usuario del controlador pueda escribir en él, como en el paso “Inicia el worker” de Ejecuta tu primera sesión.PythonPara verificar las firmas de webhook, instala el extra de 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, ) # Cancelado por shutdown() para que un elemento de trabajo en curso pueda subir los archivos de memoria modificados y # eliminar sus directorios de almacén antes de que el proceso termine. inflight: set[asyncio.Task[None]] = set() # Espera esto desde el hook de apagado del host, como un apagado de lifespan de ASGI (el código tras # `yield` en un lifespan de FastAPI), que uvicorn ejecuta al recibir SIGTERM. uvicorn deja terminar las solicitudes abiertas # antes de ejecutar ese hook, así que configura --timeout-graceful-shutdown para limitar la espera. 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: # Protegido: una entrega descartada o con tiempo de espera agotado no debe cancelar el elemento; shutdown() sí lo hace. 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, # El secreto por sesión es lo que permite al worker montar los almacenes de memoria de la sesión. work_secret=work.secret, )En los SDK de Python, TypeScript y Go,
handle_item()necesita el secreto del elemento de trabajo para montar almacenes de memoria. Un worker que sondea conrun()ya tiene el secreto. Este controlador reclama cada elemento por sí mismo, así que pasa el secreto en el argumentowork_secret. Consulta Reenvía el secreto del elemento de trabajo.
Este controlador ejecuta cada elemento reclamado en un solo proceso, y ejecuta al mismo tiempo elementos de entregas de webhook distintas. Esas sesiones comparten un único sistema de archivos, incluidos /workspace y /mnt/memory. Si tus sesiones adjuntan el mismo almacén de memoria, consulta Aislar sesiones que comparten un almacén.
Próximos pasos
Lanza sandboxes con el chart de Helm en Kubernetes, un script de lanzamiento o el sondeador del SDK.
Lee la profundidad de la cola, detén sesiones y workers de forma limpia y corrige fallos comunes.
Modelo de responsabilidad compartida para entornos de sandbox autoalojados.
Disponibilidad
Claude API
- Estado
- Beta
- API
- Managed Agents
- Encabezado beta
- Requiere
- Modelos
- Todos los modelos
Claude Platform on AWS
- Estado
- Beta
- API
- Managed Agents
- Encabezado beta
- Requiere
- Modelos
- Todos los modelos
Manejo de datos
Descripción general del manejo de datosEndpoints aplicables
/v1/agents/v1/sessions/v1/environments
No es elegible para ZDR, excepto Managed Agents autoalojado. Las sesiones son recursos con estado; las transcripciones persisten hasta que las eliminas. Más información
No es elegible para HIPAA. Se aplica a todas las subfunciones de Managed Agents.
¿Te resultó útil esta página?