Sandboxes autoalojados

De forma predeterminada, Managed Agents ejecuta herramientas y código dentro de sandboxes en la nube administrados por Anthropic. Los "self-hosted sandboxes" (sandboxes autoalojados) mantienen la orquestación del lado de Anthropic, pero trasladan la ejecución de herramientas a una 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. Las skills del agente y el contenido de cualquier almacén de memoria adjunto a la sesión son almacenados por Anthropic y copiados a tu sandbox durante la sesión; los cambios que el agente realiza en los archivos de memoria se sincronizan de vuelta con el almacé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 sobre datos que no pueden salir del perímetro 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 combinarlo 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 puede acceder a servidores MCP privados a través de un túnel, y una sesión autoalojada puede usar servidores MCP tanto tunelizados como públicos. Usa ambos cuando quieras que la ejecución y el acceso a herramientas permanezcan dentro de tu perímetro. 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 "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 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 un 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 admite únicamente el patrón siempre activo; el SDK admite tanto el patrón siempre activo como el activado por webhook. Ambos son configurables: consulta Worker autoalojado en la referencia para ver los flags de la CLI, y Helpers del SDK en esta página para ver las opciones del SDK. Para un 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 que se usa en los sandboxes administrados por Anthropic, por lo que los entregables finales quedan donde el agente los escriba en el sistema de archivos de tu sandbox, normalmente bajo el directorio de trabajo.
• /mnt/memory/: los almacenes de memoria adjuntos a la sesión son materializados aquí por el worker del SDK, un directorio por almacén 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; consulta Usar almacenes de memoria.

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 además 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 de binarios adicionales.
• La CLI ant o un SDK de Anthropic (Python, TypeScript o Go) en el host del worker.
• Credenciales: una clave de entorno (generada en la Console en los pasos siguientes) autentica al worker ante 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 solo está disponible en la Console. Los elementos de trabajo reclamados también llevan un secret por sesión que el worker usa para montar almacenes de memoria; no lo generas tú, pero en el patrón de un sandbox por sesión lo reenvías tú mismo al sandbox (consulta Ejecutar un sandbox por sesión).
• Para almacenes de memoria, un host preparado. Si las sesiones en este entorno adjuntarán almacenes de memoria, prepara /mnt/memory en el host del worker antes de iniciar el worker; consulta Preparar el host.

1. 1

   Crea un entorno autoalojado

   En la Console: Workspace > Environments > New > Self-hosted

   O a través de la API:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client = anthropic.Anthropic()
   
   environment = client.beta.environments.create(
       name="self-hosted", config={"type": "self_hosted"}
   )
   print(environment.id)

2. 2

   Genera una clave de entorno

   En la Console, abre el entorno y haz clic en Generate environment key. La generación de claves solo está disponible en la Console, independientemente de si creaste el entorno a través de la Console o de la API. Luego exporta el ID del entorno y la clave en el host del worker:

   export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
   export ANTHROPIC_ENVIRONMENT_ID="env_..."

   

Ejecutar un worker

Elige siempre activo para la configuración más sencilla: un proceso de larga duración sondea la cola continuamente y solo necesita HTTPS de salida. 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 con diferentes niveles de control. EnvironmentWorker cubre la mayoría de los casos de uso; recurre 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 termina. 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. Para permitir que la sesión monte sus almacenes de memoria, pasa también el secret del elemento de trabajo como work_secret (workSecret en TypeScript, WorkSecret en Go) o establece ANTHROPIC_WORK_SECRET; ant beta:worker poll --on-work no establece esa variable, así que lee el secret del JSON del elemento de trabajo que escribe en la entrada estándar de tu script, como se muestra en Ejecutar un sandbox por sesión.
  • memory_sync_interval (memorySyncIntervalMs en TypeScript, MemorySyncInterval en Go) y memory_sync_deletions (memorySyncDeletions, MemorySyncDeletions): con qué frecuencia los almacenes de memoria adjuntos se reconcilian con el servidor mientras la sesión se ejecuta, y si los archivos que el agente elimina localmente también se eliminan del almacén. Consulta Configurar la sincronización para ver unidades, valores predeterminados y cómo deshabilitar el soporte de memoria.
• work.poller(): sondea la cola de trabajo en tu nombre y te entrega cada sesión reclamada. Úsalo cuando quieras decidir qué sucede con cada sesión, por ejemplo lanzar un sandbox en lugar de ejecutar herramientas en 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 comprobación no bloqueante; omitir el parámetro usa el long-poll predeterminado de 999 ms.
  • reclaim_older_than_ms: volver a reclamar elementos de trabajo que fueron reclamados pero nunca confirmados dentro de esta cantidad de milisegundos.
  • auto_stop (autoStop en TypeScript, AutoStop en Go): 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. Desactívalo siempre que lo que ejecute el elemento de trabajo publique la detención por sí mismo: handle_item() lo hace, así que establécelo en false cuando entregues elementos reclamados a handle_item() como hacen los manejadores de webhook de esta página, y también lo hace un sandbox que lances y que sea dueño de la llamada de detención.
• 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

SANDBOX_ENV = (
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
)


async def launch_container(work: BetaSelfHostedWork) -> None:
    print(f"claimed session {work.data.id}")
    # Reemplaza `docker run` con tu propio lanzador de sandbox. Reenvía la clave
    # del entorno (nunca tu clave de API) y el secreto por sesión del elemento de trabajo:
    # el worker interno necesita el secreto para montar los almacenes de memoria de la sesión.
    env = os.environ | {
        "ANTHROPIC_WORK_ID": work.id,
        "ANTHROPIC_SESSION_ID": work.data.id,
        "ANTHROPIC_WORK_SECRET": work.secret or "",
    }
    forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
    launcher = await asyncio.create_subprocess_exec(
        "docker", "run", "--rm", "--detach", *forward, "your-sdk-worker-image", env=env
    )
    await launcher.wait()


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())

Lo que sea que lance el sandbox debe reenviar el secret del elemento de trabajo reclamado hacia él (por ejemplo como ANTHROPIC_WORK_SECRET) junto con los identificadores de sesión, trabajo y entorno, para que el worker en su interior pueda montar los almacenes de memoria de la sesión; consulta Ejecutar un sandbox por sesión.

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. Las herramientas de archivos (read, write, edit, glob, grep) están confinadas al directorio de trabajo más cualquier directorio listado en allowed_roots (allowedRoots en TypeScript, AllowedRoots en Go), y write y edit además rechazan rutas bajo read_only_roots (readOnlyRoots, ReadOnlyRoots). EnvironmentWorker agrega por sí mismo los directorios de los almacenes de memoria de la sesión a estas listas. 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 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)

Verificar 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á 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 ver la respuesta completa de estadísticas y ejemplos en otros lenguajes.

Iniciar 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 que los archivos específicos de la sesión estén disponibles, pasa referencias a 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 sesión: tu script de lanzamiento 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 ver la lista completa de flags de la CLI, y Helpers del SDK para ver las opciones de los helpers del SDK.

Usar almacenes de memoria

Las sesiones en un entorno autoalojado adjuntan almacenes de memoria exactamente igual que las sesiones en entornos en la nube: enuméralos en resources cuando crees la sesión, como se muestra en Adjuntar un almacén de memoria a una sesión. Una sesión acepta hasta 8 almacenes de memoria. En un entorno autoalojado, el worker del SDK, en lugar de la infraestructura de Anthropic, materializa cada almacén para el agente, por lo que los almacenes de memoria allí requieren EnvironmentWorker (o su método handle_item()) del SDK de Python, TypeScript o Go.

El worker de la CLI ant (ant beta:worker poll y ant beta:worker run) no monta almacenes de memoria. Para combinar el sondeador de la CLI con almacenes de memoria, ejecuta el worker del SDK dentro de un sandbox por sesión como se describe en Ejecutar un sandbox por sesión.

Los almacenes de memoria no se pueden adjuntar a sesiones en entornos autoalojados en Claude Platform on AWS.

Cómo maneja el worker la memoria

Cuando el worker reclama un elemento de trabajo cuya sesión tiene almacenes de memoria adjuntos:

1. Descarga cada almacén adjunto a su mount_path en el host del worker, autenticándose con el secret por sesión del elemento de trabajo. El mount_path es el mismo directorio bajo /mnt/memory/ que usan las sesiones en la nube (por ejemplo, /mnt/memory/user-preferences/ para un almacén llamado "User Preferences"), y la indicación del sistema de la sesión se lo describe al agente.
2. Agrega esos directorios a las raíces permitidas de las herramientas de archivos, y los directorios de los almacenes adjuntos con access: "read_only" a sus raíces de solo lectura, de modo que el agente trabaja sobre las memorias con las mismas herramientas read, write, edit, glob y grep que usa en el directorio de trabajo.
3. Reconcilia los cambios locales y remotos después de las llamadas a herramientas, como máximo una vez por intervalo de sincronización (15 segundos de forma predeterminada): las memorias que cambiaron en el almacén se escriben en disco, y los archivos que el agente cambió se suben al almacén.
4. Ejecuta una sincronización final cuando la sesión termina, vacía cualquier subida aún pendiente durante hasta 30 segundos y luego elimina los directorios que creó. Un worker que es cancelado mientras una sesión se ejecuta omite la sincronización final, pero aun así sube los archivos modificados y elimina los directorios antes de terminar.

El almacén de memoria del lado de Anthropic sigue siendo la fuente de verdad. Las versiones de memoria, la redacción y la visualización o edición de memorias en la Console funcionan igual que para las sesiones en la nube, y las lecturas y escrituras de memoria del agente aparecen en el flujo de eventos como eventos de herramientas ordinarios. Dado que cada worker sincroniza en un intervalo, un cambio escrito en una sesión se vuelve visible para otra sesión en ejecución solo después de que ambas hayan sincronizado, normalmente bastante menos de un minuto con el intervalo predeterminado; las sesiones en sandboxes en la nube ven los cambios de las demás casi de inmediato.

Cada directorio de almacén contiene un archivo marcador llamado .anthropic-memory-store que vincula el directorio con su almacén. Déjalo en su lugar: el worker no sincroniza un directorio cuyo marcador falte o haya sido alterado.

Preparar el host

Los almacenes de memoria en sandboxes autoalojados necesitan un sistema de archivos POSIX en el host del worker (el host Linux de Antes de comenzar); los hosts Windows no son compatibles, porque el worker requiere O_NOFOLLOW cuando abre archivos de memoria. Se recomienda un sistema de archivos sensible a mayúsculas y minúsculas, para que las rutas de memoria que difieran solo en mayúsculas y minúsculas no colisionen.

Antes de iniciar el worker, crea el directorio padre y hazlo escribible por el usuario con el que se ejecuta el worker:

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

No crees tú mismo los directorios por almacén. El worker crea el directorio mount_path de cada almacén (por ejemplo, /mnt/memory/user-preferences) cuando una sesión comienza, se niega a iniciar el trabajo de la sesión si ya existe algo en esa ruta, y elimina el directorio cuando la sesión termina. De esto se derivan dos reglas operativas:

• Ejecuta una sesión por sistema de archivos cuando las sesiones adjunten el mismo almacén. Dos sesiones no pueden montar el mismo almacén en un host al mismo tiempo, porque ambas necesitan la misma ruta. Darle a cada sesión su propio sandbox, como se describe en Ejecutar un sandbox por sesión, satisface esta regla.
• Detén los workers de forma ordenada. Cuando detienes un worker mientras una sesión se ejecuta, EnvironmentWorker sube los archivos de memoria modificados de la sesión y elimina sus directorios de almacén solo si es cancelado en lugar de terminado forzosamente: un proceso terminado forzosamente no ejecuta ninguna limpieza, y el worker no instala manejadores de señales por sí mismo. Conecta SIGTERM y SIGINT a la cancelación en el proceso que lo ejecuta: aborta el signal que pasas al worker en TypeScript, cancela el contexto en Go, y en Python cancela la tarea que ejecuta run() o handle_item(). Hazlo desde un manejador de señales cuando tu worker sea el proceso, como hacen los workers independientes de esta página, o desde el propio hook de apagado de tu servidor cuando el worker se ejecute dentro de un manejador de webhook, que no debe apropiarse de las señales del servidor. Luego detén los workers con SIGTERM y dales al menos 30 segundos para terminar antes de cualquier terminación forzosa, porque la subida final puede tardar ese tiempo. Si un worker es terminado forzosamente antes de que se ejecute su limpieza, elimina el directorio de almacén sobrante bajo /mnt/memory/ antes de la siguiente sesión que adjunte ese almacén; cualquier edición en él que no se hubiera sincronizado se pierde.

Ejecuta un sandbox por sesión

El patrón de sandbox por sesión en Ejecuta un worker le da a cada sesión un sistema de archivos nuevo, que es lo que Prepara el host requiere cuando las sesiones adjuntan el mismo almacén. Mantén ant beta:worker poll --on-work (o el work poller del SDK) como el poller en el host.

El punto de entrada ant beta:worker run que se muestra allí no monta almacenes de memoria, así que construye la imagen por sesión alrededor del worker del SDK en su lugar: su punto de entrada construye EnvironmentWorker y llama a handle_item() (handleItem en TypeScript, HandleItem en Go), que lee los identificadores de sesión, trabajo y entorno de las variables ANTHROPIC_* y el secret por sesión del elemento de trabajo desde ANTHROPIC_WORK_SECRET. También puedes pasar el secreto explícitamente como work_secret (workSecret en TypeScript, WorkSecret en Go).

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


async def main() -> None:
    async with AsyncAnthropic(auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]) as client:
        worker = EnvironmentWorker(client, workdir="/workspace")
        # Sin argumentos, handle_item() lee las variables ANTHROPIC_* que el script de
        # lanzamiento reenvió, incluida ANTHROPIC_WORK_SECRET.
        task = asyncio.create_task(worker.handle_item())
        # Cancelar la tarea cuando se detiene el contenedor permite al worker subir
        # los archivos de memoria modificados y eliminar los directorios del almacén antes de salir.
        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())

ant beta:worker poll --on-work no establece ANTHROPIC_WORK_SECRET para el script que lanza, así que el script de lanzamiento lee el secreto del JSON del elemento de trabajo en su entrada estándar y lo pasa al sandbox:

#!/bin/bash
# spawn.sh: se llama una vez por cada elemento de trabajo reclamado
# El elemento de trabajo reclamado llega como JSON por stdin. Su secreto es la
# credencial por sesión que requieren los endpoints del almacén de memoria.
ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
export ANTHROPIC_WORK_SECRET
mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
exec docker run --rm \
  -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
  -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
  -e ANTHROPIC_WORK_SECRET \
  -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
  your-sdk-worker-image

Si en su lugar reclamas trabajo con el work poller del SDK, pasa el secret de cada elemento reclamado al sandbox que lances de la misma manera. Pásalo solo al sandbox que atiende esa sesión, y nunca lo registres en logs.

La imagen del sandbox también necesita un /mnt/memory con permisos de escritura (consulta Prepara el host). Como cada sandbox atiende una sesión y se descarta después, no quedan directorios sobrantes que limpiar, y los directorios de memoria no necesitan montarse con bind-mount en el host: el worker sube su contenido al almacén antes de que el sandbox termine. Si detienes un contenedor antes de que termine su sesión, envía una señal que el punto de entrada convierta en cancelación (consulta Prepara el host) en lugar de matarlo, para que esa subida aún se ejecute. Dale también tiempo al contenedor para terminar la subida: Docker sigue la señal de detención con SIGKILL después de 10 segundos de forma predeterminada, así que eleva ese límite al menos a los 30 segundos que Prepara el host requiere, con --stop-timeout en docker run o el período de gracia de terminación de tu orquestador.

Configura la sincronización

Dos opciones de EnvironmentWorker controlan el comportamiento de la memoria:

• memory_sync_interval (Python, en segundos; memorySyncIntervalMs en TypeScript, en milisegundos; MemorySyncInterval en Go, una duración): con qué frecuencia los almacenes adjuntos se reconcilian con el servidor mientras la sesión se ejecuta. El valor predeterminado es 15 segundos; el mínimo es 5 segundos. Un intervalo más corto reduce la ventana en la que otra sesión ve memorias obsoletas, a costa de más solicitudes al almacén de memoria. None en Python, null en TypeScript o una duración negativa en Go deshabilita por completo el soporte de memoria: el worker no descarga ni sincroniza almacenes, y una sesión con almacenes de memoria adjuntos se ejecuta sin ellos aunque su indicación del sistema aún los describa, así que deshabilita el soporte de memoria solo en workers cuyas sesiones no adjunten almacenes de memoria. Mientras el soporte de memoria está habilitado, un elemento de trabajo que llega sin un secret por sesión para una sesión con almacenes adjuntos falla en lugar de ejecutarse sin memoria (consulta Soluciona problemas de montajes de memoria).
• memory_sync_deletions (memorySyncDeletions en TypeScript, MemorySyncDeletions en Go): si un archivo que el agente elimina localmente también se elimina del almacén. El valor es uno de "enabled" (el predeterminado), "log_only" o "disabled" en Python y TypeScript, y una de las constantes environments.MemorySyncDeletionsEnabled (el valor cero), environments.MemorySyncDeletionsLogOnly o environments.MemorySyncDeletionsDisabled en Go. Cuando está habilitado, el worker elimina la memoria del almacén una vez que una sincronización posterior confirma que el archivo sigue ausente; en modo solo registro ejecuta las mismas comprobaciones pero solo registra lo que habría eliminado, lo que te permite observar qué eliminarían tus workers antes de confiar en el modo habilitado; cuando está deshabilitado, nunca elimina del almacén. Las subidas y descargas no se ven afectadas por esta configuración.

Establece estas opciones donde construyas el worker, ya sea a través del constructor de EnvironmentWorker o, en Python y TypeScript, la fábrica client.beta.environments.work.worker() que usa el manejador de webhooks.

Por ejemplo, para sincronizar cada 10 segundos y solo registrar las eliminaciones que el worker habría hecho:

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

Almacenes de solo lectura y conflictos

Para un almacén adjunto con access: "read_only", las herramientas write y edit se niegan a cambiar archivos dentro de su directorio, y el worker nunca sube nada desde él. Los cambios hechos a través de bash, o a través de una herramienta personalizada o servidor MCP que sirvas desde el sandbox, no se bloquean localmente: nunca se sincronizan con el almacén, y el siguiente cambio remoto a esa memoria los sobrescribe. Si necesitas que la copia local en sí permanezca sin cambios durante la sesión, deshabilita la herramienta bash para ese agente y no le des ninguna herramienta personalizada que escriba en el sistema de archivos del sandbox; no montes la ruta del almacén como solo lectura, porque el propio worker debe crear el directorio y escribir en él las memorias descargadas.

Los conflictos se resuelven a favor del almacén. Cuando el agente cambia un archivo de memoria que también cambió en el almacén desde la última vez que la sesión lo sincronizó, el worker conserva la versión del almacén en la siguiente sincronización, sobrescribe el archivo local con ella y registra una advertencia; las herramientas write y edit en sí tienen éxito y ningún error llega al agente. Si el cambio del agente aún aplica, puede volver a leer el archivo después de la sincronización y hacer el cambio de nuevo.

Soluciona problemas de montajes de memoria

El worker registra los fallos de montaje y de sincronización en segundo plano en lugar de reportarlos a la sesión; solo los rechazos de solo lectura llegan al agente, como errores de herramienta (consulta Almacenes de solo lectura y conflictos). Si un almacén de memoria no puede montarse cuando el worker reclama una sesión, el worker marca el elemento de trabajo como fallido: la sesión no emite ningún evento de error y permanece inactiva.

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 correspondiente. El worker puede ser ese código, y como se ejecuta dentro de tu sandbox, la herramienta alcanza los servicios internos, credenciales y 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, así que tu clave de API de Claude se mantiene fuera del host del worker.

1. 1

   Declara la herramienta en el agente

   Agrega una entrada custom a las tools del agente cuyo name coincida con la herramienta que tu worker registra. Consulta Herramientas personalizadas para la forma completa de la declaración.

   {
     "type": "custom",
     "name": "get_order_status",
     "description": "Look up an order in the internal fulfillment system by order ID.",
     "input_schema": {
       "type": "object",
       "properties": {
         "order_id": { "type": "string", "description": "The order ID" }
       },
       "required": ["order_id"]
     }
   }

   
2. 2

   Registra la implementación con el worker

   Pasa la herramienta a través de la fábrica tools del worker (consulta Helpers del SDK), junto con el conjunto de herramientas integrado:

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   import os
   from anthropic import AsyncAnthropic, beta_async_tool
   from anthropic.lib.environments import EnvironmentWorker
   from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
   
   
   @beta_async_tool
   async def get_order_status(order_id: str) -> str:
       """Look up an order in the internal fulfillment system by order ID."""
       # Se ejecuta en el host del worker: llama a cualquier cosa que el sandbox pueda alcanzar.
       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:
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
               tools=lambda env: [*beta_agent_toolset_20260401(env), get_order_status],
           ).run()
   
   
   asyncio.run(main())

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 en pausa con un motivo 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, así que un servidor debe exponer un endpoint HTTP que Anthropic pueda alcanzar, directamente o a través de un túnel MCP. Para usar un servidor que solo tu red puede alcanzar, 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 a 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).

1. 1

   Declara las herramientas del servidor en el agente

   Lista las herramientas del servidor MCP y declara cada una como una herramienta custom; los campos name, description e inputSchema de MCP se corresponden uno a uno con los campos de la herramienta personalizada. Si el servidor pagina su lista de herramientas, declara cada página; el worker debe listar las mismas páginas.

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   from typing import Any, cast
   from anthropic import AsyncAnthropic
   from anthropic.types.beta import BetaManagedAgentsCustomToolParams
   from mcp import ClientSession, types
   # Requiere mcp >= 1.24, que renombró streamablehttp_client a streamable_http_client.
   from mcp.client.streamable_http import streamable_http_client
   
   MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
   
   
   def to_custom_tool(tool: types.Tool) -> BetaManagedAgentsCustomToolParams:
       # Los campos MCP se corresponden uno a uno con una declaración de herramienta personalizada. El cast
       # entrega el diccionario del esquema al parámetro tipado del SDK sin cambios.
       return {
           "type": "custom",
           "name": tool.name,
           "description": tool.description or tool.name,
           "input_schema": cast(Any, tool.inputSchema),
       }
   
   
   async def main() -> None:
       # Ejecuta esto donde crees los agentes, no en el host worker:
       # se autentica con tu clave de API de Claude (ANTHROPIC_API_KEY).
       async with (
           streamable_http_client(MCP_SERVER_URL) as (read, write, _),
           ClientSession(read, write) as mcp_session,
           AsyncAnthropic() as client,
       ):
           await mcp_session.initialize()
           listed = await mcp_session.list_tools()
           agent = await client.beta.agents.create(
               name="Internal tools agent",
               model="claude-opus-5",
               tools=[
                   {"type": "agent_toolset_20260401"},
                   *[to_custom_tool(tool) for tool in listed.tools],
               ],
           )
           print(agent.id)
   
   
   asyncio.run(main())

2. 2

   Sirve las herramientas desde el worker

   Conéctate al mismo servidor MCP al iniciar, convierte sus herramientas con los helpers MCP y regístralas junto con el conjunto de herramientas integrado. Mantén una sesión MCP abierta durante toda la vida del worker.

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   import os
   from datetime import timedelta
   from anthropic import AsyncAnthropic
   from anthropic.lib.environments import EnvironmentWorker
   from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
   from anthropic.lib.tools.mcp import async_mcp_tool
   from mcp import ClientSession
   # Requiere mcp >= 1.24, que renombró streamablehttp_client a streamable_http_client.
   from mcp.client.streamable_http import streamable_http_client
   
   MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
   
   
   async def main() -> None:
       environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
       environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
       # Conéctate al servidor MCP una vez al inicio y mantén la sesión abierta durante
       # la vida del worker. El timeout convierte una llamada a herramienta colgada en un
       # resultado de error en lugar de una llamada estancada.
       async with (
           streamable_http_client(MCP_SERVER_URL) as (read, write, _),
           ClientSession(read, write, read_timeout_seconds=timedelta(seconds=60)) as mcp_session,
           AsyncAnthropic(auth_token=environment_key) as client,
       ):
           await mcp_session.initialize()
           listed = await mcp_session.list_tools()
           mcp_tools = [async_mcp_tool(tool, mcp_session) for tool in listed.tools]
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
               tools=lambda env: [*beta_agent_toolset_20260401(env), *mcp_tools],
           ).run()
   
   
   asyncio.run(main())

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 iniciar 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 no vacía; 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 de agente integrada 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 tú mismo el envoltorio bajo un nombre con prefijo y haz que llame al nombre de herramienta original 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 en resultados 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 hace el ejemplo del worker en 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 de MCP para 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 sobrepasa 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 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 hace, 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, así que no llamas a esos endpoints directamente.

Lee 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 alerta 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, así que este valor se mantiene cerca de cero en operación normal; un valor distinto de cero sostenido significa que un worker se estancó entre reclamar y confirmar.
• oldest_queued_at es la marca de tiempo del elemento más antiguo aún en la cola, esperando 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 hecho polling en los últimos 30 segundos. Usa esto para alertas de disponibilidad.

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
}

Detén una sesión de forma ordenada

Usa work.stop para pedirle al worker que maneja una sesión específica que la cierre. De forma predeterminada el elemento de trabajo pasa a stopping: el worker lo nota en su siguiente heartbeat de lease, cancela la llamada a herramienta en curso de la sesión y confirma el cierre, momento en el que 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.

Como estas llamadas se ejecutan desde tus herramientas de operaciones en lugar del host del worker, ANTHROPIC_WORK_ID no se establece automáticamente. Establécelo al 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