For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegación principal

Sandboxes alojados por OpenAI

Ejecuta código y crea archivos descargables sin administrar recursos de cómputo.

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 de npm mediante las listas python, system o npm. 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 propio cwd opcional, 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, incluidos PATH, CODEX_* y OPENAI_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.accessComportamiento
enabledPermite el acceso de salida. Es la opción predeterminada, a menos que heredes una política de plantilla.
disabledBloquea el acceso de salida.
restrictedPermite 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.

Crear summary.json
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

ProblemaQué revisar
La configuración fallaInspecciona 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 sandboxRevisa network y los hosts a los que se accede mediante redirecciones.
Falla una operación con archivos en el sandbox activoConfirma 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 5xxVuelve a intentarlo con intervalos de espera cada vez mayores y un plazo límite. Conserva el ID de la solicitud si el error persiste.