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 de tu límite de red, acceder a servicios internos que no son enrutables públicamente o ejecutarse bajo los controles de cumplimiento y auditoría propios 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. Para darle al agente herramientas de un servidor MCP dentro de tu red sin ejecutar un túnel, también puedes envolver el servidor como herramientas personalizadas servidas por tu worker.



Worker de entorno

Un 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 le asigna una sesión, 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.
• Salidas: en entornos autoalojados, la indicación del sistema de la sesión omite la instrucción /mnt/session/outputs usada en los sandboxes administrados por Anthropic, por lo que los entregables finales terminan donde el agente los escriba en el sistema de archivos de tu sandbox, típicamente bajo el directorio de trabajo.



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 binarios adicionales.
• 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 desde 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 en el proceso.
  • 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 en 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á alcanzando 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 en el ID de 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 sandboxes autoalojados. Para hacer disponibles archivos específicos de la sesión, pasa referencias de archivos (como una ruta de S3 o un SHA de commit) en el campo metadata de la sesión. El elemento de trabajo reclamado no lleva los metadatos de la sesión, pero sí lleva el ID de la sesión: tu script de generación o manejador --on-work recupera la sesión (GET /v1/sessions/{session_id}) para leer el campo metadata, y luego 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.



Sirve herramientas personalizadas desde tu sandbox

Las herramientas personalizadas son herramientas que tu propio código ejecuta: el agente emite un evento agent.custom_tool_use y espera un user.custom_tool_result coincidente. El worker puede ser ese código, y como se ejecuta dentro de tu sandbox, la herramienta alcanza los servicios internos, las credenciales y la salida de red que configuraste para el sandbox, y nada más. La clave de entorno autoriza la publicación de resultados de herramientas personalizadas, por lo que tu clave de API de Claude se mantiene fuera del host del worker.

El worker responde solo a las herramientas registradas con él. Una herramienta personalizada que está declarada en el agente pero no registrada con ningún worker o cliente deja la sesión pausada con una razón de detención requires_action hasta que algo publique su resultado; consulta Manejo de llamadas a herramientas personalizadas para el flujo de eventos.



Envuelve un servidor MCP como herramientas personalizadas

El conector MCP se conecta a servidores MCP desde el lado de Anthropic, por lo que un servidor debe exponer un endpoint HTTP al que Anthropic pueda acceder, directamente o a través de un túnel MCP. Para usar un servidor al que solo tu red puede acceder, haz que el worker sea el cliente MCP en su lugar y declara las herramientas del servidor como herramientas personalizadas. El servidor MCP no necesita conectividad entrante desde fuera de tu red; Anthropic recibe las definiciones de herramientas que declaras en el agente, la entrada de cada llamada y el resultado que tu worker publica de vuelta. En tiempo de ejecución, el modelo llama a una herramienta envuelta como cualquier otra herramienta personalizada:

1. El agente emite un evento agent.custom_tool_use.
2. El worker, dentro de tu sandbox, reenvía la llamada a través de su sesión MCP abierta al servidor en tu red.
3. El worker publica la respuesta del servidor como el user.custom_tool_result.

Los helpers MCP del lado del cliente de los SDK convierten las herramientas del servidor en las herramientas ejecutables que el worker acepta; instala un SDK de MCP junto con el SDK de Anthropic (pip install "anthropic[mcp]" "mcp>=1.24", npm install @modelcontextprotocol/sdk, go get github.com/modelcontextprotocol/go-sdk). Los ejemplos se conectan sin autenticación; para enviar credenciales, configura el cliente HTTP o las opciones de solicitud que le entregas al transporte MCP (http_client en Python, requestInit en TypeScript, HTTPClient en Go).

Ten en cuenta lo siguiente cuando envuelvas un servidor MCP:

• Las herramientas se declaran, no se descubren en tiempo de ejecución. El worker lista las herramientas del servidor MCP una vez al inicio y no puede agregar herramientas a una sesión en ejecución. Cuando las herramientas del servidor cambien, decláralas de nuevo, en el agente o en una sesión inactiva a través de Actualización de la configuración del agente, y reinicia el worker.
• Los nombres y descripciones deben ajustarse a la API de Managed Agents. Los nombres de herramientas personalizadas son únicos por agente y usan letras, dígitos, guiones bajos y guiones (1–128 caracteres); se requiere una descripción (1–4,096 caracteres); y el arreglo tools de un agente acepta como máximo 128 entradas (cada herramienta envuelta es una entrada, y el conjunto de herramientas integrado es una más). La API rechaza una declaración que reutilice un nombre de herramienta, nombre una herramienta personalizada igual que una herramienta integrada del agente como bash o read, o use el prefijo reservado mcp__. Los helpers MCP conservan los nombres y descripciones del servidor, así que renombra o recorta donde sea necesario. Cuando dos servidores exponen el mismo nombre de herramienta, define el envoltorio tú mismo bajo un nombre con prefijo y haz que llame al nombre original de la herramienta del servidor.
• La mayoría de los esquemas pasan sin cambios. La API acepta las palabras clave de JSON Schema que los servidores MCP emiten comúnmente, como additionalProperties y title. Rechaza palabras clave de referencia como $ref en cualquier parte del input_schema de una herramienta personalizada, así que incorpora en línea los esquemas que generadores como pydantic factorizan en $defs. También rechaza oneOf, anyOf y allOf de nivel superior, y nombres de propiedades fuera de letras, dígitos, guiones bajos, puntos y guiones (1–64 caracteres).
• Los fallos de herramientas aparecen como resultados de herramienta con error. Cuando el servidor MCP reporta un error de herramienta, el worker publica un resultado de herramienta con error al que el modelo puede reaccionar. El contenido MCP sin equivalente de resultado de herramienta, como bloques de audio y enlaces a recursos, también aparece como un error. Establece un tiempo de espera en el cliente MCP para un fallo más rápido y claro, como lo hace el ejemplo del worker de Python con read_timeout_seconds. Sin uno, una llamada colgada se convierte en un resultado de error solo cuando se dispara el tiempo de espera de solicitud predeterminado del SDK MCP de TypeScript (alrededor de un minuto) o cuando lo hace el respaldo propio del worker: alrededor de dos minutos y medio en Python, y dos minutos en Go, donde el worker cancela una llamada a herramienta que sobrevive a su valor predeterminado de 120 segundos y publica un resultado de error.
• Envuelve servidores que operes o en los que confíes. El nombre, la descripción y los resultados de una herramienta envuelta entran en el contexto del modelo como los de cualquier otra herramienta: entrada no confiable que puede influir en lo que el agente hace con sus otras herramientas, incluido bash en el host del worker. Declara solo las herramientas que pretendes que el agente use.
• Las políticas de permisos no se aplican a las herramientas personalizadas. Las políticas de permisos gobiernan los conjuntos de herramientas integrados y MCP; el worker ejecuta cada llamada a herramienta envuelta que el modelo haga, así que coloca cualquier paso de aprobación en tu propio código de herramienta.



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 a 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 reclamados por un worker pero aún no confirmados. Los helpers del worker confirman cada elemento antes de procesarlo, por lo que este valor se mantiene cerca de cero en operación normal; un valor distinto de cero sostenido significa que un worker se detuvo entre reclamar y confirmar.
• oldest_queued_at es la marca de tiempo del elemento más antiguo que aún está en la cola, esperando a ser reclamado o reclamado pero aún no confirmado, 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 controlada

Usa work.stop para pedirle al worker que maneja una sesión específica que la apague. De forma predeterminada, el elemento de trabajo pasa a stopping: el worker lo detecta en su siguiente latido de lease, cancela la llamada a herramienta en curso de la sesión y confirma el apagado, momento en el cual el elemento de trabajo pasa a stopped. Pasa force: true en el cuerpo de la solicitud (con la CLI, pasa --force) para marcar el elemento de trabajo como stopped inmediatamente en lugar de esperar la confirmación del worker.

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. Configúralo 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 Work de Environments.

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