OpenAI Agents SDK: Så kör du agenter i Modal Sandboxes

OpenAI:s nyare arbetsflöde för Agents-sandlådor ändrar hur agentkörning är strukturerad. I stället för att behålla agenten, filer, verktyg och runtime i en enda rörig loop, separerar ramverket det betrodda orkestreringslagret från körningsmiljön.

Detta innebär att din applikation kan hantera agentlogik, modellanrop och beslutsfattande, medan det faktiska arbetet sker i en isolerad sandlådemiljö med åtkomst till filer, kommandon och genererade utdata.

Den här uppsättningen är särskilt användbar när din agent behöver göra mer än att bara svara utifrån promptkontext. Till exempel kan den inspektera ett projekt, skriva eller ändra filer, köra kod, testa utdata och skapa artefakter i en kontrollerad miljö.

I den här guiden lär vi oss hur du kombinerar OpenAI Agents-ramverket med Modal Sandboxes för att bygga en praktisk agentisk applikation. Agenten kommer att kunna köras i en isolerad Modal-miljö, köra kommandon säkert, arbeta med filer och skicka tillbaka användbara utdata till huvudapplikationen.

För en introduktion utan att använda sandlådor rekommenderar jag också att du läser vår OpenAI Agents SDK-handledning. 

Vad är nytt i OpenAI Agents SDK?

Den nyare OpenAI Agents SDK ger ett renare sätt att bygga agenter som kan arbeta med riktiga filer, verktyg och körningsmiljöer. Istället för att behålla allt i en enda prompt-loop separerar SDK:n nu agentens orkestreringslager från sandlådan där arbetet sker.

Viktiga uppdateringar inkluderar:

• Inbyggt stöd för sandlådor för att köra agenter i isolerade miljöer
• Manifest för att definiera vilka filer, mappar och utdata som agenten kan komma åt
• SandboxAgent för att koppla agenten till en sandlådad arbetsyta
• SandboxRunConfig för att styra var och hur sandlådekörningen sker
• Codex-liknande verktyg för filredigering, shell-kommandon och projektinspektion
• MCP-stöd för att möjliggöra att agenter kopplas till externa verktyg och tjänster
• Skills och stöd för AGENTS.md för att ge agenter tydligare projektinstruktioner
• Stöd för flera sandlådeleverantörer, inklusive Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop och Vercel

Tillsammans gör dessa uppdateringar det enklare att bygga agentiska appar som kan inspektera projekt, köra kod, redigera filer och returnera genererade utdata från en kontrollerad arbetsyta.

1. Konfigurera projektet

I det här demoprojektet bygger vi ett litet exempel för triagering av supportärenden med OpenAI Agents SDK och Modal Sandboxes. Appen skapar en sandlådad arbetsyta, lägger till några projektfiler och ber sedan en GPT-5.4-mini-agent att inspektera dessa filer innan den svarar.

Börja med att installera nödvändiga paket i din miljö:

pip install "openai-agents[modal]" modal

Innan du kör projektet behöver du två konton:

• OpenAI-konto: Skapa ett konto på OpenAI Platform och lägg till API-krediter med ett kreditkort. Se till att ditt konto är verifierat för att få åtkomst till de senaste stödda modellerna.
• Modal-konto: Registrera dig på Modal. Gratisplanen inkluderar månatliga krediter, vilket räcker för att testa den här guiden.

Lägg sedan till din OpenAI API-nyckel i din lokala miljö.

• På macOS eller Linux: export OPENAI_API_KEY="your_openai_api_key"
• På Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

Autentisera sedan Modal lokalt:

modal setup

Detta öppnar ett webbläsarfönster och ber dig logga in på Modal. Efter inloggning godkänner du begäran om tokengenerering. Modal lägger automatiskt till autentiseringsuppgifterna i din lokala miljö.

När allt är konfigurerat ska du se ett lyckat meddelande i din terminal som bekräftar att Modal-autentiseringen är klar.

2. Definiera sandlådearbetsytan

Skapa sedan en Python-fil, till exempel main.py, och lägg till de nödvändiga importerna. Dessa importer tar in OpenAI Agents SDK, konfigurationsklasser för sandlådan och Modal-sandlådeklienten. 

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 behöver vi definiera sandlådearbetsytan. I det här exemplet inkluderar arbetsytan ett litet projekt för triagering av supportärenden med en README.md, en appfil och en checklista inför release.

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

Manifest talar om för agenten vilka filer som finns i sandlådan. Detta ger agenten en verklig projektstruktur att inspektera, redigera och resonera kring, i stället för att bara förlita sig på texten i prompten.

I det här fallet kommer agenten att kunna granska logiken för routning av supportärenden, kontrollera dokumentationen och göra ändringar inne i den sandlådebaserade arbetsytan.

3. Skapa sandlådeagenten

När arbetsytan är definierad skapar du agenten med sandlådestöd. En SandboxAgent är utformad för att arbeta med en verklig arbetsyta, vilket innebär att den kan inspektera filer, förstå projektstrukturen och svara baserat på vad som finns i sandlådan.

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

Här ger vi agenten namnet Modal Sandbox Assistant och använder modellen gpt-5.4-mini för snabbare svar. Instruktionerna säger åt agenten att inspektera sandlådearbetsytan innan den svarar, vilket är viktigt när svaret beror på de faktiska filerna i projektet.

Parametern default_manifest=manifest kopplar agenten till arbetsytan vi skapade tidigare. Inställningen tool_choice="required" uppmuntrar agenten att använda tillgängliga sandlådeverktyg i stället för att bara svara utifrån minne eller promptkontext.

4. Skapa Modal-sandlådeklienten

Skapa sedan Modal-sandlådeklienten. Detta är kopplingen mellan OpenAI Agents-arbetsflödet och Modal-sandlådan, där den faktiska fil- och kommandoexekveringen sker.

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

ModalSandboxClient() talar om för agenten att använda Modal som sandlådeleverantör. Det innebär att agenten kan köras i en isolerad Modal-miljö i stället för direkt på din lokala maskin.

ModalSandboxClientOptions styr hur Modal-sandlådan konfigureras. Här ger app_name Modal-appen ett tydligt namn, medan workspace_persistence="tar" talar om för Modal hur arbetsytans filer ska paketeras och bevaras under körningen.

5. Starta sandlådesessionen

Nu när klienten och alternativen är klara, skapa sandlådan från manifest och starta sessionen. 

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

await sandbox.start()

Anropet client.create() skapar en ny Modal-sandlåda med de filer vi definierade i Manifest. Det betyder att sandlådan startar med samma projektstruktur, inklusive README.md, src/app.py och docs/release-checks.md.

Därefter startar await sandbox.start() sandlådesessionen. Nu har du en aktiv isolerad arbetsyta som körs på Modal, redo för agenten att inspektera filer, köra kommandon och arbeta med projektet.

6. Köra agenten i sandlådan

När sandlådan är aktiv kör du agenten mot den genom att skicka den aktiva sandlådesessionen via SandboxRunConfig. Detta talar om för OpenAI Agents SDK att agenten ska använda Modal-sandlådearbetsytan under körningen. 

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)

Det är här allt kommer samman. Modellen hanterar resonemanget, medan sandlådan ger åtkomst till de verkliga arbetsytefilerna.

I det här exemplet kan agenten inspektera projektet för triagering av supportärenden, förstå vad tjänsten gör, kontrollera releasenoteringarna och returnera ett kort svar baserat på filerna i Modal-sandlådan.

7. Städa upp sandlådan

När agentkörningen är klar, ta bort sandlådan så att du inte lämnar oanvända sessioner igång i Modal.

await client.aclose(sandbox)

Detta tar bort sandlådesessionen när arbetet är klart. Det är en bra vana eftersom sandlådesessioner kan använda beräkningsresurser medan de är aktiva.

I ett riktigt projekt bör du placera detta i ett finally-block. På så sätt körs städningen även om agentanropet misslyckas eller skriptet får ett fel.

8. Fullständigt kodexempel

Här är det kompletta skriptet samlat. Det skapar arbetsytan, startar en Modal-sandlåda, kör agenten i den, skriver ut slutliga utdata och stänger sedan sandlådesessionen. 

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

Detta skript följer den aktuella OpenAI-sandlådestrukturen och använder Modal som körningsbackend. Agentlogiken finns kvar i din Python-app, medan själva arbetsytan körs i en Modal-sandlåda.

finally-blocket är viktigt eftersom det stänger och tar bort sandlådan även om agentkörningen misslyckas. Detta hjälper till att hålla din Modal-miljö ren och undviker att lämna oanvända sessioner igång.

9. Testa appen lokalt

När ditt skript är klart, kör det lokalt från en terminal i samma mapp där main.py är sparad:

python main.py

Om allt är korrekt konfigurerat kommer skriptet att skapa en Modal-sandlåda, ladda manifestet i den, köra OpenAI-agenten mot arbetsytan, skriva ut svaret och sedan städa upp sandlådan.

Du bör se ett utdata som liknar detta:

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.

Körningen kan ta några sekunder att slutföra. Medan den körs, öppna din Modal-instrumentpanel, klicka på appen openai-agents-modal-demo och kontrollera loggarna. Detta är ett bra sätt att bekräfta att sandlådan skapades, startades, användes av agenten och städades upp korrekt.

10. Skapa en interaktiv webbapp 

Det första skriptet är statiskt, vilket betyder att vi bara kan skicka en begäran, få ett svar och stoppa. För att göra projektet enklare att använda kan vi förvandla det till en interaktiv webbapp med Gradio. Detta låter oss chatta med sandlådeagenten, ställa följdfrågor, skapa eller redigera filer och köra tester från ett enkelt webbläsargränssnitt.

Installera först den senaste versionen av Gradio:

pip install gradio

Skapa sedan en ny fil med namnet app.py och kopiera Gradio-appkoden (OpenAI-Agents-in-Modal/app.py) till den. Den här appen använder samma OpenAI Agents- och Modal Sandbox-uppsättning, men kapslar in den i ett chattgränssnitt. Koden återanvänder också sandlådesessionen när det är möjligt, så varje meddelande behöver inte skapa en helt ny sandlåda från grunden.

Kör appen med:

python app.py

Du bör se en lokal URL i din terminal:

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

Öppna den lokala URL:en i din webbläsare för att använda chattappen. Du kan be agenten inspektera projektet, förklara vad tjänsten gör, skapa nya hjälpfiler, redigera befintliga filer eller köra tester i Modal-sandlådan.

Till exempel bad jag först om en förklaring av vad projekttjänsten gör, och inom några sekunder fick jag ett detaljerat svar baserat på sandlådefilerna.

Sedan bad jag agenten att skapa en ny hjälparfil för routning. Denna begäran tog lite längre tid eftersom agenten var tvungen att ändra sandlådearbetsytan, lägga till tester och köra testsviten.

Agenten skapade src/routing_rules.py, lade till en ny testfil på tests/test_routing_rules.py och verifierade ändringarna med pytest. Alla 6 testerna klarade, vilket bekräftade att den nya hjälparen fungerade korrekt och att den befintliga ärenderoutningslogiken fortfarande var intakt.

På en övergripande nivå ger den här Gradio-appen dig en enkel frontend för att arbeta med en Modal-stödd OpenAI-agent. Användaren skickar ett meddelande via webbläsaren, appen skickar det vidare till SandboxAgent, agenten arbetar i Modal-sandlådan och det slutliga svaret visas tillbaka i chattgränssnittet.

Avslutande tankar

OpenAI Agents med Modal Sandboxes ger oss ett rent sätt att bygga agentiska appar som kan arbeta med riktiga filer, köra kommandon och returnera användbara utdata från en isolerad miljö. 

Uppsättningsprocessen för Modal var smidig, och att skapa själva sandlådan var okomplicerat. När allt var ihopkopplat kunde agenten inspektera projektet, skapa en ny hjälparfil för routning, lägga till tester och bekräfta att alla 6 testerna klarade.

Det sagt krävde det mer arbete än väntat att bygga den interaktiva appen och konfigurera modellen. Stegen för filskapande och testning tog också längre tid eftersom Modal-sandlådan ibland timeout:ade. Jag var tvungen att öka sandlåde-timeouten från 300 sekunder till 600 sekunder för att ge agenten tillräckligt med tid att slutföra hela arbetsflödet.

En annan smärtpunkt var loggning och insyn. Medan jag väntade på att agenten skulle bli klar var det inte alltid tydligt vad Agents SDK gjorde i bakgrunden. Inte ens Modal-loggarna visade alltid tillräckligt med detaljer för att förstå om agenten inspekterade filer, redigerade kod eller körde tester. 

I framtiden skulle det vara hjälpsamt att ha mer utförliga agentloggar, liknande det du ser när du arbetar med verktyg som Claude Code, där du kan följa varje steg tydligare.

Överlag är detta ett starkt arbetsflöde för att bygga sandlådade agentappar, särskilt om din agent behöver arbeta med filer, kod och genererade utdata. Du hittar hela projektet på GitHub, klona det lokalt och kör det själv: kingabzpro/OpenAI-Agents-in-Modal.

Om du vill lära dig allt om hur man bygger avancerade AI-system rekommenderar jag vår kurs Building Scalable Agentic Systems.