Sandboxes autoalojados

De forma predeterminada, Managed Agents ejecuta herramientas y código dentro de sandboxes en la nube administrados por Anthropic. Los sandboxes autoalojados mantienen la orquestación del lado de Anthropic pero trasladan la ejecución de herramientas a infraestructura que tú controlas, de modo que el código del agente, el sistema de archivos y la salida de red nunca abandonan tu entorno.

La ejecución de herramientas permanece en tu host: el sistema de archivos que el agente lee y escribe, los procesos que genera y la red a la que puede acceder están todos bajo tu control. Las entradas y salidas de las herramientas siguen fluyendo hacia el plano de control de Anthropic (donde se ejecuta Claude) para que el modelo pueda ver los resultados y determinar qué hacer a continuación. Consulta el modelo de seguridad para conocer el límite completo del flujo de datos.



En qué se diferencia de los entornos en la nube

El autoalojamiento es una buena opción cuando el agente necesita operar con datos que no pueden salir del límite de tu red, acceder a servicios internos que no son enrutables públicamente o ejecutarse bajo los propios controles de cumplimiento y auditoría de tu organización.

Para la elegibilidad de Zero Data Retention y HIPAA BAA, consulta API y retención de datos.



Cuándo combinar con túneles MCP

El autoalojamiento controla dónde se ejecuta el código del agente. Los túneles MCP controlan cómo Anthropic accede a los servidores MCP en tu red. Son independientes: una sesión que se ejecuta en los sandboxes en la nube de Anthropic aún puede acceder a servidores MCP privados a través de un túnel, y una sesión autoalojada puede usar servidores MCP tunelizados o públicos. Usa ambos cuando quieras que la ejecución y el acceso a herramientas permanezcan dentro de tu límite.



Worker de entorno

Un "environment worker" (worker de entorno) es un proceso que ejecutas en tu propia infraestructura. Recibe solicitudes de ejecución de herramientas de Anthropic y las ejecuta localmente. El entorno self_hosted actúa como una cola de trabajo: cuando se asigna una sesión a él, Anthropic encola la sesión como un elemento de trabajo. Tu worker reclama elementos de trabajo de esa cola, genera un contexto de ejecución para cada uno, descarga las skills del agente (recursos reutilizables basados en el sistema de archivos que le dan al agente experiencia específica de dominio), ejecuta las llamadas a herramientas y publica los resultados de vuelta.

Los elementos de trabajo se reclaman sondeando la cola del entorno: ya sea mediante un worker siempre activo que sondea continuamente, o un manejador activado por webhook que se despierta con session.status_run_started y comienza a sondear.

Tanto la CLI como el SDK incluyen workers preconstruidos. La CLI ant solo admite el patrón siempre activo; el SDK admite tanto el siempre activo como el activado por webhook. Ambos son configurables: consulta Worker autoalojado en la referencia para los flags de la CLI, y Helpers del SDK en esta página para las opciones del SDK. Para mayor control, llama directamente a los endpoints de Environments Work e implementa tu propio worker.



Sistema de archivos del sandbox

• /workspace: el directorio de trabajo predeterminado del sistema para la ejecución de herramientas y la descarga de skills. El flag --workdir de la CLI usa de forma predeterminada el directorio actual; pasa --workdir /workspace para coincidir con el valor predeterminado del sistema. Las skills se descargan en <workdir>/skills/<name>/. 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.
• /mnt/session/outputs: el arnés del worker le indica a Claude que escriba los entregables finales aquí. En modo sandbox, monta un directorio del host en esta ruta para recuperar las salidas después de que termine la sesión. En modo in-process, las herramientas de archivos del worker escriben bajo el directorio de trabajo en su lugar, por lo que esta ruta no aplica.



Antes de comenzar

Necesitas:

• Un agente existente. Si no tienes uno, completa primero el Inicio rápido y anota su ID de agente.
• Un host Linux con /bin/bash en esa ruta exacta. La herramienta bash del worker lo invoca directamente, sin consultar PATH. El SDK de TypeScript requiere adicionalmente unzip y tar en el PATH y Node.js 22 o posterior; los SDK de Python y Go usan sus bibliotecas estándar para la extracción de archivos y no tienen requisitos adicionales de binarios.
• La CLI ant o un SDK de Anthropic (Python, TypeScript o Go) en el host del worker.
• Dos credenciales: una clave de entorno (generada en la Console en los pasos siguientes) autentica al worker con su cola; tu clave de API de Claude crea sesiones y lee estadísticas de la cola desde fuera del host del worker. La generación de claves es solo a través de la Console.



Ejecuta un worker

Elige siempre activo para la configuración más simple: un proceso de larga duración sondea la cola continuamente y solo necesita HTTPS saliente. Elige activado por webhook para evitar ejecutar un sondeador inactivo; requiere un endpoint de webhook al que Anthropic pueda acceder (consulta Webhooks para la configuración del endpoint y la verificación de firmas).



Helpers del SDK

El SDK proporciona tres helpers en diferentes niveles de control. EnvironmentWorker cubre la mayoría de los casos de uso; baja a los helpers de nivel inferior cuando necesites lanzar tu propio proceso por sesión o ejecutar herramientas contra una sesión ya reclamada.

• EnvironmentWorker: el worker listo para usar. Maneja el sondeo, la configuración y la ejecución de principio a fin.
  • .run(): se ejecuta indefinidamente, recogiendo sesiones a medida que llegan.
  • .handle_item(): maneja un único elemento de trabajo reclamado y sale. Pasa los identificadores de trabajo, sesión y entorno explícitamente, o deja que lea las variables ANTHROPIC_* que ant beta:worker poll --on-work establece para el proceso que genera.
• work.poller(): sondea la cola de trabajo en tu nombre y te entrega cada sesión reclamada. Usa esto cuando quieras decidir qué sucede con cada sesión, por ejemplo, lanzar un sandbox en lugar de ejecutar herramientas in-process.
  • drain: si se debe dejar de sondear una vez que la cola esté vacía en lugar de esperar nuevo trabajo.
  • block_ms: cuánto tiempo esperar a que llegue trabajo antes de retornar, en milisegundos. Debe estar entre 1 y 999 (espera por sondeo; el helper vuelve a sondear automáticamente). Pasa null (None en Python, param.Null[int64]() en Go) para una verificación no bloqueante; omitir el parámetro usa el long-poll predeterminado de 999 ms.
  • reclaim_older_than_ms: vuelve a reclamar elementos de trabajo que fueron reclamados pero nunca confirmados 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 termine con él. El sondeador de Go no tiene opción de exclusión y siempre publica la señal de detención, así que bloquea en el cuerpo del bucle hasta que la sesión se complete en lugar de desacoplarte.
• client.beta.sessions.events.tool_runner(): ejecuta llamadas a herramientas para una única sesión, dado el ID de sesión y una lista de herramientas. Úsalo cuando ya hayas reclamado el trabajo y solo necesites la capa de ejecución.

Usa el sondeador de trabajo directamente cuando quieras lanzar tu propio proceso por sesión, por ejemplo, iniciando un sandbox para cada sesión reclamada:

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Reemplaza con tu propio lanzador de sandbox por sesión. Pasa
    # ANTHROPIC_ENVIRONMENT_KEY al sandbox lanzado, nunca
    # tu clave de API.
    print(f"claimed session {work.data.id}")


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:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

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. beta_agent_toolset_20260401(env) toma un AgentToolContext y devuelve las implementaciones estándar de herramientas (bash, read, write, edit, glob, grep).

Con EnvironmentWorker: ambos se administran automáticamente. Pasa una fábrica tools para personalizar la lista de herramientas:

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

Con work.poller() y tool_runner(): pasa una lista de herramientas como tools a client.beta.sessions.events.tool_runner(). Para construir esa lista, configura AgentToolContext tú mismo 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)



Verifica que el worker esté conectado

Desde una shell separada, con ANTHROPIC_API_KEY establecida con tu clave de API de Claude (no la clave de entorno), confirma que workers_polling sea al menos 1:

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

Si workers_polling permanece en 0, el worker no está llegando a la cola: confirma que ANTHROPIC_ENVIRONMENT_KEY y ANTHROPIC_ENVIRONMENT_ID estén establecidas en el host del worker. Consulta Leer la profundidad de la cola para la respuesta completa de estadísticas y ejemplos en otros lenguajes.



Inicia una sesión

Una vez que tu worker esté en ejecución, crea una sesión que apunte al entorno. Establece AGENT_ID con el ID del agente que anotaste en Antes de comenzar. La sesión entra en la cola de trabajo del entorno y espera allí hasta que un worker la reclame; si no hay ningún worker conectado, la sesión permanece en cola en lugar de fallar.

Anthropic no monta archivos ni repositorios de GitHub en los sandboxes autoalojados. Para hacer que los archivos específicos de la sesión estén disponibles, pasa referencias de archivos (como una ruta de S3 o un SHA de commit) en el campo metadata de la sesión. Tu script de generación o manejador --on-work lee esos metadatos del elemento de trabajo reclamado (el sondeador de la CLI canaliza el JSON del elemento de trabajo al stdin del script, y los manejadores del SDK pueden leerlo a través de los endpoints de Environments Work) y prepara los archivos en el directorio de trabajo antes de que comience la ejecución de herramientas.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

Consulta Worker autoalojado en la referencia para la lista completa de flags de la CLI, y Helpers del SDK para las opciones de helpers del SDK.



Monitoreo y operaciones

Estas llamadas se ejecutan desde tus herramientas de monitoreo u operaciones, autenticadas con tu clave de API de Claude, para observar y administrar la flota de workers. El bucle de reclamación y keep-alive se maneja dentro de los helpers del worker, por lo que no llamas a esos endpoints directamente.



Leer la profundidad de la cola

work.stats devuelve el estado de la cola para un entorno:

• depth es el número de elementos esperando ser reclamados. Escala tu flota de workers o genera alertas sobre el backlog basándote en este valor.
• pending es el número de elementos que un worker ha reclamado y está procesando actualmente.
• oldest_queued_at es la marca de tiempo del elemento más antiguo que aún está en cola o siendo procesado, o null cuando no hay ninguno.
• workers_polling es el número de workers que han sondeado en los últimos 30 segundos. Usa esto para alertas de actividad.

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}



Detener una sesión de forma ordenada

Usa work.stop para pedirle al worker que maneja una sesión específica que la cierre limpiamente. El worker termina cualquier llamada a herramienta en curso, publica un estado final y libera la sesión. Pasa force: true en el cuerpo de la solicitud (con la CLI, pasa --force) para interrumpir inmediatamente en lugar de esperar a que se complete la llamada a herramienta actual.

Debido a que estas llamadas se ejecutan desde tus herramientas de operaciones en lugar del host del worker, ANTHROPIC_WORK_ID no se establece automáticamente. Establécela con el ID del elemento de trabajo objetivo antes de ejecutar los siguientes ejemplos. Para encontrar el ID de un elemento de trabajo, lista los elementos de trabajo del entorno a través de los endpoints de Environments Work.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)



Próximos pasos