Claude Platform Docs
Managed AgentsSandboxes autoalojados

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

ComandoDescripción
ant beta:worker pollReclama 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 runGestiona una sesión reclamada y termina. Úsalo como punto de entrada de un sandbox por sesión.
FlagDescripción
--environment-idEl entorno que se consulta en busca de trabajo. También se lee de ANTHROPIC_ENVIRONMENT_ID.
--environment-keyAutentica el worker con este entorno. También se lee de ANTHROPIC_ENVIRONMENT_KEY.
--workdirDirectorio donde el worker descarga las skills y donde las herramientas leen y escriben archivos. El valor predeterminado es . (el directorio actual). El directorio debe existir antes de que se inicie el worker.
--on-workScript 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-idleCuánto tiempo espera el worker mientras una sesión está inactiva antes de que ant beta:worker run termine o ant beta:worker poll pase al siguiente elemento de trabajo. El tiempo de inactividad con un motivo de detención requires_action no cuenta. El valor predeterminado es 60s. Establécelo en 0 para desactivar el límite de tiempo de espera. Con un script de --on-work, ant beta:worker poll ignora este flag. En su lugar, pásalo al comando ant beta:worker run que tu script inicia.
--log-formatFormato de salida de los logs. Usa json para la ingesta de logs estructurados. El valor predeterminado es text.

Variables de entorno

VariableDescripciónEstablecida por
ANTHROPIC_ENVIRONMENT_IDEl entorno cuya cola atiende el worker.Tú, en el host del worker. El sondeador la pasa al script de --on-work.
ANTHROPIC_ENVIRONMENT_KEYAutentica el worker ante su cola.Tú, en el host del worker. El sondeador la pasa al script de --on-work.
ANTHROPIC_SESSION_IDLa sesión que representa un elemento de trabajo reclamado.El sondeador, para el script de --on-work.
ANTHROPIC_WORK_IDEl elemento de trabajo reclamado.El sondeador, para el script de --on-work.
ANTHROPIC_WORK_SECRETEl secreto del elemento de trabajo para su sesión.Tú. El sondeador no la establece. Consulta Reenvía el secreto del elemento de trabajo.
ANTHROPIC_BASE_URLSobrescribe el endpoint predeterminado de la API. Opcional.Tú, en el host del worker.
ANTHROPIC_WEBHOOK_SIGNING_KEYVerifica las cargas útiles de webhooks entrantes.Tú, en un host que gestione webhooks.

Requisitos del host

WorkerRequisito
Todos los workersUn host Linux o macOS con /bin/bash en esa ruta exacta. La herramienta bash del worker lo ejecuta directamente, sin consultar PATH. En macOS, se trata del Bash 3.2 del sistema.
SDK de TypeScriptunzip y tar en el PATH, y Node.js 22 o posterior.
SDK de Python y GoNingú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.

En macOS, el volumen raíz es de solo lectura, por lo que mkdir no puede crear /workspace. Establece como directorio de trabajo del worker uno en el que puedas escribir, como un directorio workspace en tu directorio personal. Para usar almacenes de memoria en macOS, primero prepara el host macOS.

Sistema de archivos del sandbox

RutaContenido
/workspaceEl directorio de trabajo de los ejemplos de las páginas de sandboxes autoalojados. No es el valor predeterminado del worker: el worker usa el directorio actual a menos que establezcas --workdir o workdir. Los sandboxes en la nube de Anthropic guardan las skills y los repositorios en /workspace. 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>/Una copia local de cada almacén de memoria adjunto, un directorio por almacén. La API devuelve la ruta completa de cada directorio en el campo mount_path del recurso de almacén de memoria de la sesión (por ejemplo, /mnt/memory/user-preferences/).

El worker crea los directorios de los almacenes de memoria cuando reclama una sesión. Los elimina cuando termina con esa sesión o cuando detienes el worker de forma ordenada. Eso elimina solo las copias locales, y las memorias permanecen en el almacén.

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 descargas las skills por tu cuenta, establece tú mismo sus permisos de ejecución.

Cuándo termina el worker con una sesión

El worker termina con una sesión en cualquiera de estos casos:

  • La sesión termina.
  • Detienes el elemento de trabajo de la sesión.
  • La sesión permanece inactiva durante el límite de inactividad del worker. La sesión en sí permanece abierta. Cuando luego le envías un nuevo evento, como un mensaje de usuario, el mismo worker u otro la reclama. Ese worker vuelve a descargar los almacenes.

El límite de inactividad es de 60 segundos de forma predeterminada. Para cambiarlo, usa --max-idle para el worker de la CLI ant o max_idle para EnvironmentWorker. El chart de Helm cma-sandboxes, en cambio, inicia sus workers con un límite de 30 minutos. Para cambiar ese límite, cambia la opción sandbox.idleTimeout del chart.

Entregables finales

Los sandboxes autoalojados no tienen un directorio /mnt/session/outputs. En los sandboxes en la nube de Anthropic, la indicación del sistema de la sesión instruye al agente para que copie allí los entregables finales. En los entornos autoalojados, la indicación del sistema omite esa instrucción. Los entregables finales quedan donde el agente los escriba, normalmente dentro del directorio de trabajo, y el worker no los sube.

Para reunir los entregables finales en un solo lugar, proporciona la ruta completa de un directorio en la indicación del sistema de tu agente. Elige un directorio en el que puedan escribir las herramientas de archivos del worker:

Helpers del SDK

Los SDK de Python, TypeScript y Go proporcionan tres helpers con distintos niveles de control:

HelperQué haceÚsalo cuando
EnvironmentWorkerGestiona el sondeo, la configuración y las ejecuciones de herramientas 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 cómo gestionar cada sesión, por ejemplo, lanzando 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 ejecutar las herramientas.

EnvironmentWorker

MétodoDescripción
run()Se ejecuta indefinidamente, tomando las sesiones a medida que llegan.
handle_item()Gestiona un elemento de trabajo ya reclamado por un sondeador. El sondeador puede ser ant beta:worker poll --on-work o tu propio código. El método retorna cuando el worker termina con la sesión del elemento. Puedes pasar work_id, session_id, environment_id y work_secret. Para cada uno que omitas, el método lee la variable ANTHROPIC_* correspondiente.
OpciónDescripción
toolsUna 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.
max_idleCuánto tiempo espera el worker mientras una sesión está inactiva antes de terminar con la sesión. El tiempo de inactividad con un motivo de detención requires_action no cuenta. El valor predeterminado es de 60 segundos. Para esperar 5 minutos, establécelo en 300. Para desactivar el límite, establécelo en None.
memory_sync_intervalEl tiempo mínimo entre dos sincronizaciones de los almacenes de memoria adjuntos mientras se ejecuta la sesión. El worker comprueba el intervalo después de cada llamada a una herramienta que se ejecuta en tu sandbox, no con un temporizador. El valor predeterminado es de 15 segundos. Consulta Intervalo de sincronización.
memory_sync_deletionsSi 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:

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic, beta_async_tool
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_bash_tool


@beta_async_tool
async def get_order_status(order_id: str) -> str:
    """Look up an order in the internal fulfillment system by order ID."""
    return f"Order {order_id}: shipped"


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,
            # Enumera todas las herramientas que el agente puede llamar. El worker no responde a ninguna otra herramienta.
            tools=lambda env: [beta_bash_tool(env), get_order_status],
        )
        task = asyncio.create_task(worker.run())
        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())

Sondeador de trabajo

OpciónDescripción
drainSi se debe dejar de sondear una vez que la cola está vacía en lugar de esperar trabajo nuevo.
block_msCuá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 no bloqueante. El valor predeterminado es un sondeo largo de 999 ms.
reclaim_older_than_msVuelve a reclamar los elementos de trabajo que se reclamaron pero nunca se confirmaron dentro de esta cantidad de milisegundos.
auto_stopSi el sondeador publica una señal de detención para cada elemento de trabajo una vez que el cuerpo de tu bucle termina con él. El valor predeterminado es True. Establécelo en False en los dos casos que siguen a esta tabla.

Establece auto_stop en False en dos casos:

  1. Tu bucle llama a handle_item(), que publica la detención por sí mismo.
  2. Tu bucle lanza un sandbox para el elemento y continúa. El worker de ese sandbox debe publicar la detención cuando termine el trabajo de la sesión, como hacen ant beta:worker run y handle_item().

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ónDescripción
allowed_rootsDirectorios, además del directorio de trabajo, a los que pueden acceder las herramientas de archivos (read, write, edit, glob, grep).
read_only_rootsDirectorios 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).

¿Te resultó útil esta página?