OpenAI Agents SDK: come eseguire agenti in Modal Sandboxes

Il nuovo workflow sandbox degli Agents di OpenAI cambia il modo in cui è strutturata l’esecuzione degli agenti. Invece di mantenere agente, file, strumenti e runtime dentro un unico loop disordinato, il framework separa il livello di orchestrazione affidabile dall’ambiente di esecuzione.

Questo significa che la tua applicazione può gestire la logica dell’agente, le chiamate al modello e il processo decisionale, mentre il lavoro effettivo avviene dentro uno spazio di lavoro isolato (sandbox) con accesso a file, comandi e output generati.

Questa configurazione è particolarmente utile quando l’agente deve fare più che rispondere al solo contesto del prompt. Per esempio, può ispezionare un progetto, scrivere o modificare file, eseguire codice, testare gli output e generare artefatti in un ambiente controllato.

In questa guida vedremo come combinare il framework OpenAI Agents con Modal Sandboxes per costruire un’applicazione agentica pratica. L’agente potrà girare dentro un ambiente Modal isolato, eseguire comandi in sicurezza, lavorare con i file e restituire output utili all’applicazione principale.

Per un’introduzione senza usare sandbox, ti consiglio anche di leggere il nostro OpenAI Agents SDK Tutorial. 

Cosa c’è di nuovo nell’OpenAI Agents SDK?

Il nuovo OpenAI Agents SDK introduce un modo più pulito per creare agenti che possono lavorare con file reali, strumenti e ambienti di esecuzione. Invece di tenere tutto dentro un unico prompt loop, l’SDK ora separa il livello di orchestrazione dell’agente dalla sandbox in cui avviene il lavoro.

Gli aggiornamenti principali includono:

• Supporto nativo alle sandbox per eseguire agenti in ambienti isolati
• Manifest per definire i file, le cartelle e gli output a cui l’agente può accedere
• SandboxAgent per collegare l’agente a uno spazio di lavoro sandbox
• SandboxRunConfig per controllare dove e come avviene la run nella sandbox
• Strumenti in stile Codex per l’editing di file, comandi shell e ispezione del progetto
• Supporto MCP per consentire agli agenti di connettersi a strumenti e servizi esterni
• Supporto a Skills e AGENTS.md per fornire istruzioni di progetto più chiare agli agenti
• Supporto a più provider di sandbox, tra cui Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop e Vercel

Insieme, questi aggiornamenti semplificano la creazione di app agentiche che possono ispezionare progetti, eseguire codice, modificare file e restituire output generati da uno spazio di lavoro controllato.

1. Configurazione del progetto

In questo progetto demo, costruiremo un piccolo esempio di triage dei ticket di supporto usando l’OpenAI Agents SDK e Modal Sandboxes. L’app creerà uno spazio di lavoro sandbox, ci aggiungerà alcuni file di progetto e poi chiederà a un agente GPT-5.4-mini di ispezionare quei file prima di rispondere.

Inizia installando i pacchetti richiesti nel tuo ambiente:

pip install "openai-agents[modal]" modal

Prima di eseguire il progetto, ti servono due account:

• Account OpenAI: Crea un account sulla OpenAI Platform e aggiungi crediti API usando una carta di credito. Assicurati che il tuo account sia verificato per accedere ai modelli più recenti supportati.
• Account Modal: Registrati su Modal. Il piano gratuito include crediti mensili, sufficienti per testare questa guida.

Poi aggiungi la tua chiave API OpenAI all’ambiente locale.

• Su macOS o Linux: export OPENAI_API_KEY="your_openai_api_key"
• Su Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

Quindi autentica Modal in locale:

modal setup

Questo aprirà una finestra del browser e ti chiederà di accedere a Modal. Dopo l’accesso, approva la richiesta di generazione del token. Modal aggiungerà automaticamente le credenziali al tuo ambiente locale.

Una volta completata la configurazione, dovresti vedere nel terminale un messaggio di successo che conferma il completamento dell’autenticazione a Modal.

2. Definire lo spazio di lavoro della sandbox

Ora crea un file Python, ad esempio main.py, e aggiungi gli import necessari. Questi import includono l’OpenAI Agents SDK, le classi di configurazione della sandbox e il client della 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

Ora dobbiamo definire lo spazio di lavoro della sandbox. In questo esempio, lo spazio di lavoro include un piccolo progetto di triage dei ticket di supporto con un README.md, un file dell’app e una checklist di rilascio.

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

Il Manifest indica all’agente quali file esistono dentro la sandbox. Questo fornisce all’agente una vera struttura di progetto da ispezionare, modificare e su cui ragionare, invece di affidarsi solo al testo nel prompt.

In questo caso, l’agente potrà rivedere la logica di instradamento dei ticket di supporto, controllare la documentazione e apportare modifiche dentro lo spazio di lavoro in sandbox.

3. Creare il Sandbox Agent

Una volta definito lo spazio di lavoro, crea l’agente basato su sandbox. Un SandboxAgent è progettato per lavorare con uno spazio di lavoro reale, il che significa che può ispezionare i file, comprendere la struttura del progetto e rispondere in base a ciò che esiste dentro la 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"),
)

Qui stiamo chiamando l’agente Modal Sandbox Assistant e usando il modello gpt-5.4-mini per risposte più rapide. Le istruzioni dicono all’agente di ispezionare lo spazio di lavoro in sandbox prima di rispondere, cosa importante quando la risposta dipende dai file reali del progetto.

Il parametro default_manifest=manifest collega l’agente allo spazio di lavoro creato in precedenza. L’impostazione tool_choice="required" incoraggia l’agente a usare gli strumenti della sandbox disponibili invece di rispondere solo dalla memoria o dal contesto del prompt.

4. Creare il client della Modal Sandbox

Poi crea il client della sandbox Modal. Questa è la connessione tra il workflow degli OpenAI Agents e la sandbox Modal, dove avverranno l’accesso ai file e l’esecuzione dei comandi.

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

Il ModalSandboxClient() indica all’agente di usare Modal come provider della sandbox. Questo significa che l’agente può girare dentro un ambiente Modal isolato invece di girare direttamente sulla tua macchina locale.

Il ModalSandboxClientOptions controlla come è configurata la sandbox Modal. Qui, app_name assegna un nome chiaro all’app Modal, mentre workspace_persistence="tar" indica a Modal come impacchettare e mantenere i file dello spazio di lavoro durante l’esecuzione.

5. Avviare la sessione della sandbox

Ora che client e opzioni sono pronti, crea la sandbox a partire dal manifest e avvia la sessione. 

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

await sandbox.start()

La chiamata client.create() crea una nuova sandbox Modal usando i file definiti nel Manifest. Questo significa che la sandbox parte con la stessa struttura di progetto, inclusi README.md, src/app.py e docs/release-checks.md.

Poi, await sandbox.start() avvia la sessione della sandbox. A questo punto hai uno spazio di lavoro isolato live che gira su Modal, pronto perché l’agente ispezioni i file, esegua comandi e lavori sul progetto.

6. Eseguire l’agente nella sandbox

Una volta attiva la sandbox, esegui l’agente su di essa passando la sessione live della sandbox tramite SandboxRunConfig. Questo dice all’OpenAI Agents SDK che l’agente deve usare lo spazio di lavoro della sandbox di Modal durante la 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)

Qui è dove tutto si unisce. Il modello gestisce il ragionamento, mentre la sandbox gli dà accesso ai file reali dello spazio di lavoro.

In questo esempio, l’agente può ispezionare il progetto di triage dei ticket di supporto, capire cosa fa il servizio, controllare le note di rilascio e restituire una risposta breve basata sui file dentro la sandbox di Modal.

7. Pulire la sandbox

Dopo che l’esecuzione dell’agente è terminata, elimina la sandbox per non lasciare sessioni inutilizzate in esecuzione su Modal.

await client.aclose(sandbox)

Questo rimuove la sessione della sandbox dopo che il lavoro è completo. È una buona abitudine, perché le sessioni della sandbox possono usare risorse di calcolo mentre sono attive.

In un progetto reale, dovresti inserire questo dentro un blocco finally. In questo modo, la pulizia viene eseguita anche se la chiamata all’agente fallisce o lo script incontra un errore.

8. Esempio di codice completo

Ecco lo script completo in un unico posto. Crea lo spazio di lavoro, avvia una sandbox Modal, esegue l’agente al suo interno, stampa l’output finale e poi pulisce la sessione della 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())

Questo script segue l’attuale struttura sandbox di OpenAI e usa Modal come backend di esecuzione. La logica dell’agente rimane nella tua app Python, mentre lo spazio di lavoro effettivo gira dentro una sandbox di Modal.

Il blocco finally è importante perché chiude ed elimina la sandbox anche se l’esecuzione dell’agente fallisce. Questo aiuta a mantenere pulito l’ambiente Modal ed evita di lasciare sessioni inutilizzate in esecuzione.

9. Testare l’app in locale

Quando lo script è pronto, eseguilo in locale da un terminale nella stessa cartella in cui è salvato main.py:

python main.py

Se tutto è configurato correttamente, lo script creerà una sandbox Modal, caricherà il manifest al suo interno, eseguirà l’agente OpenAI sullo spazio di lavoro, stamperà la risposta e poi pulirà la sandbox.

Dovresti vedere un output simile a questo:

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’esecuzione può richiedere alcuni secondi. Mentre è in corso, apri la dashboard di Modal, clicca sull’app openai-agents-modal-demo e controlla i log. È un modo utile per confermare che la sandbox è stata creata, avviata, usata dall’agente e pulita con successo.

10. Creare un’app web interattiva 

Il primo script è statico, cioè possiamo inviare una richiesta, ottenere una risposta e fermarci. Per rendere il progetto più comodo da usare, possiamo trasformarlo in un’app web interattiva usando Gradio. Questo ci permette di chattare con l’agente in sandbox, fare domande di follow-up, creare o modificare file ed eseguire test da una semplice interfaccia nel browser.

Per prima cosa, installa l’ultima versione di Gradio:

pip install gradio

Poi crea un nuovo file chiamato app.py e copia al suo interno il codice dell’app di Gradio (OpenAI-Agents-in-Modal/app.py). Questa app usa lo stesso setup di OpenAI Agents e Modal Sandbox, ma lo incapsula in un’interfaccia di chat. Il codice inoltre riutilizza la sessione della sandbox quando possibile, così ogni messaggio non deve creare ogni volta una nuova sandbox da zero.

Esegui l’app con:

python app.py

Dovresti vedere un URL locale nel terminale:

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

Apri l’URL locale nel browser per usare l’app di chat. Puoi chiedere all’agente di ispezionare il progetto, spiegare cosa fa il servizio, creare nuovi file helper, modificare file esistenti o eseguire test dentro la sandbox di Modal.

Per esempio, prima gli ho chiesto di spiegare cosa fa il servizio del progetto e, in pochi secondi, ha restituito una risposta dettagliata basata sui file della sandbox.

Poi ho chiesto all’agente di creare un nuovo file helper per l’instradamento. Questa richiesta ha richiesto un po’ più tempo perché l’agente ha dovuto modificare lo spazio di lavoro della sandbox, aggiungere test ed eseguire la suite di test.

L’agente ha creato src/routing_rules.py, ha aggiunto un nuovo file di test in tests/test_routing_rules.py e ha verificato le modifiche con pytest. Tutti e 6 i test sono passati, confermando che il nuovo helper funzionava correttamente e che la logica esistente di instradamento dei ticket era ancora integra.

A grandi linee, questa app Gradio ti fornisce un frontend semplice per lavorare con un agente OpenAI supportato da Modal. L’utente invia un messaggio tramite il browser, l’app lo passa al SandboxAgent, l’agente lavora dentro la sandbox di Modal e la risposta finale viene mostrata nell’interfaccia di chat.

Considerazioni finali

Gli OpenAI Agents con Modal Sandboxes offrono un modo pulito per costruire app agentiche che possono lavorare con file reali, eseguire comandi e restituire output utili da un ambiente isolato. 

Il processo di setup per Modal è stato fluido e creare la sandbox è stato semplice. Una volta collegato tutto, l’agente è stato in grado di ispezionare il progetto, creare un nuovo file helper per l’instradamento, aggiungere test e confermare che tutti e 6 i test sono passati.

Detto questo, costruire l’app interattiva e configurare il modello ha richiesto più lavoro del previsto. Anche i passaggi di creazione file e testing hanno impiegato più tempo perché a volte la sandbox di Modal andava in timeout. Ho dovuto aumentare il timeout della sandbox da 300 secondi a 600 secondi per dare all’agente abbastanza tempo per completare l’intero workflow.

Un altro punto dolente è stato logging e visibilità. Mentre aspettavo che l’agente finisse, non era sempre chiaro cosa stesse facendo l’Agents SDK in background. Anche i log di Modal non mostravano sempre dettagli sufficienti per capire se l’agente stesse ispezionando file, modificando codice o eseguendo test. 

In futuro, sarebbero utili log dell’agente più verbosi, simili a quelli che vedi quando lavori con strumenti come Claude Code, dove puoi seguire ogni passaggio in modo più chiaro.

Nel complesso, questo è un workflow solido per costruire app agentiche in sandbox, soprattutto se il tuo agente deve lavorare con file, codice e output generati. Puoi trovare il progetto completo su GitHub, clonarlo in locale ed eseguirlo tu stesso: kingabzpro/OpenAI-Agents-in-Modal.

Se vuoi imparare a fondo come costruire sistemi di intelligenza artificiale avanzati, ti consiglio il nostro corso Building Scalable Agentic Systems.