OpenAI Agents SDK: cómo ejecutar agentes en los sandboxes de Modal

El flujo de trabajo más reciente de sandbox de los Agents de OpenAI cambia cómo se estructura la ejecución del agente. En lugar de mantener el agente, los archivos, las herramientas y el runtime dentro de un mismo bucle desordenado, el framework separa la capa de orquestación de confianza del entorno de ejecución.

Esto significa que tu aplicación puede encargarse de la lógica del agente, las llamadas al modelo y la toma de decisiones, mientras que el trabajo real sucede dentro de un espacio aislado (sandbox) con acceso a archivos, comandos y salidas generadas.

Esta configuración es especialmente útil cuando tu agente necesita hacer algo más que responder solo con el contexto del prompt. Por ejemplo, puede inspeccionar un proyecto, escribir o modificar archivos, ejecutar código, probar resultados y generar artefactos en un entorno controlado.

En esta guía aprenderás a combinar el framework de OpenAI Agents con Modal Sandboxes para crear una aplicación agentic práctica. El agente podrá ejecutarse en un entorno aislado de Modal, ejecutar comandos de forma segura, trabajar con archivos y devolver resultados útiles a la aplicación principal.

Si quieres una introducción sin usar sandboxes, te recomiendo leer nuestro OpenAI Agents SDK Tutorial. 

¿Qué hay de nuevo en OpenAI Agents SDK?

El nuevo OpenAI Agents SDK incorpora una forma más limpia de crear agentes que trabajen con archivos reales, herramientas y entornos de ejecución. En lugar de juntar todo en un único bucle de prompts, el SDK ahora separa la capa de orquestación del agente del sandbox donde ocurre el trabajo.

Las novedades clave incluyen:

• Compatibilidad nativa con sandboxes para ejecutar agentes en entornos aislados
• Manifest para definir los archivos, carpetas y salidas a los que el agente puede acceder
• SandboxAgent para conectar el agente con un espacio de trabajo sandbox
• SandboxRunConfig para controlar dónde y cómo se ejecuta el sandbox
• Herramientas al estilo Codex para edición de archivos, comandos de shell e inspección de proyectos
• Compatibilidad con MCP para permitir que los agentes se conecten a herramientas y servicios externos
• Soporte para Skills y AGENTS.md para dar instrucciones de proyecto más claras a los agentes
• Soporte para varios proveedores de sandbox, incluidos Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop y Vercel

En conjunto, estas mejoras facilitan la creación de apps agentic que pueden inspeccionar proyectos, ejecutar código, editar archivos y devolver salidas generadas desde un espacio de trabajo controlado.

1. Configuración del proyecto

En este proyecto de demostración, crearemos un pequeño ejemplo de triaje de tickets de soporte usando OpenAI Agents SDK y Modal Sandboxes. La app creará un espacio de trabajo aislado, añadirá algunos archivos de proyecto y, después, pedirá a un agente GPT-5.4-mini que inspeccione esos archivos antes de responder.

Empieza instalando los paquetes necesarios en tu entorno:

pip install "openai-agents[modal]" modal

Antes de ejecutar el proyecto, necesitas dos cuentas:

• Cuenta de OpenAI: Crea una cuenta en la OpenAI Platform y añade créditos de API con tarjeta. Asegúrate de que tu cuenta esté verificada para acceder a los modelos más recientes compatibles.
• Cuenta de Modal: Regístrate en Modal. El plan gratuito incluye créditos mensuales, suficientes para probar esta guía.

A continuación, añade tu clave de la API de OpenAI a tu entorno local.

• En macOS o Linux: export OPENAI_API_KEY="your_openai_api_key"
• En Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

Luego autentica Modal en local:

modal setup

Se abrirá una ventana del navegador y te pedirá iniciar sesión en Modal. Tras iniciar sesión, aprueba la solicitud de generación del token. Modal añadirá automáticamente las credenciales a tu entorno local.

Cuando todo esté listo, verás en la terminal un mensaje de éxito confirmando que la autenticación en Modal se ha completado.

2. Definir el espacio de trabajo del sandbox

Ahora crea un archivo de Python, por ejemplo main.py, y añade los imports necesarios. Estos imports traen OpenAI Agents SDK, las clases de configuración del sandbox y el cliente de sandbox de Modal. 

import asyncio

from agents import ModelSettings, Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import File
from agents.extensions.sandbox import ModalSandboxClient, ModalSandboxClientOptions

Ahora necesitamos definir el espacio de trabajo del sandbox. En este ejemplo, el workspace incluye un pequeño proyecto de triaje de tickets de soporte con un README.md, un archivo de app y una checklist de lanzamiento.

manifest = Manifest(
    entries={
        "README.md": File(
            content=(
                b"# Support Ticket Triage\n\n"
                b"Small service that labels customer tickets by urgency and team.\n"
            )
        ),
        "src/app.py": File(
            content=(
                b"def route_ticket(subject: str, customer_tier: str) -> dict:\n"
                b"    urgent = customer_tier == \"enterprise\" or \"outage\" in subject.lower()\n"
                b"    return {\n"
                b"        \"priority\": \"high\" if urgent else \"normal\",\n"
                b"        \"team\": \"support-ops\" if urgent else \"customer-care\",\n"
                b"    }\n"
            )
        ),
        "docs/release-checks.md": File(
            content=(
                b"# Release Checks\n\n"
                b"- Confirm routing rules match the current support escalation policy.\n"
            )
        ),
    }
)

El Manifest indica al agente qué archivos existen dentro del sandbox. Así el agente cuenta con una estructura de proyecto real que puede inspeccionar, editar y sobre la que puede razonar, en lugar de depender solo del texto del prompt.

En este caso, el agente podrá revisar la lógica de enrutado de tickets de soporte, consultar la documentación y hacer cambios dentro del espacio de trabajo aislado.

3. Crear el agente de sandbox

Una vez definido el workspace, crea el agente respaldado por sandbox. Un SandboxAgent está pensado para trabajar con un workspace real, lo que significa que puede inspeccionar archivos, entender la estructura del proyecto y responder en función de lo que exista dentro del sandbox.

agent = SandboxAgent(
    name="Modal Sandbox Assistant",
    model="gpt-5.4-mini",
    instructions=(
        "You are a coding assistant reviewing a small production service. "
        "Inspect the sandbox workspace before answering. "
        "Keep the answer short and practical."
    ),
    default_manifest=manifest,
    model_settings=ModelSettings(tool_choice="required"),
)

Aquí nombramos al agente Modal Sandbox Assistant y usamos el modelo gpt-5.4-mini para respuestas más rápidas. Las instrucciones le indican que inspeccione el workspace del sandbox antes de contestar, algo importante cuando la respuesta depende de los archivos reales del proyecto.

El parámetro default_manifest=manifest conecta el agente con el workspace que creamos antes. La opción tool_choice="required" anima al agente a usar las herramientas del sandbox disponibles en lugar de responder solo desde memoria o el contexto del prompt.

4. Crear el cliente de Modal Sandbox

A continuación, crea el cliente del sandbox de Modal. Es la conexión entre el flujo de trabajo de OpenAI Agents y el sandbox de Modal, donde se ejecutarán realmente los archivos y los comandos.

client = ModalSandboxClient()
options = ModalSandboxClientOptions(
    app_name="openai-agents-modal-demo",
    workspace_persistence="tar",
)

Con ModalSandboxClient() indicas al agente que use Modal como proveedor de sandbox. Así, el agente puede ejecutarse en un entorno aislado de Modal en lugar de hacerlo directamente en tu máquina local.

Las ModalSandboxClientOptions controlan cómo se configura el sandbox de Modal. Aquí, app_name da un nombre claro a la app de Modal, mientras que workspace_persistence="tar" indica a Modal cómo empaquetar y persistir los archivos del workspace durante la ejecución.

5. Iniciar la sesión del sandbox

Con el cliente y las opciones listos, crea el sandbox a partir del manifest e inicia la sesión. 

sandbox = await client.create(
    manifest=manifest,
    options=options,
)

await sandbox.start()

La llamada client.create() crea un nuevo sandbox de Modal usando los archivos definidos en el Manifest. Esto significa que el sandbox arranca con la misma estructura de proyecto, incluyendo README.md, src/app.py y docs/release-checks.md.

Después, await sandbox.start() inicia la sesión del sandbox. En este punto, ya tienes un workspace aislado en vivo ejecutándose en Modal, listo para que el agente inspeccione archivos, ejecute comandos y trabaje con el proyecto.

6. Ejecutar el agente en el sandbox

Cuando el sandbox esté activo, ejecuta el agente contra él pasando la sesión activa a través de SandboxRunConfig. Esto le indica al OpenAI Agents SDK que el agente debe usar el workspace del sandbox de Modal durante la ejecución. 

result = await Runner.run(
    agent,
    (
        "Explain what this service does and name one production check "
        "before release. Keep it under 3 sentences."
    ),
    run_config=RunConfig(
        sandbox=SandboxRunConfig(session=sandbox),
        workflow_name="Modal sandbox example",
    ),
)

print(result.final_output)

Aquí es donde todo encaja. El modelo se encarga del razonamiento, mientras que el sandbox le da acceso a los archivos reales del workspace.

En este ejemplo, el agente puede inspeccionar el proyecto de triaje de tickets de soporte, entender qué hace el servicio, revisar las notas de lanzamiento y devolver una respuesta breve basada en los archivos dentro del sandbox de Modal.

7. Limpiar el sandbox

Cuando termine la ejecución del agente, elimina el sandbox para no dejar sesiones sin uso ejecutándose en Modal.

await client.aclose(sandbox)

Esto elimina la sesión del sandbox una vez que el trabajo ha finalizado. Es una buena práctica porque las sesiones activas consumen recursos de cómputo mientras están en ejecución.

En un proyecto real, deberías colocar esto dentro de un bloque finally. Así te aseguras de que la limpieza se ejecute incluso si la llamada del agente falla o el script da un error.

8. Ejemplo completo de código

Aquí tienes el script completo en un solo lugar. Crea el workspace, inicia un sandbox de Modal, ejecuta el agente dentro, imprime la salida final y después limpia la sesión del sandbox. 

import asyncio

from agents import ModelSettings, Runner
from agents.extensions.sandbox import ModalSandboxClient, ModalSandboxClientOptions
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import File


async def main():
    manifest = Manifest(
        entries={
            "README.md": File(
                content=(
                    b"# Support Ticket Triage\n\n"
                    b"Small service that labels customer tickets by urgency and team.\n"
                )
            ),
            "src/app.py": File(
                content=(
                    b"def route_ticket(subject: str, customer_tier: str) -> dict:\n"
                    b"    urgent = customer_tier == \"enterprise\" or \"outage\" in subject.lower()\n"
                    b"    return {\n"
                    b"        \"priority\": \"high\" if urgent else \"normal\",\n"
                    b"        \"team\": \"support-ops\" if urgent else \"customer-care\",\n"
                    b"    }\n"
                )
            ),
            "docs/release-checks.md": File(
                content=(
                    b"# Release Checks\n\n"
                    b"- Confirm routing rules match the current support escalation policy.\n"
                )
            ),
        }
    )

    agent = SandboxAgent(
        name="Modal Sandbox Assistant",
        model="gpt-5.4-mini",
        instructions=(
            "You are a coding assistant reviewing a small production service. "
            "Inspect the sandbox workspace before answering. "
            "Keep the answer short and practical."
        ),
        default_manifest=manifest,
        model_settings=ModelSettings(tool_choice="required"),
    )

    client = ModalSandboxClient()
    options = ModalSandboxClientOptions(
        app_name="openai-agents-modal-demo",
        workspace_persistence="tar",
    )

    sandbox = await client.create(
        manifest=manifest,
        options=options,
    )

    await sandbox.start()

    try:
        result = await Runner.run(
            agent,
            (
                "Explain what this service does and name one production check "
                "before release. Keep it under 3 sentences."
            ),
            run_config=RunConfig(
                sandbox=SandboxRunConfig(session=sandbox),
                workflow_name="Modal sandbox example",
            ),
        )

        print(result.final_output)

    finally:
        await sandbox.aclose()

if __name__ == "__main__":
    asyncio.run(main())

Este script sigue la estructura actual de sandbox de OpenAI y utiliza Modal como backend de ejecución. La lógica del agente permanece en tu app de Python, mientras que el workspace real se ejecuta dentro de un sandbox de Modal.

El bloque finally es importante porque cierra y elimina el sandbox incluso si la ejecución del agente falla. Esto ayuda a mantener tu entorno de Modal limpio y evita dejar sesiones sin uso ejecutándose.

9. Probar la app en local

Cuando tu script esté listo, ejecútalo en local desde una terminal en la misma carpeta donde guardaste main.py:

python main.py

Si todo está bien configurado, el script creará un sandbox de Modal, cargará el manifest, ejecutará el agente de OpenAI contra el workspace, imprimirá la respuesta y luego limpiará el sandbox.

Deberías ver una salida similar a esta:

This service triages customer support tickets by assigning urgency and routing them to the right team. One production check before release is to confirm the routing rules still match the current support escalation policy.

La ejecución puede tardar unos segundos. Mientras se ejecuta, abre tu panel de Modal, haz clic en la app openai-agents-modal-demo y revisa los logs. Es una forma útil de confirmar que el sandbox se creó, se inició, lo usó el agente y se limpió correctamente.

10. Crear una app web interactiva 

El primer script es estático: solo podemos enviar una petición, recibir una respuesta y parar. Para que el proyecto sea más cómodo, podemos convertirlo en una app web interactiva con Gradio. Así podremos chatear con el agente del sandbox, hacer preguntas de seguimiento, crear o editar archivos y ejecutar tests desde una interfaz sencilla en el navegador.

Primero, instala la última versión de Gradio:

pip install gradio

Luego crea un archivo nuevo llamado app.py y copia el código de la app de Gradio (OpenAI-Agents-in-Modal/app.py) en él. Esta app usa la misma configuración de OpenAI Agents y Modal Sandbox, pero la envuelve en una interfaz de chat. El código también reutiliza la sesión del sandbox cuando es posible, así que cada mensaje no tiene que crear desde cero un sandbox nuevo.

Ejecuta la app con:

python app.py

Verás una URL local en tu terminal:

* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set share=True in launch().

Abre la URL local en tu navegador para usar la app de chat. Puedes pedir al agente que inspeccione el proyecto, explique qué hace el servicio, cree nuevos archivos de ayuda, edite archivos existentes o ejecute tests dentro del sandbox de Modal.

Por ejemplo, primero le pedí que explicara qué hace el servicio del proyecto y, en pocos segundos, devolvió una respuesta detallada basada en los archivos del sandbox.

Después le pedí al agente que creara un nuevo archivo auxiliar de enrutado. Esta petición tardó un poco más porque el agente tuvo que modificar el workspace del sandbox, añadir tests y ejecutar la batería de pruebas.

El agente creó src/routing_rules.py, añadió un nuevo archivo de test en tests/test_routing_rules.py y verificó los cambios con pytest. Pasaron los 6 tests, confirmando que el nuevo helper funcionaba correctamente y que la lógica existente de enrutado de tickets seguía intacta.

A alto nivel, esta app de Gradio te da un frontend sencillo para trabajar con un agente de OpenAI respaldado por Modal. El usuario envía un mensaje desde el navegador, la app lo pasa al SandboxAgent, el agente trabaja dentro del sandbox de Modal y la respuesta final aparece en la interfaz de chat.

Reflexiones finales

OpenAI Agents con Modal Sandboxes nos ofrece una forma clara de crear apps agentic que pueden trabajar con archivos reales, ejecutar comandos y devolver resultados útiles desde un entorno aislado. 

La puesta en marcha de Modal fue fluida y crear el sandbox fue sencillo. Una vez conectado todo, el agente pudo inspeccionar el proyecto, crear un nuevo archivo auxiliar de enrutado, añadir tests y confirmar que los 6 tests pasaban.

Dicho esto, construir la app interactiva y configurar el modelo llevó más trabajo del esperado. Los pasos de creación de archivos y pruebas también tardaron más porque el sandbox de Modal a veces hacía timeout. Tuve que aumentar el tiempo de espera del sandbox de 300 segundos a 600 para dar al agente tiempo suficiente para completar todo el flujo.

Otro punto de fricción fue el logging y la visibilidad. Mientras esperaba a que el agente terminara, no siempre quedaba claro qué estaba haciendo el Agents SDK en segundo plano. Incluso los logs de Modal a veces no mostraban suficiente detalle para entender si el agente estaba inspeccionando archivos, editando código o ejecutando tests. 

De cara al futuro, sería útil contar con logs del agente más detallados, similares a los que ves al trabajar con herramientas como Claude Code, donde puedes seguir cada paso con mayor claridad.

En general, es un flujo de trabajo muy sólido para crear apps de agentes en sandbox, especialmente si tu agente necesita trabajar con archivos, código y salidas generadas. Puedes encontrar el proyecto completo en GitHub, clonarlo en local y ejecutarlo tú mismo: kingabzpro/OpenAI-Agents-in-Modal.

Si quieres aprender a fondo cómo construir sistemas de IA avanzados, te recomiendo nuestro curso Building Scalable Agentic Systems.