Un sandbox alojado por OpenAI le ofrece a tu agente un espacio de trabajo Linux con Python, Node.js y herramientas de línea de comandos. OpenAI lo aprovisiona y conecta; tu aplicación proporciona la tarea y recupera los resultados. Elige un sandbox autoalojado cuando necesites tu propia imagen, recursos de cómputo o red privada.
Configura el sandbox
Establece environment.type en openai_hosted y agrega solo la configuración que tu carga de trabajo
necesite. El directorio de trabajo es /workspace.
packages: instala paquetes de Python, del sistema o globales denpmmediante las listaspython,systemonpm. Fija las versiones cuando sea necesario, por ejemplo,pandas==2.2.3.setup_commands: ejecuta comandos de shell en orden antes de que se inicie el agente, por ejemplo,[{ "command": "mkdir -p reports" }]. Cada comando tiene su propiocwdopcional, cuyo valor predeterminado es/workspace.files: proporciona archivos de entrada mediante un ID de la API de archivos o contenido base64 en línea.env: establece variables de entorno con valores de cadena. Se rechazan los nombres reservados por el entorno de ejecución, incluidosPATH,CODEX_*yOPENAI_API_KEY.skills,plugins,capability_directories: agrega habilidades y complementos.environment_template_id: reutiliza la configuración guardada entre sesiones. Los ajustes omitidos se heredan de la plantilla; las modificaciones de red no pueden ampliar lo que permite su política.
Los paquetes y los archivos de entrada se preparan antes de ejecutar los comandos de configuración. Un código de salida de configuración distinto de cero impide que se inicie el agente. Usa un comando de configuración para comprobar las dependencias o los archivos necesarios. Las plantillas guardan la configuración, no un espacio de trabajo en ejecución.
Controla el acceso a la red
network.access | Comportamiento |
|---|---|
enabled | Permite el acceso de salida. Es la opción predeterminada, a menos que heredes una política de plantilla. |
disabled | Bloquea el acceso de salida. |
restricted | Permite solo los hosts incluidos en allowed_domains. |
El modo restringido acepta entre 1 y 100 nombres de host exactos, como api.example.com.
No incluyas comodines, protocolos, rutas ni puertos. Los subdominios y los destinos de las redirecciones
necesitan sus propias entradas. Actualmente, los servidores MCP alojados que usan stdio requieren
acceso enabled; consulta los requisitos de MCP por stdio.
Verifica que la configuración se haya completado correctamente
La respuesta de creación de sesión indica que la configuración ha comenzado. Consulta
GET /v1/agents/environments/{environment_id} usando el environment.id de la sesión:
provisioning indica que la configuración está en curso; connected indica que se completó correctamente.
Si el estado es failed, consulta environment.error en el evento agent.session.environment.failed.
Espera a que el estado sea connected antes de agregar o listar archivos en el sandbox activo.
Archivos y tiempo de vida
Cada sesión tiene un espacio de trabajo independiente. Los archivos se conservan entre turnos mientras
exista su sandbox. Los archivos de /workspace/outputs se publican como artefactos
inmutables cuando finaliza un turno; esas copias siguen disponibles para descargar después de que
expire el sandbox.
Consulta Archivos y artefactos para obtener información sobre cargas, reglas de rutas, operaciones con archivos en el sandbox activo, descargas y límites. Guarda los archivos de salida que necesites antes de eliminar la sesión.
Expiración del sandbox
Los sandboxes conectados reciben señales de mantenimiento de conexión, incluso entre turnos. Si no hay actividad ni señales de mantenimiento de conexión durante una hora, el sandbox puede eliminarse. Este tiempo de espera no se puede configurar.
Elimina la sesión cuando termines para solicitar la limpieza del sandbox. Si la eliminación
devuelve 409 mientras termina la configuración o la ejecución, espera y vuelve a intentarlo con un límite
de intentos. Cerrar un flujo de eventos no cancela la tarea.
Precios
A los sandboxes alojados por OpenAI se les aplican las tarifas de contenedores estándar. El uso del modelo se factura por separado según las tarifas de la API del modelo seleccionado.
Ejemplo: crea un informe
Proporciona al agente un CSV que contenga 10, 20 y 30. El agente ejecuta Python para calcular
la suma y escribe /workspace/outputs/summary.json.
Establece OPENAI_API_KEY en la terminal de tu aplicación siguiendo los
requisitos previos del inicio rápido.
Mantén esta clave fuera del sandbox. Usa una versión del
SDK de OpenAI que incluya la API de agentes en versión beta.
from openai import OpenAI
client = OpenAI()
stream = client.beta.agents.sessions.create(
agent={"model": "gpt-6-astra"},
environment={
"type": "openai_hosted",
"network": {"access": "disabled"},
"files": [
{
"type": "inline",
"path": "/workspace/amounts.csv",
"data": "YW1vdW50CjEwCjIwCjMwCg==",
}
],
},
input="Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
stream=True,
)
with stream:
for event in stream:
print(event.model_dump_json())El valor base64 de files contiene el CSV de entrada. El código imprime los eventos de la sesión.
Guarda el session.id de agent.session.created. Después de agent.session.turn.completed,
lista los artefactos, busca summary.json
y descárgalo. Su contenido debería ser:
{ "total": 60 }
Que un turno haya finalizado no garantiza que todas las herramientas hayan funcionado correctamente. Si la tarea falla o el flujo termina antes de que se complete, inspecciona los elementos guardados de la sesión. Elimina la sesión cuando termines.
Solución de problemas
| Problema | Qué revisar |
|---|---|
| La configuración falla | Inspecciona el evento de error del entorno y corrige el error del paquete, archivo de entrada o comando de configuración antes de crear otra sesión. |
| Se bloquea una solicitud del sandbox | Revisa network y los hosts a los que se accede mediante redirecciones. |
| Falla una operación con archivos en el sandbox activo | Confirma que el sandbox esté en estado connected. Si expiró, crea una nueva sesión y vuelve a proporcionar los datos de entrada. |
Una solicitud de estado o de lista de archivos devuelve 5xx | Vuelve a intentarlo con intervalos de espera cada vez mayores y un plazo límite. Conserva el ID de la solicitud si el error persiste. |