OpenAI Agents SDK: Agents uitvoeren in Modal Sandboxes

De nieuwere sandbox-workflow van OpenAI Agents verandert hoe de uitvoering van agents is opgezet. In plaats van de agent, bestanden, tools en runtime in één rommelige lus te houden, scheidt het framework de vertrouwde orkestratielaag van de uitvoeringsomgeving.

Dit betekent dat je applicatie de agentlogica, modelaanroepen en besluitvorming kan afhandelen, terwijl het daadwerkelijke werk plaatsvindt in een gesandboxte workspace met toegang tot bestanden, commando’s en gegenereerde outputs.

Deze opzet is vooral handig wanneer je agent meer moet doen dan alleen reageren op basis van de promptcontext. Hij kan bijvoorbeeld een project inspecteren, bestanden schrijven of aanpassen, code uitvoeren, outputs testen en artefacten genereren in een gecontroleerde omgeving.

In deze gids leer je hoe je het OpenAI Agents-framework combineert met Modal Sandboxes om een praktische agentic-applicatie te bouwen. De agent kan draaien in een geïsoleerde Modal-omgeving, veilig commando’s uitvoeren, met bestanden werken en nuttige outputs teruggeven aan de hoofdapplicatie.

Voor een introductie zonder sandboxes raad ik ook aan om onze OpenAI Agents SDK Tutorial te lezen. 

Wat is er nieuw in de OpenAI Agents SDK?

De nieuwere OpenAI Agents SDK biedt een schonere manier om agents te bouwen die met echte bestanden, tools en uitvoeringsomgevingen kunnen werken. In plaats van alles in één promptlus te houden, scheidt de SDK nu de agent-orkestratielaag van de sandbox waar het werk gebeurt.

Belangrijke updates zijn onder andere:

• Native sandbox-ondersteuning om agents in geïsoleerde omgevingen te draaien
• Manifest om de bestanden, mappen en outputs te definiëren waartoe de agent toegang heeft
• SandboxAgent om de agent te verbinden met een gesandboxte workspace
• SandboxRunConfig om te bepalen waar en hoe de sandbox-run plaatsvindt
• Codex-achtige tools voor bestandsbewerking, shell-commando’s en projectinspectie
• MCP-ondersteuning om agents te koppelen aan externe tools en services
• Skills en AGENTS.md-ondersteuning om agents duidelijkere projectinstructies te geven
• Ondersteuning voor meerdere sandbox-providers, waaronder Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop en Vercel

Samen maken deze updates het eenvoudiger om agentic apps te bouwen die projecten kunnen inspecteren, code kunnen uitvoeren, bestanden kunnen bewerken en gegenereerde outputs kunnen teruggeven vanuit een gecontroleerde workspace.

1. Het project opzetten

In dit demoproject bouwen we een klein voorbeeld voor het beoordelen van supporttickets met de OpenAI Agents SDK en Modal Sandboxes. De app maakt een gesandboxte workspace, voegt er een paar projectbestanden aan toe en vraagt vervolgens een GPT-5.4-mini-agent om die bestanden te inspecteren voordat hij antwoordt.

Begin met het installeren van de vereiste pakketten in je omgeving:

pip install "openai-agents[modal]" modal

Voordat je het project draait, heb je twee accounts nodig:

• OpenAI-account: Maak een account aan op het OpenAI Platform en voeg API-tegoed toe met een creditcard. Zorg dat je account is geverifieerd om toegang te krijgen tot de nieuwste ondersteunde modellen.
• Modal-account: Meld je aan bij Modal. Het gratis plan bevat maandelijkse credits, voldoende om deze gids te testen.

Voeg daarna je OpenAI API-sleutel toe aan je lokale omgeving.

• Op macOS of Linux: export OPENAI_API_KEY="your_openai_api_key"
• Op Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

Authenticeer Modal vervolgens lokaal:

modal setup

Dit opent een browservenster en vraagt je om in te loggen bij Modal. Keur na het inloggen het verzoek tot token-generatie goed. Modal voegt de inloggegevens automatisch toe aan je lokale omgeving.

Als alles is ingesteld, zou je in je terminal een succesmelding moeten zien die bevestigt dat de Modal-authenticatie is voltooid.

2. De sandbox-workspace definiëren

Maak vervolgens een Python-bestand, bijvoorbeeld main.py, en voeg de vereiste imports toe. Deze imports halen de OpenAI Agents SDK op, configuratieklassen voor de sandbox en de Modal-sandboxclient. 

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

Nu moeten we de sandbox-workspace definiëren. In dit voorbeeld bevat de workspace een klein project voor supportticket-triage met een README.md, een app-bestand en een releasechecklist.

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

Het Manifest vertelt de agent welke bestanden er in de sandbox staan. Zo krijgt de agent een echte projectstructuur om te inspecteren, te bewerken en over te redeneren, in plaats van alleen te vertrouwen op de tekst in de prompt.

In dit geval kan de agent de routeringslogica voor tickets beoordelen, de documentatie controleren en wijzigingen aanbrengen in de gesandboxte workspace.

3. De Sandbox Agent maken

Zodra de workspace is gedefinieerd, maak je de agent met sandbox-backend. Een SandboxAgent is ontworpen om met een echte workspace te werken. Dat betekent dat hij bestanden kan inspecteren, de projectstructuur kan begrijpen en kan antwoorden op basis van wat er in de sandbox aanwezig is.

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

Hier geven we de agent de naam Modal Sandbox Assistant en gebruiken we het model gpt-5.4-mini voor snellere reacties. De instructies vertellen de agent om de sandbox-workspace te inspecteren voordat hij antwoordt, wat belangrijk is wanneer het antwoord afhangt van de daadwerkelijke bestanden in het project.

De koppeling default_manifest=manifest verbindt de agent met de workspace die we eerder hebben gemaakt. De instelling tool_choice="required" stimuleert de agent om de beschikbare sandbox-tools te gebruiken in plaats van alleen uit geheugen of promptcontext te antwoorden.

4. De Modal-sandboxclient maken

Maak vervolgens de Modal-sandboxclient. Dit is de verbinding tussen de OpenAI Agents-workflow en de Modal-sandbox, waar de feitelijke bestands- en commando-uitvoering plaatsvindt.

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

De ModalSandboxClient() vertelt de agent dat Modal de sandbox-provider is. Dit betekent dat de agent draait in een geïsoleerde Modal-omgeving in plaats van direct op je lokale machine.

De ModalSandboxClientOptions bepalen hoe de Modal-sandbox is geconfigureerd. Hier geeft app_name de Modal-app een duidelijke naam, terwijl workspace_persistence="tar" aangeeft hoe Modal de workspacebestanden tijdens de run moet verpakken en bewaren.

5. De sandboxsessie starten

Nu de client en opties klaar zijn, maak je de sandbox op basis van het manifest en start je de sessie. 

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

await sandbox.start()

De aanroep client.create() maakt een nieuwe Modal-sandbox met de bestanden die we in het Manifest hebben gedefinieerd. De sandbox start dus met dezelfde projectstructuur, inclusief README.md, src/app.py en docs/release-checks.md.

Vervolgens start await sandbox.start() de sandboxsessie. Op dit punt heb je een live geïsoleerde workspace die op Modal draait, klaar voor de agent om bestanden te inspecteren, commando’s uit te voeren en met het project te werken.

6. De agent in de sandbox uitvoeren

Zodra de sandbox actief is, voer je de agent erop uit door de live sandboxsessie door te geven via SandboxRunConfig. Dit vertelt de OpenAI Agents SDK dat de agent tijdens de run de Modal-sandboxworkspace moet gebruiken. 

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)

Hier komt alles samen. Het model verzorgt de redenering, terwijl de sandbox toegang geeft tot de echte workspacebestanden.

In dit voorbeeld kan de agent het supportticket-triageproject inspecteren, begrijpen wat de service doet, de releasenotities controleren en een kort antwoord teruggeven op basis van de bestanden in de Modal-sandbox.

7. De sandbox opruimen

Nadat de agent-run is voltooid, verwijder je de sandbox zodat er geen ongebruikte sessies in Modal blijven draaien.

await client.aclose(sandbox)

Dit verwijdert de sandboxsessie nadat het werk klaar is. Dat is een goede gewoonte, omdat sandboxsessies rekenresources gebruiken zolang ze actief zijn.

In een echt project zet je dit het beste in een finally-blok. Zo wordt de cleanup alsnog uitgevoerd, zelfs als de agentaanroep faalt of het script een fout raakt.

8. Volledig codevoorbeeld

Hier staat het complete script bij elkaar. Het maakt de workspace, start een Modal-sandbox, draait de agent erin, print de uiteindelijke output en ruimt daarna de sandboxsessie op. 

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

Dit script volgt de huidige OpenAI-sandboxstructuur en gebruikt Modal als uitvoeringsbackend. De agentlogica blijft in je Python-app, terwijl de daadwerkelijke workspace binnen een Modal-sandbox draait.

Het finally-blok is belangrijk omdat het de sandbox sluit en verwijdert, zelfs als de agent-run faalt. Dit houdt je Modal-omgeving schoon en voorkomt dat ongebruikte sessies blijven draaien.

9. De app lokaal testen

Zodra je script klaar is, voer je het lokaal uit vanuit een terminal in dezelfde map waar main.py is opgeslagen:

python main.py

Als alles correct is geconfigureerd, maakt het script een Modal-sandbox, laadt het manifest erin, draait de OpenAI-agent tegen de workspace, print de respons en ruimt daarna de sandbox op.

Je zou een output moeten zien zoals deze:

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.

De run kan enkele seconden duren. Terwijl hij draait, open je je Modal-dashboard, klik je op de app openai-agents-modal-demo en controleer je de logs. Dit is een handige manier om te bevestigen dat de sandbox is gemaakt, gestart, gebruikt door de agent en succesvol is opgeruimd.

10. Een interactieve webapp maken 

Het eerste script is statisch: je kunt maar één verzoek sturen, één antwoord krijgen en stoppen. Om het project gebruiksvriendelijker te maken, kunnen we er een interactieve webapp van maken met Gradio. Zo kun je chatten met de sandbox-agent, vervolgvragen stellen, bestanden maken of bewerken en tests draaien vanuit een eenvoudige browserinterface.

Installeer eerst de nieuwste versie van Gradio:

pip install gradio

Maak daarna een nieuw bestand met de naam app.py en kopieer de Gradio-appcode (OpenAI-Agents-in-Modal/app.py) erin. Deze app gebruikt dezelfde OpenAI Agents- en Modal Sandbox-setup, maar verpakt die in een chatinterface. De code hergebruikt waar mogelijk ook de sandboxsessie, zodat niet voor elk bericht helemaal vanaf nul een nieuwe sandbox hoeft te worden gemaakt.

Start de app met:

python app.py

Je zou een lokale URL in je terminal moeten zien:

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

Open de lokale URL in je browser om de chatapp te gebruiken. Je kunt de agent vragen het project te inspecteren, uit te leggen wat de service doet, nieuwe helperbestanden te maken, bestaande bestanden te bewerken of tests te draaien in de Modal-sandbox.

Ik vroeg bijvoorbeeld eerst om uit te leggen wat de projectservice doet, en binnen een paar seconden kwam er een gedetailleerde respons op basis van de sandboxbestanden.

Daarna vroeg ik de agent om een nieuw routing-helperbestand te maken. Dit verzoek duurde wat langer omdat de agent de sandbox-workspace moest aanpassen, tests moest toevoegen en de testsuite moest draaien.

De agent maakte src/routing_rules.py, voegde een nieuw testbestand toe op tests/test_routing_rules.py en verifieerde de wijzigingen met pytest. Alle 6 tests slaagden, wat bevestigde dat de nieuwe helper correct werkte en dat de bestaande routeringslogica voor tickets intact was gebleven.

Op hoofdlijnen biedt deze Gradio-app een eenvoudige frontend om te werken met een door Modal ondersteunde OpenAI-agent. De gebruiker stuurt een bericht via de browser, de app geeft het door aan de SandboxAgent, de agent werkt binnen de Modal-sandbox en het uiteindelijke antwoord verschijnt terug in de chatinterface.

Tot slot

OpenAI Agents met Modal Sandboxes biedt een nette manier om agentic apps te bouwen die met echte bestanden kunnen werken, commando’s kunnen uitvoeren en nuttige outputs kunnen teruggeven vanuit een geïsoleerde omgeving. 

Het instelproces voor Modal verliep soepel en het maken van de sandbox was eenvoudig. Toen alles eenmaal verbonden was, kon de agent het project inspecteren, een nieuw routing-helperbestand maken, tests toevoegen en bevestigen dat alle 6 tests slaagden.

Dat gezegd hebbende, kostte het bouwen van de interactieve app en het configureren van het model meer werk dan verwacht. De stappen voor bestandscreatie en testen duurden ook langer omdat de Modal-sandbox soms time-outte. Ik moest de sandbox-time-out verhogen van 300 seconden naar 600 seconden om de agent genoeg tijd te geven om de volledige workflow af te ronden.

Een ander pijnpunt was logging en zichtbaarheid. Tijdens het wachten tot de agent klaar was, was het niet altijd duidelijk wat de Agents SDK op de achtergrond deed. Zelfs de Modal-logs gaven niet altijd genoeg detail om te begrijpen of de agent bestanden inspecteerde, code bewerkte of tests draaide. 

In de toekomst zouden uitgebreidere agentlogs handig zijn, vergelijkbaar met wat je ziet bij tools zoals Claude Code, waarbij je elke stap duidelijker kunt volgen.

Al met al is dit een sterke workflow voor het bouwen van gesandboxte agent-apps, vooral als je agent met bestanden, code en gegenereerde outputs moet werken. Je vindt het volledige project op GitHub; kloon het lokaal en probeer het zelf: kingabzpro/OpenAI-Agents-in-Modal.

Als je de fijne kneepjes wilt leren van het bouwen van geavanceerde AI-systemen, raad ik onze cursus Building Scalable Agentic Systems aan.