OpenAI Agents SDK : exécuter des agents dans des sandboxes Modal

Le nouveau flux de travail sandbox des Agents d'OpenAI change la façon dont l'exécution d'un agent est structurée. Au lieu de garder l'agent, les fichiers, les outils et l'exécution dans une seule boucle peu lisible, le framework sépare la couche d'orchestration de confiance de l'environnement d'exécution.

Concrètement, votre application gère la logique de l'agent, les appels au modèle et la prise de décision, tandis que le travail effectif s'exécute dans un espace de travail isolé avec accès aux fichiers, aux commandes et aux sorties générées.

Cette approche est particulièrement utile lorsque votre agent doit faire plus que répondre à partir du seul contexte du prompt. Par exemple, il peut inspecter un projet, écrire ou modifier des fichiers, exécuter du code, tester des sorties et générer des artefacts dans un environnement contrôlé.

Dans ce guide, nous allons combiner le framework OpenAI Agents avec les Modal Sandboxes pour construire une application agentique concrète. L'agent pourra s'exécuter dans un environnement Modal isolé, lancer des commandes en toute sécurité, travailler avec des fichiers et renvoyer des résultats utiles à l'application principale.

Pour une introduction sans sandboxes, nous vous recommandons aussi de lire notre OpenAI Agents SDK Tutorial. 

Quoi de neuf dans l'OpenAI Agents SDK ?

La nouvelle version de l'OpenAI Agents SDK propose une façon plus claire de créer des agents capables de travailler avec de vrais fichiers, outils et environnements d'exécution. Plutôt que de tout conserver dans une unique boucle de prompt, le SDK sépare désormais la couche d'orchestration de l'agent du sandbox où le travail s'effectue.

Les principales nouveautés incluent :

• Prise en charge native des sandboxes pour exécuter des agents dans des environnements isolés
• Manifest pour définir les fichiers, dossiers et sorties accessibles à l'agent
• SandboxAgent pour relier l'agent à un espace de travail sandboxé
• SandboxRunConfig pour contrôler le lieu et la façon dont le sandbox s'exécute
• Outils de style Codex pour l'édition de fichiers, les commandes shell et l'inspection de projet
• Prise en charge de l'MCP pour connecter des agents à des outils et services externes
• Skills et prise en charge d'AGENTS.md pour fournir des consignes de projet plus claires aux agents
• Compatibilité avec plusieurs fournisseurs de sandbox, dont Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop et Vercel

Ensemble, ces évolutions facilitent la création d'applications agentiques capables d'inspecter des projets, d'exécuter du code, d'éditer des fichiers et de rentrer des sorties générées depuis un espace de travail contrôlé.

1. Configuration du projet

Dans ce projet de démonstration, nous allons construire un petit exemple de tri de tickets support avec l'OpenAI Agents SDK et les Modal Sandboxes. L'application créera un espace de travail sandboxé, y ajoutera quelques fichiers de projet, puis demandera à un agent GPT-5.4-mini d'inspecter ces fichiers avant de répondre.

Commencez par installer les paquets requis dans votre environnement :

pip install "openai-agents[modal]" modal

Avant d'exécuter le projet, vous aurez besoin de deux comptes :

• Compte OpenAI : Créez un compte sur la plateforme OpenAI et ajoutez des crédits API avec une carte bancaire. Assurez-vous que votre compte est vérifié pour accéder aux derniers modèles pris en charge.
• Compte Modal : Inscrivez-vous sur Modal. L'offre gratuite inclut des crédits mensuels, suffisants pour tester ce guide.

Ensuite, ajoutez votre clé d'API OpenAI à votre environnement local.

• Sur macOS ou Linux : export OPENAI_API_KEY="your_openai_api_key"
• Sur Windows PowerShell : $env:OPENAI_API_KEY="your_openai_api_key"

Puis authentifiez Modal en local :

modal setup

Une fenêtre de navigateur s'ouvrira et vous demandera de vous connecter à Modal. Après connexion, approuvez la génération du jeton. Modal ajoutera automatiquement les identifiants à votre environnement local.

Une fois terminé, vous devriez voir un message de succès dans votre terminal confirmant que l'authentification Modal est réussie.

2. Définir l'espace de travail du sandbox

Créez ensuite un fichier Python, par exemple main.py, et ajoutez les imports nécessaires. Ils apportent l'OpenAI Agents SDK, les classes de configuration du sandbox et le client 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

Nous devons maintenant définir l'espace de travail du sandbox. Dans cet exemple, il inclut un petit projet de tri de tickets support avec un README.md, un fichier d'application et une checklist de publication.

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"
            )
        ),
    }
)

Le Manifest indique à l'agent quels fichiers existent dans le sandbox. L'agent dispose ainsi d'une structure de projet réelle à inspecter, éditer et analyser, plutôt que de s'appuyer uniquement sur le texte du prompt.

Dans notre cas, l'agent peut revoir la logique de routage des tickets, consulter la documentation et effectuer des modifications dans l'espace de travail isolé.

3. Créer l'agent sandbox

Une fois l'espace de travail défini, créez l'agent adossé au sandbox. Un SandboxAgent est conçu pour travailler avec un espace de travail réel : il peut donc inspecter les fichiers, comprendre la structure du projet et répondre en fonction de ce qui existe dans le 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"),
)

Ici, nous nommons l'agent Modal Sandbox Assistant et utilisons le modèle gpt-5.4-mini pour des réponses plus rapides. Les consignes demandent à l'agent d'inspecter l'espace de travail avant de répondre, ce qui est crucial lorsque la réponse dépend des fichiers réels du projet.

Le paramètre default_manifest=manifest relie l'agent à l'espace de travail que nous avons créé. L'option tool_choice="required" encourage l'agent à utiliser les outils du sandbox plutôt que de répondre uniquement depuis sa mémoire ou le contexte du prompt.

4. Créer le client Modal Sandbox

Créez ensuite le client Modal sandbox. C'est la connexion entre le flux de travail OpenAI Agents et le sandbox Modal, où l'exécution des fichiers et commandes a effectivement lieu.

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

Le ModalSandboxClient() indique à l'agent d'utiliser Modal comme fournisseur de sandbox. L'agent s'exécute ainsi dans un environnement isolé Modal, plutôt que directement sur votre machine locale.

Les ModalSandboxClientOptions contrôlent la configuration du sandbox Modal. Ici, app_name donne un nom clair à l'app Modal, tandis que workspace_persistence="tar" précise comment empaqueter et conserver les fichiers de l'espace de travail pendant l'exécution.

5. Démarrer la session sandbox

Maintenant que le client et les options sont prêts, créez le sandbox à partir du manifest et lancez la session.

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

await sandbox.start()

L'appel client.create() crée un nouveau sandbox Modal en utilisant les fichiers définis dans le Manifest. Le sandbox démarre donc avec la même structure de projet, incluant README.md, src/app.py et docs/release-checks.md.

Ensuite, await sandbox.start() lance la session sandbox. À ce stade, vous disposez d'un espace de travail isolé en direct sur Modal, prêt pour que l'agent inspecte des fichiers, exécute des commandes et travaille sur le projet.

6. Exécuter l'agent dans le sandbox

Une fois le sandbox actif, exécutez l'agent dessus en passant la session live via SandboxRunConfig. Vous indiquez ainsi au SDK OpenAI Agents que l'agent doit utiliser l'espace de travail Modal pendant le run.

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)

C'est ici que tout s'assemble. Le modèle gère le raisonnement, tandis que le sandbox lui donne accès aux fichiers réels de l'espace de travail.

Dans cet exemple, l'agent peut inspecter le projet de tri des tickets, comprendre ce que fait le service, consulter les notes de publication et renvoyer une réponse courte fondée sur les fichiers du sandbox Modal.

7. Nettoyer le sandbox

Après l'exécution de l'agent, supprimez le sandbox afin de ne pas laisser de sessions inutilisées tourner dans Modal.

await client.aclose(sandbox)

Cela supprime la session une fois le travail terminé. C'est une bonne pratique, car des sessions actives consomment des ressources de calcul.

Dans un projet réel, placez cette étape dans un bloc finally pour garantir le nettoyage même en cas d'échec de l'appel ou d'erreur du script.

8. Exemple de code complet

Voici le script complet en un seul endroit. Il crée l'espace de travail, démarre un sandbox Modal, exécute l'agent à l'intérieur, affiche la sortie finale, puis nettoie la session.

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())

Ce script suit la structure sandbox actuelle d'OpenAI et utilise Modal comme moteur d'exécution. La logique de l'agent reste dans votre application Python, tandis que l'espace de travail s'exécute dans un sandbox Modal.

Le bloc finally est important : il ferme et supprime le sandbox même si l'exécution de l'agent échoue. Cela aide à garder votre environnement Modal propre et à éviter des sessions inutiles.

9. Tester l'application en local

Une fois le script prêt, exécutez-le en local depuis un terminal dans le même dossier que main.py :

python main.py

Si tout est correctement configuré, le script va créer un sandbox Modal, y charger le manifest, exécuter l'agent OpenAI sur l'espace de travail, afficher la réponse, puis nettoyer le sandbox.

Vous devriez voir une sortie similaire à ceci :

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.

L'exécution peut prendre quelques secondes. Pendant ce temps, ouvrez votre tableau de bord Modal, cliquez sur l'app openai-agents-modal-demo et consultez les logs. C'est utile pour vérifier que le sandbox a été créé, démarré, utilisé par l'agent et correctement nettoyé.

10. Créer une application web interactive 

Le premier script est statique : on envoie une requête, on reçoit une réponse et on s'arrête. Pour faciliter l'usage, transformons-le en application web interactive avec Gradio. Vous pourrez ainsi discuter avec l'agent sandbox, poser des questions de suivi, créer ou éditer des fichiers et lancer des tests depuis une interface navigateur simple.

Commencez par installer la dernière version de Gradio :

pip install gradio

Créez ensuite un nouveau fichier nommé app.py et copiez le code de l'app Gradio (OpenAI-Agents-in-Modal/app.py) dedans. Cette app reprend la même configuration OpenAI Agents + Modal Sandbox, mais l'encapsule dans une interface de chat. Le code réutilise également la session du sandbox quand c'est possible, évitant de recréer un environnement à chaque message.

Lancez l'app avec :

python app.py

Vous devriez voir une URL locale dans votre terminal :

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

Ouvrez cette URL dans votre navigateur pour utiliser l'app de chat. Vous pouvez demander à l'agent d'inspecter le projet, d'expliquer le service, de créer des fichiers utilitaires, d'éditer des fichiers existants ou d'exécuter des tests dans le sandbox Modal.

Par exemple, je lui ai d'abord demandé d'expliquer ce que fait le service du projet ; en quelques secondes, il a renvoyé une réponse détaillée basée sur les fichiers du sandbox.

Je lui ai ensuite demandé de créer un nouveau fichier utilitaire de routage. Cette requête a pris un peu plus de temps car l'agent a dû modifier l'espace de travail, ajouter des tests et exécuter la suite de tests.

L'agent a créé src/routing_rules.py, ajouté un nouveau fichier de tests tests/test_routing_rules.py, et vérifié les changements avec pytest. Les 6 tests ont réussi, confirmant que le nouvel utilitaire fonctionne et que la logique de routage existante reste intacte.

Globalement, cette app Gradio vous offre un frontend simple pour travailler avec un agent OpenAI adossé à Modal. L'utilisateur envoie un message via le navigateur, l'app le transmet au SandboxAgent, l'agent travaille dans le sandbox Modal, puis la réponse finale s'affiche dans l'interface de chat.

Conclusion

Les Agents OpenAI avec Modal Sandboxes offrent une façon propre de construire des applications agentiques capables de manipuler de vrais fichiers, d'exécuter des commandes et de renvoyer des sorties utiles depuis un environnement isolé.

La configuration de Modal a été fluide et la création du sandbox, directe. Une fois le tout connecté, l'agent a pu inspecter le projet, créer un nouveau fichier utilitaire de routage, ajouter des tests et confirmer que les 6 tests réussissaient.

Cela dit, construire l'application interactive et configurer le modèle a demandé plus d'efforts que prévu. Les étapes de création de fichiers et de tests ont aussi été plus longues, car le sandbox Modal expirait parfois. J'ai dû augmenter le délai d'expiration du sandbox de 300 secondes à 600 secondes pour laisser à l'agent le temps de mener à bien tout le flux.

Autre point de friction : la journalisation et la visibilité. Pendant l'attente, il n'était pas toujours clair ce que faisait le SDK Agents en arrière-plan. Même les logs Modal ne montraient pas toujours suffisamment de détail pour savoir si l'agent inspectait des fichiers, éditait du code ou exécutait des tests.

Pour la suite, des logs d'agent plus verbeux seraient utiles, à l'image d'outils comme Claude Code, qui permettent de suivre chaque étape plus clairement.

Dans l'ensemble, c'est un workflow solide pour créer des applications d'agents en sandbox, surtout si votre agent doit travailler avec des fichiers, du code et des sorties générées. Vous pouvez retrouver le projet complet sur GitHub, le cloner en local et l'exécuter vous-même : kingabzpro/OpenAI-Agents-in-Modal.

Si vous souhaitez maîtriser la conception de systèmes d'IA avancés, nous vous recommandons notre cours Building Scalable Agentic Systems.