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
Theme

Sandboxes alojados por OpenAI

Ejecuta código y crea archivos descargables sin tener que 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 se encarga de aprovisionar y conectar el sandbox. Tu aplicación proporciona la tarea y recupera los resultados. Elige un sandbox autoalojado cuando necesites usar tu propia imagen, tus propios recursos de cómputo o tu red privada.

Para tareas que interactúan con sitios web mediante un navegador, consulta Uso de la computadora.

Para preparar el espacio de trabajo antes de crear una sesión, consulta Preparar sandboxes con anticipación.

Configurar el sandbox

Establece environment.type en openai_hosted en la solicitud de creación de la sesión. Agrega solo los parámetros que necesite tu carga de trabajo. El directorio de trabajo del sandbox es /workspace.

Elige los recursos y el acceso a la red que necesita tu tarea con container_size y network. Si usas una plantilla de entorno, los parámetros que omitas tomarán los valores de la plantilla.

Preparar paquetes y archivos

Usa estos parámetros para que las dependencias y los archivos de entrada estén disponibles en el sandbox:

  • packages: instala paquetes de Python, paquetes del sistema o paquetes globales de npm mediante las listas python, system o npm. Cuando sea necesario, especifica una versión exacta, por ejemplo, pandas==2.2.3.
  • files: proporciona archivos de entrada mediante su ID en la API de archivos o incluye directamente su contenido en base64.

Ejecutar comandos de configuración

Usa setup_commands para ejecutar comandos de shell en orden antes de que se inicie el agente. Por ejemplo, [{ "command": "mkdir -p reports" }] crea un directorio. Cada comando puede definir su propio cwd. El valor predeterminado es /workspace.

Los paquetes y los archivos de entrada se preparan antes de que se ejecuten los comandos de configuración. Usa un comando de configuración para comprobar que estén disponibles las dependencias o los archivos necesarios. Si un comando de configuración devuelve un código de salida distinto de cero, el agente no se inicia.

Definir variables de entorno

Usa env para definir variables de entorno cuyos valores sean cadenas de texto. El código que genere el agente puede leer esos valores.

Para los secretos, usa credenciales de la bóveda para mantener los valores reales fuera del sandbox. El entorno de ejecución rechaza los nombres que tiene reservados, entre ellos PATH, CODEX_* y OPENAI_API_KEY.

Elegir el tamaño del contenedor

Al crear una sesión, establece environment.container_size para elegir los recursos de CPU y memoria disponibles en tu sandbox. El valor predeterminado es medium.

Tamaño vCPU Memoria
small 1 1 GB
medium 2 4 GB
large 4 16 GB

Por ejemplo, incluye este entorno en tu solicitud POST /v1/agents/sessions para seleccionar small:

{
  "environment": {
    "type": "openai_hosted",
    "container_size": "small"
  }
}

La sesión que recibes en la respuesta indica el tamaño seleccionado en environment.container_size. Este parámetro solo se aplica a los sandboxes alojados por OpenAI.

Controlar el acceso a la red

network.access Comportamiento
enabled Permite las conexiones salientes. Es la opción predeterminada, salvo que heredes la política de una plantilla.
disabled Bloquea las conexiones salientes.
restricted Permite conexiones solo a los hosts que figuran en allowed_domains.

El modo restringido admite 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 el nivel de acceso enabled. Consulta los requisitos de MCP para stdio.

Agregar habilidades y complementos

Usa skills, plugins y capability_directories para agregar habilidades y complementos.

Reutilizar la configuración en varias sesiones

Establece environment_template_id para reutilizar una configuración guardada. Los parámetros que omitas tomarán los valores de la plantilla. Si modificas la configuración de red, no puedes ampliar el acceso que permite la política de la plantilla. Las plantillas solo guardan la configuración. No conservan un espacio de trabajo en ejecución.

Comprobar que la configuración se completó correctamente

La respuesta a la solicitud de creación de la sesión indica que la configuración ya comenzó. Para comprobar su estado, envía una solicitud GET /v1/agents/environments/{environment_id} con el valor de environment.id de la sesión.

Estado Qué hacer
provisioning Espera mientras se configura el entorno.
connected La configuración se completó correctamente. Puedes agregar archivos al sandbox activo o ver la lista de archivos que contiene.
failed Consulta environment.error en el evento agent.session.environment.failed.

Espera a que el estado sea connected antes de agregar archivos al sandbox activo o consultar su lista de archivos.

Archivos y duración del sandbox

Cada sesión tiene su propio espacio de trabajo. Los archivos se conservan entre turnos mientras exista el sandbox de la sesión. Al finalizar un turno, los archivos de /workspace/outputs se publican como artefactos inmutables. Esas copias se pueden descargar incluso después de que expire el sandbox.

Consulta Archivos y artefactos para obtener información sobre la carga de archivos, las reglas para las rutas, las operaciones con archivos del sandbox activo, las descargas y los límites. Guarda los resultados que necesites antes de eliminar la sesión.

Expiración del sandbox

Los sandboxes conectados reciben señales para mantener activa la conexión, incluso entre turnos. Si durante una hora no hay actividad ni se reciben esas señales, el sandbox puede eliminarse. Este tiempo de espera no se puede configurar.

Cuando termines, elimina la sesión para solicitar la limpieza del sandbox. Si la solicitud de eliminación devuelve 409 mientras finaliza la configuración o la ejecución, espera antes de volver a intentarlo y limita el número de intentos. Cerrar un flujo de eventos no cancela la tarea.

Precios

A los sandboxes alojados por OpenAI se les aplican las tarifas estándar de los contenedores. El uso del modelo se factura por separado según las tarifas de la API correspondientes al modelo seleccionado.

Ejemplo: crear un informe

Proporciona al agente un archivo CSV con los valores 10, 20 y 30. El agente ejecuta Python para calcular la suma y escribe el resultado en /workspace/outputs/summary.json.

Define OPENAI_API_KEY en la terminal de tu aplicación siguiendo los requisitos previos de la guía de inicio rápido. Mantén esta clave fuera del sandbox. Usa una versión del SDK de OpenAI que incluya la versión beta de la API de agentes.

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.with_result_collection():
    for event in stream:
        print(event.model_dump_json())
    result = stream.get_final_result()

client.beta.agents.sessions.artifacts.for_result(result).download(
    "/workspace/outputs/summary.json", to="summary.json"
)

El valor en base64 de files contiene el CSV de entrada. El código imprime los eventos de la sesión. Guarda el valor de session.id del evento agent.session.created. Después de agent.session.turn.completed, consulta la lista de artefactos, busca summary.json y descárgalo. Su contenido debería ser:

{ "total": 60 }

Que un turno se complete no garantiza que todas las herramientas se hayan ejecutado correctamente. Si la tarea falla o el flujo de eventos termina antes de que finalice el turno, revisa los elementos guardados de la sesión. Elimina la sesión cuando termines.

Solución de problemas

Problema Qué revisar
Falla la configuración Revisa el evento que indica el fallo del entorno y corrige el error en el paquete, el archivo de entrada o el 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 del sandbox activo Verifica que el estado del sandbox sea connected. Si el sandbox expiró, crea otra sesión y vuelve a proporcionar los archivos de entrada.
Una solicitud para consultar el estado o la lista de archivos devuelve 5xx Aumenta la espera entre intentos y fija un plazo máximo para los reintentos. Si el error persiste, conserva el ID de la solicitud.