--- title: Referencia de workers autoalojados url: https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-reference description: "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." featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Esta página documenta los workers predefinidos que atienden un entorno `self_hosted`. Para guías orientadas a tareas, comienza con [Sandboxes autoalojados](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes) y [Implementar workers autoalojados](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-workers). ## 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](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons) `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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). | | `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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#requirements) 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. | | `/skills//` | Las skills descargadas del agente. | | `/mnt/memory//` | Un directorio por cada almacén de memoria adjunto, en el `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) 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`](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-reference#environment-worker) | Gestiona el sondeo, la configuración y la ejecución de principio a fin. | En la mayoría de los casos. | | [`work.poller()` (go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-reference#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()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-reference#session-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()` (go: `Run()`) | Se ejecuta indefinidamente, tomando las sesiones a medida que llegan. | | `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | 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` (typescript: `workSecret`; go: `WorkSecret`), o deja que lea las [variables `ANTHROPIC_*`](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-reference#environment-variables). | | Opción | Descripción | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools` (go: `ToolsFunc`) | 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` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) | Con qué frecuencia los almacenes de memoria adjuntos se concilian con el servidor mientras se ejecuta la sesión. Consulta [Intervalo de sincronización](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#sync-interval). | | `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) | Si los archivos que el agente elimina localmente también se eliminan del almacén. Consulta [Eliminaciones](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#deletions). | `EnvironmentWorker` gestiona automáticamente el `AgentToolContext` y el conjunto de herramientas. Pasa una fábrica `tools` (go: `ToolsFunc`) para personalizar la lista de herramientas: ```python Python EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool]) ``` ```typescript TypeScript new EnvironmentWorker({ client, environmentId, environmentKey, tools: (ctx) => [betaBashTool(ctx), myCustomTool] }); ``` El SDK de C# no tiene `EnvironmentWorker`. Para responder a las llamadas a herramientas personalizadas desde tu propio código, envía cada resultado en el flujo de eventos de la sesión, como en [Devolver un resultado de herramienta personalizada](https://platform.claude.com/docs/es/managed-agents/events-and-streaming#return-a-custom-tool-result). ```go Go worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool { return []anthropic.BetaTool{agenttoolset.BetaBashTool(env), myCustomTool} }, }) ``` El SDK de Java no tiene `EnvironmentWorker`. Para responder a las llamadas a herramientas personalizadas desde tu propio código, envía cada resultado en el flujo de eventos de la sesión, como en [Devolver un resultado de herramienta personalizada](https://platform.claude.com/docs/es/managed-agents/events-and-streaming#return-a-custom-tool-result). El SDK de PHP no tiene `EnvironmentWorker`. Para responder a las llamadas a herramientas personalizadas desde tu propio código, envía cada resultado en el flujo de eventos de la sesión, como en [Devolver un resultado de herramienta personalizada](https://platform.claude.com/docs/es/managed-agents/events-and-streaming#return-a-custom-tool-result). El SDK de Ruby no tiene `EnvironmentWorker`. Para responder a las llamadas a herramientas personalizadas desde tu propio código, envía cada resultado en el flujo de eventos de la sesión, como en [Devolver un resultado de herramienta personalizada](https://platform.claude.com/docs/es/managed-agents/events-and-streaming#return-a-custom-tool-result). ### Sondeador de trabajo | Opción | Descripción | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `drain` (go: `Drain`) | Si se debe dejar de sondear una vez que la cola está vacía en lugar de esperar trabajo nuevo. | | `block_ms` (typescript: `blockMs`; go: `BlockMs`) | 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 `null` (python: `None`; go: `param.Null[int64]()`) para una comprobación sin bloqueo. El valor predeterminado es un long-poll de 999 ms. | | `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | Vuelve a reclamar los elementos de trabajo que se reclamaron pero nunca se confirmaron dentro de esta cantidad de milisegundos. | | `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | 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` (python: `False`; go: `param.NewOpt(false)`) cuando lo que ejecuta el elemento de trabajo publica la detención por sí mismo. `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-workers#launch-sandboxes-from-the-sdk-poller). ### Ejecutor de herramientas de sesión `client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`) recibe una lista de herramientas como `tools` (go: `Tools`). Para construir esa lista, configura tú mismo `AgentToolContext` y llama a `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`): ```python Python 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// tools = beta_agent_toolset_20260401(env) ``` ```typescript TypeScript import { setupSkills, betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node"; const ctx = { workdir: "/workspace", client, sessionId: work.data.id }; await setupSkills(ctx); const tools = betaAgentToolset20260401(ctx); ``` El SDK de C# no tiene `AgentToolContext`. ```go Go env := &agenttoolset.AgentToolContext{Workdir: "/workspace"} if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil { panic(err) } // skills descargadas en /workspace/skills// tools := agenttoolset.BetaAgentToolset20260401(env) ``` El SDK de Java no tiene `AgentToolContext`. El SDK de PHP no tiene `AgentToolContext`. El SDK de Ruby no tiene `AgentToolContext`. ### 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` (typescript: `allowedRoots`; go: `AllowedRoots`) | Directorios, además del directorio de trabajo, a los que pueden acceder las herramientas de archivos (`read`, `write`, `edit`, `glob`, `grep`). | | `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`) | 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` (typescript: `allowedRoots`; go: `AllowedRoots`), y los directorios de los almacenes adjuntos con `access: "read_only"` a `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`). 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)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`) recibe un `AgentToolContext` y devuelve las implementaciones de herramientas estándar (`bash`, `read`, `write`, `edit`, `glob`, `grep`).