SDK-ul OpenAI Agents: Cum să rulați agenți în sandbox-urile Modal

Noul flux de lucru pentru sandbox al OpenAI Agents schimbă modul în care este structurată execuția agentului. În loc ca agentul, fișierele, uneltele și runtime-ul să fie într-o singură buclă încâlcită, cadrul separă stratul de orchetrare de încredere de mediul de execuție.

Asta înseamnă că aplicația dumneavoastră poate gestiona logica agentului, apelurile către model și luarea deciziilor, în timp ce munca propriu-zisă se întâmplă într-un workspace izolat, cu acces la fișiere, comenzi și rezultate generate.

Această configurare este utilă mai ales când agentul are nevoie să facă mai mult decât să răspundă doar din contextul promptului. De exemplu, poate inspecta un proiect, scrie sau modifica fișiere, rula cod, testa rezultate și genera artefacte într-un mediu controlat.

În acest ghid, vom învăța cum să combinăm cadrul OpenAI Agents cu Modal Sandboxes pentru a construi o aplicație agentică practică. Agentul va putea rula într-un mediu Modal izolat, executa comenzi în siguranță, lucra cu fișiere și returna rezultate utile înapoi în aplicația principală.

Pentru o introducere fără a folosi sandbox-uri, recomand și tutorialul OpenAI Agents SDK. 

Ce este nou în OpenAI Agents SDK?

Noul OpenAI Agents SDK adaugă o modalitate mai curată de a construi agenți care pot lucra cu fișiere reale, unelte și medii de execuție. În loc să țină totul într-o singură buclă de prompt, SDK-ul separă acum stratul de orchetrare al agentului de sandbox-ul în care are loc munca.

Actualizările-cheie includ:

• Suport nativ pentru sandbox pentru a rula agenți în medii izolate
• Manifest pentru a defini fișierele, folderele și rezultatele la care agentul poate avea acces
• SandboxAgent pentru a conecta agentul la un workspace sandbox
• SandboxRunConfig pentru a controla unde și cum are loc rularea în sandbox
• Unelte în stil Codex pentru editarea fișierelor, comenzi shell și inspectarea proiectului
• Suport MCP pentru a permite agenților să se conecteze la unelte și servicii externe
• Suport pentru Skills și AGENTS.md pentru a oferi agenților instrucțiuni de proiect mai clare
• Suport pentru mai mulți provideri de sandbox, inclusiv Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop și Vercel

Împreună, aceste actualizări facilitează construirea de aplicații agentice care pot inspecta proiecte, rula cod, edita fișiere și returna rezultate generate dintr-un workspace controlat.

1. Configurarea proiectului

În acest proiect demonstrativ, vom construi un mic exemplu de triere a tichetelor de suport folosind OpenAI Agents SDK și Modal Sandboxes. Aplicația va crea un workspace izolat, va adăuga câteva fișiere de proiect în el și apoi va cere unui agent GPT-5.4-mini să inspecteze acele fișiere înainte de a răspunde.

Începeți prin a instala pachetele necesare în mediul dumneavoastră:

pip install "openai-agents[modal]" modal

Înainte de a rula proiectul, aveți nevoie de două conturi:

• Cont OpenAI: Creați un cont pe OpenAI Platform și adăugați credite API folosind un card. Asigurați-vă că contul este verificat pentru a accesa cele mai noi modele suportate.
• Cont Modal: Înscrieți-vă pe Modal. Planul gratuit include credite lunare, suficiente pentru a testa acest ghid.

Apoi, adăugați cheia API OpenAI în mediul local.

• Pe macOS sau Linux: export OPENAI_API_KEY="your_openai_api_key"
• Pe Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

Apoi autentificați-vă local în Modal:

modal setup

Se va deschide o fereastră de browser și vi se va cere să vă conectați la Modal. După autentificare, aprobați cererea de generare a token-ului. Modal va adăuga automat credențialele în mediul local.

După ce totul este configurat, ar trebui să vedeți un mesaj de succes în terminal care confirmă finalizarea autentificării în Modal.

2. Definirea workspace-ului sandbox

În continuare, creați un fișier Python, de exemplu main.py, și adăugați importurile necesare. Aceste importuri aduc SDK-ul OpenAI Agents, clasele de configurare pentru sandbox și clientul de sandbox 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

Acum trebuie să definim workspace-ul sandbox. În acest exemplu, workspace-ul include un mic proiect de triere a tichetelor de suport, cu un README.md, un fișier al aplicației și o listă de verificare pentru lansare.

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 îi spune agentului ce fișiere există în sandbox. Astfel, agentul are o structură reală de proiect pe care o poate inspecta, edita și raționa, în loc să se bazeze doar pe textul din prompt.

În acest caz, agentul va putea revizui logica de rutare a tichetelor de suport, verifica documentația și face modificări în workspace-ul izolat.

3. Crearea agentului pentru sandbox

După ce workspace-ul este definit, creați agentul bazat pe sandbox. Un SandboxAgent este conceput să lucreze cu un workspace real, ceea ce înseamnă că poate inspecta fișierele, înțelege structura proiectului și răspunde pe baza a ceea ce există în 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"),
)

Aici, denumim agentul Modal Sandbox Assistant și folosim modelul gpt-5.4-mini pentru răspunsuri mai rapide. Instrucțiunile îi cer agentului să inspecteze workspace-ul sandbox înainte de a răspunde, lucru important atunci când răspunsul depinde de fișierele reale din proiect.

Opțiunea default_manifest=manifest conectează agentul la workspace-ul creat anterior. Setarea tool_choice="required" încurajează agentul să folosească uneltele disponibile în sandbox, în loc să răspundă doar din memorie sau din contextul promptului.

4. Crearea clientului Modal Sandbox

În continuare, creați clientul pentru sandbox-ul Modal. Aceasta este conexiunea dintre fluxul de lucru OpenAI Agents și sandbox-ul Modal, unde vor avea loc execuțiile efective ale fișierelor și comenzilor.

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

ModalSandboxClient() îi spune agentului să folosească Modal ca provider de sandbox. Asta înseamnă că agentul poate rula într-un mediu Modal izolat, în loc să ruleze direct pe mașina locală.

ModalSandboxClientOptions controlează modul în care este configurat sandbox-ul Modal. Aici, app_name oferă un nume clar aplicației Modal, iar workspace_persistence="tar" indică Modal cum să împacheteze și să persiste fișierele workspace-ului pe durata rularii.

5. Pornirea sesiunii sandbox

Acum că avem clientul și opțiunile pregătite, creați sandbox-ul din manifest și porniți sesiunea. 

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

await sandbox.start()

Apelul client.create() creează un nou sandbox Modal folosind fișierele definite în Manifest. Asta înseamnă că sandbox-ul pornește cu aceeași structură de proiect, inclusiv README.md, src/app.py și docs/release-checks.md.

Apoi, await sandbox.start() pornește sesiunea de sandbox. În acest moment, aveți un workspace izolat live, care rulează pe Modal, gata pentru ca agentul să inspecteze fișiere, să ruleze comenzi și să lucreze cu proiectul.

6. Rularea agentului în sandbox

După ce sandbox-ul este activ, rulați agentul împotriva lui, transmițând sesiunea live de sandbox prin SandboxRunConfig. Aceasta îi spune SDK-ului OpenAI Agents că agentul ar trebui să folosească workspace-ul sandbox Modal în timpul rulării. 

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)

Aici totul se leagă. Modelul gestionează raționamentul, în timp ce sandbox-ul îi oferă acces la fișierele reale din workspace.

În acest exemplu, agentul poate inspecta proiectul de triere a tichetelor, înțelege ce face serviciul, verifica notițele de lansare și returna un răspuns scurt bazat pe fișierele din sandbox-ul Modal.

7. Curățarea sandbox-ului

După ce rularea agentului se termină, ștergeți sandbox-ul pentru a nu lăsa sesiuni neutilizate deschise în Modal.

await client.aclose(sandbox)

Aceasta elimină sesiunea de sandbox după ce munca este finalizată. Este un obicei bun, deoarece sesiunile de sandbox pot consuma resurse de calcul cât timp sunt active.

Într-un proiect real, ar trebui să plasați acest lucru într-un bloc finally. Astfel, curățarea rulează chiar dacă apelul către agent eșuează sau scriptul întâmpină o eroare.

8. Exemplu complet de cod

Iată scriptul complet într-un singur loc. Creează workspace-ul, pornește un sandbox Modal, rulează agentul în interior, afișează rezultatul final și apoi curăță sesiunea de 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())

Acest script urmează structura actuală de sandbox a OpenAI și folosește Modal ca backend de execuție. Logica agentului rămâne în aplicația dumneavoastră Python, în timp ce workspace-ul efectiv rulează într-un sandbox Modal.

Blocul finally este important deoarece închide și șterge sandbox-ul chiar dacă rularea agentului eșuează. Acest lucru ajută la menținerea mediului Modal curat și previne lăsarea sesiunilor neutilizate în execuție.

9. Testarea aplicației local

După ce scriptul este gata, rulați-l local dintr-un terminal în același folder în care este salvat main.py:

python main.py

Dacă totul este configurat corect, scriptul va crea un sandbox Modal, va încărca manifestul în el, va rula agentul OpenAI în workspace, va afișa răspunsul și apoi va curăța sandbox-ul.

Ar trebui să vedeți un output similar cu acesta:

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.

Rularea poate dura câteva secunde. Cât timp rulează, deschideți dashboard-ul Modal, faceți clic pe aplicația openai-agents-modal-demo și verificați jurnalele. Este o modalitate utilă de a confirma că sandbox-ul a fost creat, pornit, folosit de agent și curățat cu succes.

10. Crearea unei aplicații web interactive 

Primul script este static, ceea ce înseamnă că putem trimite o singură cerere, primi un singur răspuns și ne oprim. Pentru a face proiectul mai ușor de folosit, îl putem transforma într-o aplicație web interactivă folosind Gradio. Astfel putem conversa cu agentul din sandbox, pune întrebări suplimentare, crea sau edita fișiere și rula teste dintr-o interfață simplă în browser.

Mai întâi, instalați cea mai recentă versiune de Gradio:

pip install gradio

Apoi creați un fișier nou numit app.py și copiați codul aplicației Gradio (OpenAI-Agents-in-Modal/app.py) în el. Această aplicație folosește aceeași configurare OpenAI Agents și Modal Sandbox, dar o învelește într-o interfață de chat. Codul reutilizează și sesiunea de sandbox atunci când este posibil, astfel încât fiecare mesaj să nu fie nevoit să creeze un sandbox complet nou de la zero.

Rulați aplicația cu:

python app.py

Ar trebui să vedeți un URL local în terminal:

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

Deschideți URL-ul local în browser pentru a folosi aplicația de chat. Puteți cere agentului să inspecteze proiectul, să explice ce face serviciul, să creeze fișiere ajutătoare noi, să editeze fișiere existente sau să ruleze teste în sandbox-ul Modal.

De exemplu, mai întâi i-am cerut să explice ce face serviciul proiectului, iar în câteva secunde a returnat un răspuns detaliat, bazat pe fișierele din sandbox.

Apoi i-am cerut agentului să creeze un nou fișier helper pentru rutare. Această cerere a durat puțin mai mult, deoarece agentul a trebuit să modifice workspace-ul sandbox, să adauge teste și să ruleze suita de teste.

Agentul a creat src/routing_rules.py, a adăugat un nou fișier de test la tests/test_routing_rules.py și a verificat modificările cu pytest. Toate cele 6 teste au trecut, confirmând că noul helper funcționează corect și că logica existentă de rutare a tichetelor a rămas intactă.

La nivel înalt, această aplicație Gradio oferă un frontend simplu pentru a lucra cu un agent OpenAI susținut de Modal. Utilizatorul trimite un mesaj prin browser, aplicația îl transmite către SandboxAgent, agentul lucrează în sandbox-ul Modal, iar răspunsul final este afișat în interfața de chat.

Concluzii

OpenAI Agents cu Modal Sandboxes ne oferă o modalitate curată de a construi aplicații agentice care pot lucra cu fișiere reale, rula comenzi și returna rezultate utile dintr-un mediu izolat. 

Procesul de configurare pentru Modal a fost lin, iar crearea sandbox-ului în sine a fost directă. Odată ce totul a fost conectat, agentul a putut să inspecteze proiectul, să creeze un nou fișier helper pentru rutare, să adauge teste și să confirme că toate cele 6 teste au trecut.

Totuși, construirea aplicației interactive și configurarea modelului au necesitat mai multă muncă decât mă așteptam. Pașii de creare a fișierelor și testare au durat, de asemenea, mai mult deoarece sandbox-ul Modal a expirat uneori. A trebuit să măresc timeout-ul sandbox-ului de la 300 secunde la 600 secunde pentru a oferi agentului suficient timp să finalizeze întregul flux.

Un alt punct problematic a fost logarea și vizibilitatea. În timp ce așteptam finalizarea agentului, nu era întotdeauna clar ce făcea SDK-ul Agents în fundal. Chiar și jurnalele Modal nu arătau mereu suficiente detalii pentru a înțelege dacă agentul inspecta fișiere, edita cod sau rula teste. 

Pe viitor, ar fi util să existe jurnale ale agentului mai detaliate, similare cu ceea ce vedeți când lucrați cu unelte precum Claude Code, unde puteți urmări mai clar fiecare pas.

În ansamblu, acesta este un flux de lucru solid pentru a construi aplicații cu agenți în sandbox, mai ales dacă agentul trebuie să lucreze cu fișiere, cod și rezultate generate. Puteți găsi proiectul complet pe GitHub, să-l clonați local și să-l rulați: kingabzpro/OpenAI-Agents-in-Modal.

Dacă doriți să învățați în profunzime cum să construiți sisteme AI avansate, recomandăm cursul nostru Building Scalable Agentic Systems.