Configuración del entorno en la nube

Los entornos definen la configuración del contenedor donde se ejecuta tu agente. Creas un entorno una vez y luego haces referencia a su ID cada vez que inicias una sesión. Múltiples sesiones pueden compartir el mismo entorno, pero cada sesión obtiene su propia instancia de contenedor aislada.

Todas las solicitudes de la API de Managed Agents requieren el encabezado beta managed-agents-2026-04-01. El SDK establece el encabezado beta automáticamente.

Crear un entorno

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "python-dev",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)
environment_id=$(jq -r '.id' <<< "$environment")

echo "Environment ID: $environment_id"

El name debe ser único dentro de tu organización y espacio de trabajo.

Usar el entorno en una sesión

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

Opciones de configuración

Paquetes

El campo packages preinstala paquetes en el contenedor antes de que el agente se inicie. Los paquetes se instalan por sus respectivos gestores de paquetes y se almacenan en caché en todas las sesiones que comparten el mismo entorno. Cuando se especifican múltiples gestores de paquetes, se ejecutan en orden alfabético (apt, cargo, gem, go, npm, pip). Opcionalmente puedes fijar versiones específicas; el valor predeterminado es la más reciente.

Gestores de paquetes soportados:

Campo	Gestor de paquetes	Ejemplo
`apt`	Paquetes del sistema (apt-get)	`"ffmpeg"`
`cargo`	Rust (cargo)	`"[email protected]"`
`gem`	Ruby (gem)	`"rails:7.1.0"`
`go`	Módulos Go	`"golang.org/x/tools/cmd/goimports@latest"`
`npm`	Node.js (npm)	`"[email protected]"`

Redes

El campo networking controla el acceso a la red saliente del contenedor. No afecta los dominios permitidos de las herramientas web_search o web_fetch.

Modo	Descripción
`unrestricted`	Acceso completo a la red saliente, excepto por una lista de bloqueo de seguridad general. Este es el valor predeterminado.
`limited`	Restringe el acceso a la red del contenedor a la lista `allowed_hosts`. El acceso adicional se habilita a través de los booleanos `allow_package_managers` y `allow_mcp_servers`.

Para implementaciones en producción, usa redes limited con una lista explícita de allowed_hosts. Sigue el principio de menor privilegio otorgando solo el acceso mínimo a la red que tu agente requiere, y audita regularmente tus dominios permitidos.

Cuando uses redes limited:

allowed_hosts especifica los dominios que el contenedor puede alcanzar. Estos deben tener prefijo HTTPS.
allow_mcp_servers permite el acceso saliente a los puntos finales del servidor MCP configurados en el agente, más allá de los enumerados en el array allowed_hosts. El valor predeterminado es false.
allow_package_managers permite el acceso saliente a registros de paquetes públicos (PyPI, npm, etc.) más allá de los enumerados en el array allowed_hosts. El valor predeterminado es false.

Ciclo de vida del entorno

Los entornos persisten hasta que se archiven o eliminen explícitamente.
Múltiples sesiones pueden hacer referencia al mismo entorno.
Cada sesión obtiene su propia instancia de contenedor. Las sesiones no comparten el estado del sistema de archivos.
Los entornos no tienen versiones. Si actualizas frecuentemente tus entornos, es posible que desees registrar estas actualizaciones de tu lado para mapear el estado del entorno con las sesiones.

Gestionar entornos

Tiempos de ejecución preinstalados

Los contenedores en la nube incluyen tiempos de ejecución comunes listos para usar. Consulta Referencia de contenedor para la lista completa de lenguajes preinstalados, bases de datos y utilidades.

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id"
}
EOF
)

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "data-analysis",
  "config": {
    "type": "cloud",
    "packages": {
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["express"]
    },
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

config=$(cat <<'EOF'
{
  "type": "cloud",
  "networking": {
    "type": "limited",
    "allowed_hosts": ["api.example.com"],
    "allow_mcp_servers": true,
    "allow_package_managers": true
  }
}
EOF
)

# List environments
environments=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Retrieve a specific environment
env=$(curl -fsS "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Archive an environment (read-only, existing sessions continue)
curl -fsS -X POST "https://api.anthropic.com/v1/environments/$environment_id/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

# Delete an environment (only if no sessions reference it)
curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"