Configuración del entorno en la nube

Los entornos definen la configuración del sandbox donde se ejecuta tu agente. Creas un entorno una vez y luego haces referencia a su ID cada vez que inicias una sesión. Varias sesiones pueden compartir el mismo entorno, pero cada sesión obtiene su propio sandbox aislado (un contenedor Linux nuevo).

Esta página cubre los entornos type: cloud. Para ejecutar sandboxes en tu propia infraestructura, consulta Sandboxes autoalojados.

Crear un entorno

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: python-dev
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

Usa un name único y descriptivo para poder distinguir los entornos entre sí.

Usar el entorno en una sesión

Pasa el ID del entorno como una cadena al crear una sesión.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

Opciones de configuración

Paquetes

El campo packages preinstala paquetes en el sandbox antes de que el agente se inicie. Los paquetes se instalan mediante sus respectivos gestores de paquetes y se almacenan en caché entre las sesiones que comparten el mismo entorno. Cuando se especifican varios gestores de paquetes, se ejecutan en orden alfabético (apt, cargo, gem, go, npm, pip). Opcionalmente puedes fijar versiones específicas. Los paquetes sin versión fijada instalan la versión más reciente. Si el entorno usa redes en modo limited, establece también networking.allow_package_managers en true; de lo contrario, la solicitud se rechaza con un error 400.

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted

Gestores de paquetes compatibles:

Redes

El campo networking controla el acceso de red saliente del sandbox. No afecta a las herramientas web_search ni web_fetch, que se ejecutan en los servidores de Anthropic; para restringir los sitios a los que esas herramientas pueden acceder, establece allowed_domains o blocked_domains en la entrada de la herramienta dentro del conjunto de herramientas del agente. Consulta Restringir los dominios de búsqueda web y obtención web.

El siguiente ejemplo crea un entorno con redes en modo limited:

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true

Al usar redes en modo limited:

• allowed_hosts especifica los dominios a los que el sandbox puede acceder. Especifica nombres de host simples o patrones con comodines (como *.example.com). No incluyas un esquema de URL, puerto ni ruta.
• allow_mcp_servers permite el acceso saliente a los endpoints de servidores MCP configurados en el agente, además de los que figuran en el arreglo allowed_hosts. El valor predeterminado es false.
• allow_package_managers permite el acceso saliente a un conjunto de registros de paquetes públicos y servicios de alojamiento de código, además de los que figuran en el arreglo allowed_hosts. Consulta Hosts de gestores de paquetes para ver la lista. El valor predeterminado es false. Establécelo en true siempre que el entorno especifique packages; de lo contrario, la solicitud se rechaza con un error 400, incluso si los hosts del registro figuran en allowed_hosts.

Hosts de gestores de paquetes

Cuando allow_package_managers es true, el sandbox puede acceder a los siguientes hosts además de los que están en allowed_hosts. Anthropic mantiene esta lista y puede cambiarla.

Ciclo de vida del entorno

• Los entornos persisten hasta que se archivan o eliminan explícitamente.
• Cada sesión obtiene su propia instancia de sandbox, incluso cuando varias sesiones hacen referencia al mismo entorno. Las sesiones no comparten el estado del sistema de archivos.
• Los entornos no tienen versiones. Si actualizas un entorno con frecuencia, mantén tu propio registro de los cambios para poder saber qué configuración usó cada sesión.

Administrar entornos

# List environments
environments = client.beta.environments.list()

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
client.beta.environments.delete(environment.id)

Entornos de ejecución preinstalados

Los sandboxes en la nube incluyen de forma predeterminada entornos de ejecución de lenguajes comunes, bases de datos y herramientas de línea de comandos. Consulta la Referencia de sandboxes en la nube para ver la lista completa.

Próximos pasos