Referencia de workers autoalojados
Referencia para workers de sandbox autoalojados: flags de la CLI ant, variables de entorno, requisitos del host, rutas del sistema de archivos y opciones de los helpers del SDK.
Esta página documenta los workers predefinidos que atienden un entorno self_hosted. Para guías orientadas a tareas, comienza con Sandboxes autoalojados y Implementar workers autoalojados.
Comandos y flags de la CLI
| Comando | Descripción |
|---|---|
ant beta:worker poll | Reclama elementos de trabajo de la cola del entorno y ejecuta cada sesión en el mismo proceso. Con --on-work, llama a tu script para cada elemento de trabajo en su lugar. |
ant beta:worker run | Gestiona una sesión reclamada y termina. Úsalo como punto de entrada de un sandbox por sesión. |
| Flag | Descripción |
|---|---|
--environment-id | El entorno que se consulta en busca de trabajo. También se lee de ANTHROPIC_ENVIRONMENT_ID. |
--environment-key | Autentica el worker con este entorno. También se lee de ANTHROPIC_ENVIRONMENT_KEY. |
--workdir | Directorio donde se descargan las skills y donde las herramientas leen y escriben archivos. El valor predeterminado es . (el directorio actual). |
--on-work | Script al que se llama para cada elemento de trabajo reclamado en lugar de ejecutar las herramientas en el mismo proceso. Recibe los detalles de la sesión como variables de entorno y el elemento de trabajo como JSON en la entrada estándar. |
--max-idle | Cuánto tiempo esperar después de que la sesión queda inactiva con un motivo de detención end_turn antes de apagarse. El valor predeterminado es 60s. |
--log-format | Formato de salida de los logs. Usa json para la ingesta de logs estructurados. El valor predeterminado es text. |
Variables de entorno
| Variable | Descripción | Establecida por |
|---|---|---|
ANTHROPIC_ENVIRONMENT_ID | El entorno cuya cola atiende el worker. | Tú, en el host del worker. El sondeador la pasa al script de --on-work. |
ANTHROPIC_ENVIRONMENT_KEY | Autentica el worker ante su cola. | Tú, en el host del worker. El sondeador la pasa al script de --on-work. |
ANTHROPIC_SESSION_ID | La sesión que representa un elemento de trabajo reclamado. | El sondeador, para el script de --on-work. |
ANTHROPIC_WORK_ID | El elemento de trabajo reclamado. | El sondeador, para el script de --on-work. |
ANTHROPIC_WORK_SECRET | El secreto por sesión del elemento de trabajo. | Tú. El sondeador no la establece. Consulta Reenvía el secreto del elemento de trabajo. |
ANTHROPIC_BASE_URL | Sobrescribe el endpoint predeterminado de la API. Opcional. | Tú, en el host del worker. |
ANTHROPIC_WEBHOOK_SIGNING_KEY | Verifica las cargas útiles de webhooks entrantes. | Tú, en un host que gestione webhooks. |
Requisitos del host
| Worker | Requisito |
|---|---|
| Todos los workers | Un host Linux con /bin/bash en esa ruta exacta. La herramienta bash del worker lo invoca directamente, sin consultar PATH. |
| SDK de TypeScript | unzip y tar en el PATH, y Node.js 22 o posterior. |
| SDK de Python y Go | Ningún binario adicional. Estos SDK usan sus bibliotecas estándar para la extracción de archivos comprimidos. |
Los almacenes de memoria añaden sus propios requisitos.
Sistema de archivos del sandbox
| Ruta | Contenido |
|---|---|
/workspace | El directorio de trabajo predeterminado del sistema para la ejecución de herramientas y la descarga de skills. Si usas un directorio de trabajo diferente, actualiza la indicación del sistema de tu agente para que Claude pueda localizar los archivos de las skills. |
<workdir>/skills/<name>/ | Las skills descargadas del agente. |
/mnt/memory/<store>/ | Un directorio por cada almacén de memoria adjunto, en el mount_path del almacén (por ejemplo, /mnt/memory/user-preferences/). El worker crea estos directorios cuando reclama la sesión y los elimina cuando la sesión termina. |
En los entornos autoalojados, la indicación del sistema de la sesión omite la instrucción de /mnt/session/outputs que se usa en los sandboxes gestionados por Anthropic. Los entregables finales quedan donde el agente los escriba en el sistema de archivos de tu sandbox, normalmente dentro del directorio de trabajo.
Las skills pueden incluir ejecutables que el agente puede ejecutar directamente. Los workers de la CLI y del SDK conservan los permisos de ejecución registrados en el paquete de la skill al extraerlo. Si implementas la descarga de skills manualmente, eres responsable de establecer los permisos de ejecución.
Helpers del SDK
Los SDK de Python, TypeScript y Go proporcionan tres helpers con distintos niveles de control:
| Helper | Qué hace | Úsalo cuando |
|---|---|---|
EnvironmentWorker | Gestiona el sondeo, la configuración y la ejecución de principio a fin. | En la mayoría de los casos. |
work.poller() | Sondea la cola de trabajo y te entrega cada sesión reclamada. | Tú determinas qué ocurre con cada sesión, por ejemplo, lanzar un sandbox en lugar de ejecutar las herramientas en el mismo proceso. |
client.beta.sessions.events.tool_runner() | Ejecuta las llamadas a herramientas de una sola sesión, dados el ID de la sesión y una lista de herramientas. | Ya reclamaste el trabajo y solo necesitas la capa de ejecución. |
EnvironmentWorker
| Método | Descripción |
|---|---|
run() | Se ejecuta indefinidamente, tomando las sesiones a medida que llegan. |
handle_item() | Gestiona un único elemento de trabajo reclamado y retorna. Pasa explícitamente los identificadores del trabajo, la sesión y el entorno, y el work_secret, o deja que lea las variables ANTHROPIC_*. |
| Opción | Descripción |
|---|---|
tools | Una fábrica que recibe el AgentToolContext de la sesión y devuelve la lista de herramientas. El valor predeterminado es el conjunto de herramientas estándar del agente. |
memory_sync_interval | Con qué frecuencia los almacenes de memoria adjuntos se concilian con el servidor mientras se ejecuta la sesión. Consulta Intervalo de sincronización. |
memory_sync_deletions | Si los archivos que el agente elimina localmente también se eliminan del almacén. Consulta Eliminaciones. |
EnvironmentWorker gestiona automáticamente el AgentToolContext y el conjunto de herramientas. Pasa una fábrica tools para personalizar la lista de herramientas:
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])Sondeador de trabajo
| Opción | Descripción |
|---|---|
drain | Si se debe dejar de sondear una vez que la cola está vacía en lugar de esperar trabajo nuevo. |
block_ms | Cuánto tiempo espera cada sondeo a que llegue trabajo antes de retornar, en milisegundos. Debe estar entre 1 y 999; el helper vuelve a sondear automáticamente. Pasa None para una comprobación sin bloqueo. El valor predeterminado es un long-poll de 999 ms. |
reclaim_older_than_ms | Vuelve a reclamar los elementos de trabajo que se reclamaron pero nunca se confirmaron dentro de esta cantidad de milisegundos. |
auto_stop | Si se debe publicar una señal de detención para cada elemento de trabajo una vez que el cuerpo de tu bucle termina con él. Establécelo en False cuando lo que ejecuta el elemento de trabajo publica la detención por sí mismo. handle_item() lo hace, y también un sandbox que lances y que sea responsable de la llamada de detención. |
Para ver un ejemplo completo, consulta Lanza sandboxes desde el sondeador del SDK.
Ejecutor de herramientas de sesión
client.beta.sessions.events.tool_runner() recibe una lista de herramientas como tools. Para construir esa lista, configura tú mismo AgentToolContext y llama a beta_agent_toolset_20260401(env):
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 descargadas en /workspace/skills/<name>/
tools = beta_agent_toolset_20260401(env)AgentToolContext y el conjunto de herramientas del agente
AgentToolContext es el contexto de ejecución para las llamadas a herramientas. Define el directorio de trabajo y la política de rutas, y puede descargar las skills de la sesión.
| Opción | Descripción |
|---|---|
allowed_roots | Directorios, además del directorio de trabajo, a los que pueden acceder las herramientas de archivos (read, write, edit, glob, grep). |
read_only_roots | Directorios bajo los cuales write y edit rechazan rutas. |
EnvironmentWorker añade por sí mismo los directorios de los almacenes de memoria de la sesión a allowed_roots, y los directorios de los almacenes adjuntos con access: "read_only" a read_only_roots.
El confinamiento es una barrera de protección solo para las herramientas de archivos, no un sandbox. No restringe bash.
beta_agent_toolset_20260401(env) recibe un AgentToolContext y devuelve las implementaciones de herramientas estándar (bash, read, write, edit, glob, grep).
Was this page helpful?