OpenAI Agents SDK: So führst du Agents in Modal-Sandboxes aus

Der neuere Sandbox-Workflow von OpenAI Agents verändert die Struktur der Agent-Ausführung. Statt Agent, Dateien, Tools und Runtime in einer einzigen, unübersichtlichen Schleife zu halten, trennt das Framework die vertrauenswürdige Orchestrierungsschicht von der Ausführungsumgebung.

Deine Anwendung übernimmt damit Logik, Modellaufrufe und Entscheidungen, während die eigentliche Arbeit in einem isolierten Sandbox-Workspace mit Zugriff auf Dateien, Befehle und generierte Outputs passiert.

Dieses Setup ist besonders nützlich, wenn dein Agent mehr tun soll, als nur aus dem Prompt-Kontext zu antworten. Er kann zum Beispiel ein Projekt inspizieren, Dateien schreiben oder ändern, Code ausführen, Ausgaben testen und Artefakte in einer kontrollierten Umgebung erzeugen.

In diesem Guide kombinieren wir das OpenAI Agents Framework mit Modal Sandboxes und bauen eine praxisnahe Agent-Anwendung. Der Agent läuft in einer isolierten Modal-Umgebung, führt Befehle sicher aus, arbeitet mit Dateien und gibt nützliche Ergebnisse an die Hauptanwendung zurück.

Für eine Einführung ohne Sandboxes empfehle ich außerdem unser OpenAI Agents SDK Tutorial. 

Was ist neu im OpenAI Agents SDK?

Das neue OpenAI Agents SDK bietet einen saubereren Weg, Agents zu bauen, die mit echten Dateien, Tools und Ausführungsumgebungen arbeiten. Statt alles in einer Prompt-Schleife zu bündeln, trennt das SDK jetzt die Orchestrierungsschicht des Agents von der Sandbox, in der die Arbeit erfolgt.

Wichtige Neuerungen:

• Native Sandbox-Unterstützung für das Ausführen von Agents in isolierten Umgebungen
• Manifest zum Definieren der Dateien, Ordner und Outputs, auf die der Agent zugreifen darf
• SandboxAgent zur Verbindung des Agents mit einem Sandbox-Workspace
• SandboxRunConfig zur Steuerung, wo und wie die Sandbox läuft
• Codex-ähnliche Tools für Dateibearbeitung, Shell-Befehle und Projektinspektion
• MCP-Support, damit Agents externe Tools und Services anbinden können
• Skills und AGENTS.md für klarere Projektanweisungen an den Agent
• Unterstützung mehrerer Sandbox-Provider, darunter Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop und Vercel

Zusammen erleichtern diese Updates den Bau agentischer Apps, die Projekte inspizieren, Code ausführen, Dateien bearbeiten und Outputs aus einem kontrollierten Workspace zurückgeben.

1. Projekt einrichten

In diesem Demo-Projekt bauen wir ein kleines Beispiel zur Triage von Support-Tickets mit dem OpenAI Agents SDK und Modal Sandboxes. Die App erstellt einen Sandbox-Workspace, fügt ein paar Projektdateien hinzu und lässt anschließend einen GPT-5.4-mini-Agent die Dateien inspizieren, bevor er antwortet.

Starte mit der Installation der benötigten Pakete in deiner Umgebung:

pip install "openai-agents[modal]" modal

Bevor du das Projekt ausführst, benötigst du zwei Accounts:

• OpenAI-Account: Lege einen Account auf der OpenAI Platform an und lade per Kreditkarte API-Guthaben auf. Stelle sicher, dass dein Account verifiziert ist, um auf die neuesten unterstützten Modelle zuzugreifen.
• Modal-Account: Registriere dich bei Modal. Der kostenlose Plan enthält monatliche Credits und reicht für die Tests in diesem Guide.

Füge anschließend deinen OpenAI API-Schlüssel zu deiner lokalen Umgebung hinzu.

• Unter macOS oder Linux: export OPENAI_API_KEY="your_openai_api_key"
• Unter Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

Authentifiziere Modal anschließend lokal:

modal setup

Dadurch öffnet sich ein Browserfenster und du wirst aufgefordert, dich bei Modal anzumelden. Nach der Anmeldung genehmige die Token-Erstellung. Modal fügt die Anmeldedaten automatisch deiner lokalen Umgebung hinzu.

Sobald alles eingerichtet ist, solltest du im Terminal eine Erfolgsmeldung sehen, dass die Modal-Authentifizierung abgeschlossen ist.

2. Den Sandbox-Workspace definieren

Lege als Nächstes eine Python-Datei wie main.py an und füge die benötigten Imports hinzu. Diese bringen das OpenAI Agents SDK, Klassen für die Sandbox-Konfiguration und den Modal-Sandbox-Client ins Projekt. 

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

Nun definieren wir den Sandbox-Workspace. In diesem Beispiel umfasst der Workspace ein kleines Support-Triage-Projekt mit einer README.md, einer App-Datei und einer Release-Checkliste.

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

Das Manifest teilt dem Agent mit, welche Dateien in der Sandbox existieren. So erhält er eine echte Projektstruktur zum Inspizieren, Bearbeiten und Begründen – statt sich nur auf den Prompt-Text zu stützen.

In diesem Fall kann der Agent die Ticket-Routing-Logik prüfen, die Doku checken und Änderungen direkt im Sandbox-Workspace vornehmen.

3. Den Sandbox-Agent erstellen

Sobald der Workspace steht, erstellen wir den Sandbox-gestützten Agent. Ein SandboxAgent ist für die Arbeit mit einem realen Workspace ausgelegt. Er kann also Dateien inspizieren, die Projektstruktur verstehen und auf Basis des Inhalts in der Sandbox antworten.

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 nennen wir den Agent Modal Sandbox Assistant und nutzen das Modell gpt-5.4-mini für schnellere Antworten. Die Instructions sagen dem Agent, den Sandbox-Workspace vor der Antwort zu inspizieren – wichtig, wenn die Antwort von den tatsächlichen Projektdateien abhängt.

Mit default_manifest=manifest verbinden wir den Agent mit dem zuvor erstellten Workspace. Die Einstellung tool_choice="required" sorgt dafür, dass der Agent die verfügbaren Sandbox-Tools nutzt, statt nur aus Gedächtnis oder Prompt-Kontext zu antworten.

4. Den Modal-Sandbox-Client erstellen

Als Nächstes erstellen wir den Modal-Sandbox-Client. Er verbindet den OpenAI-Agents-Workflow mit der Modal-Sandbox, in der Datei- und Befehlsausführung tatsächlich stattfinden.

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

Der Aufruf ModalSandboxClient() setzt Modal als Sandbox-Provider. Der Agent läuft damit in einer isolierten Modal-Umgebung statt direkt auf deiner lokalen Maschine.

Die ModalSandboxClientOptions steuern die Konfiguration der Modal-Sandbox. Hier vergibt app_name einen klaren App-Namen, während workspace_persistence="tar" festlegt, wie Modal die Workspace-Dateien während des Runs paketiert und persistiert.

5. Die Sandbox-Session starten

Sobald Client und Optionen bereit sind, erstellst du die Sandbox aus dem manifest und startest die Session. 

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

await sandbox.start()

Der Aufruf client.create() erzeugt eine neue Modal-Sandbox anhand der im Manifest definierten Dateien. Die Sandbox startet also mit derselben Projektstruktur inklusive README.md, src/app.py und docs/release-checks.md.

Anschließend startet await sandbox.start() die Sandbox-Session. Jetzt läuft ein isolierter Workspace auf Modal, bereit für Dateiinspektionen, Befehle und Projektarbeit durch den Agent.

6. Den Agent in der Sandbox ausführen

Sobald die Sandbox aktiv ist, führst du den Agent dagegen aus, indem du die laufende Sandbox-Session via SandboxRunConfig übergibst. So weiß das OpenAI Agents SDK, dass der Agent während des Runs den Modal-Workspace verwenden soll. 

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 kommt alles zusammen. Das Modell übernimmt das Reasoning, während die Sandbox Zugriff auf die echten Workspace-Dateien bereitstellt.

In diesem Beispiel kann der Agent das Support-Triage-Projekt inspizieren, verstehen, was der Service macht, die Release-Notizen prüfen und eine kurze Antwort auf Basis der Dateien in der Modal-Sandbox zurückgeben.

7. Die Sandbox aufräumen

Wenn der Agent-Run abgeschlossen ist, lösche die Sandbox, damit keine ungenutzten Sessions in Modal weiterlaufen.

await client.aclose(sandbox)

Damit entfernst du die Sandbox-Session nach erledigter Arbeit. Das ist sinnvoll, weil aktive Sessions Rechenressourcen belegen.

In einem realen Projekt solltest du das in einen finally-Block packen. So wird das Cleanup auch ausgeführt, wenn der Agent-Aufruf fehlschlägt oder das Skript auf einen Fehler läuft.

8. Vollständiges Codebeispiel

Hier ist das komplette Skript an einem Ort. Es erstellt den Workspace, startet eine Modal-Sandbox, führt den Agent darin aus, druckt den finalen Output und räumt die Sandbox-Session anschließend auf. 

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

Dieses Skript folgt der aktuellen OpenAI-Sandbox-Struktur und nutzt Modal als Ausführungs-Backend. Die Agent-Logik bleibt in deiner Python-App, während der eigentliche Workspace in einer Modal-Sandbox läuft.

Der finally-Block ist wichtig, weil er die Sandbox auch dann schließt und löscht, wenn der Agent-Run fehlschlägt. So bleibt deine Modal-Umgebung sauber und es bleiben keine ungenutzten Sessions aktiv.

9. Die App lokal testen

Sobald dein Skript bereit ist, führst du es lokal im Terminal im gleichen Ordner aus, in dem main.py gespeichert ist:

python main.py

Wenn alles korrekt konfiguriert ist, erstellt das Skript eine Modal-Sandbox, lädt das Manifest, führt den OpenAI-Agent gegen den Workspace aus, druckt die Antwort und räumt die Sandbox anschließend auf.

Du solltest eine ähnliche Ausgabe sehen:

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.

Der Run kann ein paar Sekunden dauern. Währenddessen kannst du im Modal-Dashboard die App openai-agents-modal-demo öffnen und die Logs prüfen. So siehst du, ob die Sandbox erstellt, gestartet, vom Agent genutzt und erfolgreich bereinigt wurde.

10. Eine interaktive Web-App erstellen 

Das erste Skript ist statisch: eine Anfrage rein, eine Antwort raus, fertig. Für mehr Bedienkomfort können wir daraus mit Gradio eine interaktive Web-App machen. So chattest du mit dem Sandbox-Agent, stellst Rückfragen, erstellst oder bearbeitest Dateien und führst Tests über ein simples Browser-Interface aus.

Installiere zuerst die aktuelle Version von Gradio:

pip install gradio

Erstelle dann eine neue Datei namens app.py und kopiere den Gradio-App-Code (OpenAI-Agents-in-Modal/app.py) hinein. Die App nutzt dasselbe Setup mit OpenAI Agents und Modal-Sandbox, verpackt es aber in eine Chat-Oberfläche. Zudem wird die Sandbox-Session, wenn möglich, wiederverwendet, damit nicht für jede Nachricht eine komplett neue Sandbox entsteht.

Starte die App mit:

python app.py

Im Terminal erscheint eine lokale URL:

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

Öffne die lokale URL im Browser, um die Chat-App zu nutzen. Bitte den Agent, das Projekt zu inspizieren, den Service zu erklären, neue Helper-Dateien zu erstellen, bestehende Dateien zu bearbeiten oder Tests in der Modal-Sandbox auszuführen.

Ich habe ihn zunächst gebeten zu erklären, was der Service macht. Nach wenigen Sekunden kam eine detaillierte Antwort basierend auf den Sandbox-Dateien.

Dann habe ich den Agent gebeten, eine neue Routing-Helper-Datei zu erstellen. Diese Anfrage dauerte etwas länger, weil der Agent den Sandbox-Workspace ändern, Tests hinzufügen und die Test-Suite ausführen musste.

Der Agent hat src/routing_rules.py erstellt, eine neue Testdatei unter tests/test_routing_rules.py hinzugefügt und die Änderungen mit pytest verifiziert. Alle 6 Tests sind durchgelaufen – der neue Helper funktioniert und die bestehende Ticket-Routing-Logik bleibt intakt.

Auf hoher Ebene bietet dir diese Gradio-App ein simples Frontend für die Arbeit mit einem Modal-gestützten OpenAI-Agent. Die Nutzeranfrage geht über den Browser ein, die App leitet sie an den SandboxAgent weiter, der Agent arbeitet in der Modal-Sandbox und die finale Antwort erscheint wieder in der Chat-Oberfläche.

Fazit

OpenAI Agents mit Modal-Sandboxes bieten einen klaren Weg, agentische Apps zu bauen, die mit echten Dateien arbeiten, Befehle ausführen und nützliche Ergebnisse aus einer isolierten Umgebung zurückgeben. 

Die Einrichtung von Modal lief reibungslos und das Erstellen der Sandbox war unkompliziert. Sobald alles verbunden war, konnte der Agent das Projekt inspizieren, einen neuen Routing-Helper erstellen, Tests hinzufügen und bestätigen, dass alle 6 Tests bestanden.

Allerdings haben der Bau der interaktiven App und die Modellkonfiguration mehr Zeit gekostet als erwartet. Datei-Erstellung und Tests dauerten ebenfalls länger, da die Modal-Sandbox gelegentlich in ein Timeout lief. Ich musste das Sandbox-Timeout von 300 Sekunden auf 600 erhöhen, damit der Agent den kompletten Workflow schafft.

Ein weiterer Pain Point war Logging und Transparenz. Während der Agent lief, war nicht immer klar, was das Agents SDK im Hintergrund tat. Selbst die Modal-Logs zeigten nicht immer genug Details, um zu verstehen, ob der Agent Dateien inspiziert, Code editiert oder Tests ausführt. 

Künftig wären ausführlichere Agent-Logs hilfreich, ähnlich wie bei Tools wie Claude Code, bei denen sich jeder Schritt besser nachverfolgen lässt.

Insgesamt ist dies ein starkes Vorgehen für den Bau von Sandbox-Agent-Apps, besonders wenn dein Agent mit Dateien, Code und generierten Outputs arbeiten muss. Das vollständige Projekt findest du auf GitHub. Klone es lokal und probiere es selbst aus: kingabzpro/OpenAI-Agents-in-Modal.

Wenn du die Feinheiten beim Bau fortgeschrittener KI-Systeme lernen willst, empfehle ich unseren Kurs Building Scalable Agentic Systems.