Sandbox ospitati da OpenAI: crea un analista finanziario AI sicuro

Gli agenti AI hanno superato la semplice generazione di testo. Ora possono scrivere codice, eseguire comandi, lavorare con file, correggere errori e completare attività multi‑step in autonomia.

Ma gli LLM non sono sempre prevedibili. 

Anche con istruzioni chiare, un agente può generare un comando inatteso o modificare qualcosa che non avrebbe dovuto. Eseguire quel codice direttamente sul tuo computer locale o sul server dell’applicazione può quindi introdurre rischi inutili.

In questo tutorial userò un sandbox ospitato da OpenAI per creare un analista finanziario AI sicuro. Caricheremo un dataset finanziario, collegheremo un agente all’ambiente isolato, gli lasceremo eseguire l’analisi e generare gli artefatti, quindi scaricheremo i report, i grafici e i file di dati risultanti.

L’analista finanziario è solo un esempio. L’obiettivo principale è capire come fornire a un agente AI un ambiente controllato in cui possa eseguire codice e lavorare con i file in sicurezza.

Che cos’è il sandbox ospitato da OpenAI?

Un sandbox è un ambiente isolato in cui il codice può essere eseguito senza avere accesso illimitato al sistema che ospita la tua applicazione.

Questo è particolarmente utile per gli agenti AI perché il loro comportamento non è completamente prevedibile. 

Un agente può ricevere l’istruzione di modificare un file ma generare un comando che influisce su un’altra directory, installare una dipendenza inattesa o eseguire qualcosa che non avevi previsto.

Invece di consentire che tali comandi vengano eseguiti direttamente sul tuo laptop o server, puoi mettere l’agente all’interno di un sandbox.

OpenAI fornisce il proprio ambiente sandbox ospitato per questo scopo. 

Offre a un agente un vero workspace Linux con filesystem e shell, mantenendo però quella esecuzione separata dal tuo sistema locale.

All’interno del sandbox, l’agente può:

• Leggere e scrivere file.
• Creare ed eseguire script.
• Eseguire comandi shell.
• Ispezionare l’output dei comandi.
• Correggere errori e rieseguire il codice.
• Generare report, dataset, grafici e altri artefatti.

Puoi anche controllare a cosa il sandbox ha accesso. 

Per esempio, puoi caricare solo i file necessari per un’attività e disabilitare l’accesso di rete quando l’agente non ha bisogno di informazioni esterne.

Modi diversi di usare i sandbox OpenAI

OpenAI ti offre vari modi per eseguire agenti o modelli all’interno di ambienti isolati. La differenza principale è quanto dell’esecuzione e del workflow dell’agente vuoi che sia gestito da OpenAI.

1. Shell Tool

Lo Shell tool è l’opzione più semplice. Consente a un modello di eseguire comandi shell dentro un container ospitato da OpenAI tramite la Responses API.

response = client.responses.create(
    model=MODEL,
    tools=[{
        "type": "shell",
        "environment": {"type": "container_auto"}
    }],
    input="Analyze the files in /mnt/data."
)

È una buona scelta quando ti serve soprattutto esecuzione di codice, elaborazione di file o attività da riga di comando.

2. Agents API

La Agents API è un’opzione più gestita. OpenAI si occupa sia della sessione dell’agente sia dell’ambiente ospitato.

stream = client.beta.agents.sessions.create(
    agent={
        "model": MODEL,
        "instructions": "Analyze the data and create a report."
    },
    environment={"type": "openai_hosted"},
    input="Analyze the files in the workspace.",
    stream=True,
)

È utile quando vuoi che OpenAI gestisca più aspetti del runtime dell’agente e del ciclo di vita del sandbox.

3. SandboxAgent

SandboxAgent fa parte dell’Agents SDK ed è pensato per agenti in cui il workspace del sandbox è una parte centrale dell’applicazione.

from agents.sandbox import SandboxAgent
from agents.sandbox.capabilities import Shell

agent = SandboxAgent(
    name="Financial Analyst",
    model=MODEL,
    capabilities=[Shell()],
)

Funziona bene quando ti servono workspace, file e artefatti persistenti o flessibilità sul fornitore di sandbox da usare.

4. Agents SDK + ShellTool

È l’approccio che usiamo in questa guida.

Creiamo noi stessi il container ospitato da OpenAI e poi colleghiamo l’agente a quello specifico ambiente usando ShellTool.

sandbox_shell = ShellTool(
    environment={
        "type": "container_reference",
        "container_id": container.id,
    }
)

Abbiamo scelto questo approccio perché offre un buon equilibrio tra semplicità e controllo. 

OpenAI gestisce l’infrastruttura del sandbox, mentre noi manteniamo il controllo su container, file, accesso di rete, istruzioni all’agente, strumenti e flusso di esecuzione.

Come usare il sandbox ospitato da OpenAI

Vediamo come usare il sandbox ospitato da OpenAI per creare un agente analista finanziario sicuro. 

1. Configura l’ambiente e il progetto

Useremo un Jupyter Notebook per configurare e testare il workflow. 

Il notebook gestirà attività come installare gli SDK necessari, caricare il dataset, creare il sandbox, avviare l’agente e scaricare gli artefatti finali.

Tuttavia, la distinzione importante è che l’analisi finanziaria in sé non verrà eseguita dentro Jupyter. 

Una volta che l’agente è connesso al sandbox OpenAI, l’esecuzione del suo codice, i comandi shell, la validazione, i calcoli e la generazione di artefatti avverranno all’interno dell’ambiente ospitato.

Pensa a Jupyter come al livello di controllo, mentre il sandbox è l’ambiente di esecuzione.

Inizia installando l’OpenAI Python SDK e l’OpenAI Agents SDK:

%pip install -q -U openai openai-agents

Ti serve anche una chiave API di OpenAI disponibile tramite la variabile d’ambiente OPENAI_API_KEY.

Per questo tutorial useremo il dataset di un’azienda fittizia, archiviato in:

financial_data/northstar_cloud_financial_statements.csv

Poi importa le librerie necessarie e definisci il modello, il CSV di input, la directory di output locale e i file che ci aspettiamo che l’agente generi.

import json
import os
from pathlib import Path

from IPython.display import Markdown, SVG, display


MODEL = os.getenv("OPENAI_MODEL", "gpt-6-luna")

STATEMENT_CSV = Path(
    "financial_data/northstar_cloud_financial_statements.csv"
)

OUTPUT_DIR = Path("financial_analysis_output")
OUTPUT_DIR.mkdir(exist_ok=True)

EXPECTED_ARTIFACTS = [
    "analyze_financials.py",
    "calculated_metrics.csv",
    "unusual_movements.csv",
    "financial_trends.svg",
    "investment_analysis.md",
    "analysis_run.json",
]

assert os.getenv("OPENAI_API_KEY"), \
    "Set OPENAI_API_KEY before continuing."

assert STATEMENT_CSV.exists(), \
    f"Missing input: {STATEMENT_CSV.resolve()}"

print(f"Model: {MODEL}")
print(
    f"Input: {STATEMENT_CSV} "
    f"({STATEMENT_CSV.stat().st_size:,} bytes)"
)

Output:

Model: gpt-6-luna
Input: financial_data\northstar_cloud_financial_statements.csv (1,480 bytes)

Le asserzioni forniscono un rapido sanity check prima di creare qualsiasi risorsa OpenAI. Se manca la chiave API o il dataset non viene trovato, il notebook si interrompe subito invece di fallire più avanti nel workflow.

OUTPUT_DIR è una directory locale di Jupyter dove salveremo i file scaricati dal sandbox. 

EXPECTED_ARTIFACTS, invece, definisce i file che ci aspettiamo che l’agente crei all’interno del sandbox.

2. Carica i dati finanziari

Prima che il sandbox possa lavorare con i nostri dati finanziari, dobbiamo prima caricare il CSV su OpenAI.

Questo passaggio è gestito dal Jupyter Notebook. Legge il file locale e lo invia tramite l’OpenAI Files API.

from openai import OpenAI

client = OpenAI()

with STATEMENT_CSV.open("rb") as handle:
    uploaded_input = client.files.create(
        file=handle,
        purpose="user_data",
    )

print(f"Uploaded raw statements: {uploaded_input.id}")

Output:

Uploaded raw statements: file-C6Pb6RhZrVPR4Fiq9tZ6Hn

Il tuo file ID sarà diverso.

L’ID del file restituito è importante perché lo useremo quando creeremo il sandbox. Invece di copiare il contenuto del CSV in un prompt, possiamo allegare direttamente il file originale all’ambiente di lavoro dell’agente.

A questo punto, i bilanci Northstar sono archiviati presso OpenAI, ma l’agente non ha ancora un ambiente di esecuzione.

Lo creeremo adesso.

3. Crea il sandbox ospitato da OpenAI

Ora possiamo creare l’ambiente ospitato in cui l’agente eseguirà realmente l’analisi finanziaria.

Usa la Containers API per creare un nuovo sandbox e allegare il CSV caricato usando il suo ID file:

container = client.containers.create(
    name="northstar-financial-analysis",
    file_ids=[uploaded_input.id],
    memory_limit="4g",
    network_policy={"type": "disabled"},
)

print(f"OpenAI sandbox: {container.id}")

Output:

OpenAI sandbox: cntr_6ab7a1080b4081938d8d08ab67ac963c084798905ec997e9

Il sandbox è creato con 4 GB di memoria e i bilanci caricati sono disponibili al suo interno fin dall’inizio.

Disabilitiamo anche l’accesso di rete:

network_policy={"type": "disabled"}

La nostra analisi finanziaria non richiede informazioni da internet, quindi non c’è motivo di dare all’agente accesso esterno alla rete. Tutto ciò che gli serve è già contenuto nel CSV.

4. Definisci il compito dell’analista finanziario

Il sandbox offre all’agente un posto sicuro in cui lavorare, ma dobbiamo ancora definire esattamente cosa vogliamo che faccia.

Invece di dare al modello un’istruzione vaga come "analizza questa azienda", forniamo un compito dettagliato che descrive i calcoli, i controlli di validazione, i file da generare e come l’agente deve verificare il proprio lavoro.

ANALYST_INSTRUCTIONS = """
You are a skeptical senior buy-side financial analyst preparing an investment-committee memo.

Every analytical operation must occur in the hosted shell container under /mnt/data. Do not
estimate results mentally or ask the caller to calculate anything.

Find the uploaded Northstar statement CSV. Write analyze_financials.py using only the Python
standard library and execute it. Validate required columns, numeric values, unique ordered years,
and total_assets = total_liabilities + equity for every row. Calculate revenue growth, gross/
operating/net margins, current and quick ratios, total-liabilities-to-equity, average-balance ROA
and ROE, interest coverage, free cash flow, FCF margin, cash conversion, receivables growth, and
inventory growth. Leave a ratio blank when its denominator makes it undefined.

Flag absolute year-over-year movements of at least 15%, operating-margin moves of at least two
percentage points, and receivables growth exceeding revenue growth by at least ten points. Create
calculated_metrics.csv, unusual_movements.csv, financial_trends.svg, investment_analysis.md, and
analysis_run.json in /mnt/data. The SVG must contain four readable chart panels without external
packages.

The report must cover Executive view, KPI table, Profitability, Liquidity and leverage, Cash flow
and earnings quality, Unusual movements, Bull case, Bear case, Diligence questions, Data
limitations, and Conclusion. Tie receivables, deferred revenue, stock compensation, capex, and
interest expense to evidence; separate facts from hypotheses and cite filenames and years.

analysis_run.json must contain input_filename, row_count, year_range, validation_results,
generated_filenames, and execution_directory='/mnt/data'. validation_results must include
accounting_equation_passed_every_row=true. Run the script, inspect every artifact, independently
recompute at least three 2025 metrics in a second command, and fix discrepancies. Do not finish
until all six required files exist and are non-empty.
"""

Qui c’è una scelta progettuale importante.

Non chiediamo al modello di ragionare sull’analisi finanziaria solo nella sua risposta. 

Le istruzioni gli dicono esplicitamente di scrivere codice, eseguirlo, ispezionare i risultati, verificare alcuni calcoli e correggere eventuali discrepanze.

Diciamo anche all’agente che ogni operazione analitica deve avvenire sotto /mnt/data all’interno del sandbox ospitato.

Questo dà all’agente un workflow chiaro:

Trova i dati → validali → scrivi lo script di analisi → eseguilo → genera gli artefatti → ispeziona i risultati → verifica i calcoli → correggi gli errori se necessario.

Così il sandbox diventa un vero ambiente di lavoro, non solo un archivio temporaneo di file.

5. Collega l’agente al sandbox

Ora colleghiamo un agente OpenAI al container che abbiamo creato prima.

Lo facciamo usando ShellTool.

from agents import Agent, ModelSettings, Runner, ShellTool

sandbox_shell = ShellTool(
    environment={
        "type": "container_reference",
        "container_id": container.id,
    }
)

analyst = Agent(
    name="Sandbox Financial Analyst",
    model=MODEL,
    instructions=ANALYST_INSTRUCTIONS,
    tools=[sandbox_shell],
    model_settings=ModelSettings(tool_choice="required"),
)

La parte importante è:

"type": "container_reference",
"container_id": container.id,

Questo indica a ShellTool di collegare l’agente al sandbox che abbiamo già creato, invece di crearne o usarne un altro.

Impostiamo anche:

tool_choice="required"

Questo obbliga l’agente a usare uno strumento durante l’esecuzione, invece di completare il compito solo con una normale risposta testuale.

Per questo tutorial, è esattamente ciò che vogliamo. 

L’agente non dovrebbe limitarsi a spiegare come calcolare le metriche finanziarie. Dovrebbe usare la shell, eseguire codice dentro il sandbox e produrre i file richiesti.

6. Lascia che l’agente esegua l’analisi

Con il dataset caricato, il sandbox in esecuzione e l’agente connesso tramite ShellTool, possiamo avviare l’analisi.

result = await Runner.run(
    analyst,
    "Analyze Northstar entirely inside the sandbox and produce every required artifact.",
    max_turns=30,
)

display(Markdown(result.final_output))

Questo avvia l’agente analista finanziario e gli dà accesso al sandbox che abbiamo creato.

L’output finale dell’agente conferma che l’analisi è stata completata con successo dentro /mnt/data, inclusi la validazione dei dati, i controlli sulle metriche e la creazione di tutti e sei gli artefatti richiesti.

7. Scarica gli artefatti generati

L’analisi è completa, ma i file generati si trovano ancora dentro il sandbox OpenAI.

Ora elenchiamo i file nel container, verifichiamo che tutti gli artefatti attesi siano stati creati e li scarichiamo nella nostra directory locale.

remote_files = {
    Path(item.path).name: item
    for item in client.containers.files.list(container.id)
}

missing = [
    name for name in EXPECTED_ARTIFACTS
    if name not in remote_files
]

assert not missing, f"Sandbox did not create: {missing}"

for name in EXPECTED_ARTIFACTS:
    remote = remote_files[name]
    destination = OUTPUT_DIR / name

    client.containers.files.content.retrieve(
        remote.id,
        container_id=container.id,
    ).write_to_file(destination)

    assert destination.stat().st_size > 0, \
        f"Empty artifact: {destination}"

    print(
        f"Downloaded {name}: "
        f"{destination.stat().st_size:,} bytes"
    )

Output:

Downloaded analyze_financials.py: 22,778 bytes
Downloaded calculated_metrics.csv: 3,740 bytes
Downloaded unusual_movements.csv: 25,405 bytes
Downloaded financial_trends.svg: 13,846 bytes
Downloaded investment_analysis.md: 12,159 bytes
Downloaded analysis_run.json: 1,522 bytes

A questo punto puoi aprire la directory locale financial_analysis_output e ispezionare tutto ciò che l’agente ha creato.

La cartella contiene lo script di analisi, le metriche calcolate, i flag dei movimenti insoliti, il memo di investimento completo, il manifesto di validazione e una visualizzazione SVG delle tendenze finanziarie.

Il file investment_analysis.md contiene l’analisi scritta principale, inclusi executive view, redditività, liquidità, leva finanziaria, flusso di cassa, movimenti insoliti e gli scenari bull e bear.

Puoi anche aprire financial_trends.svg per ispezionare i risultati visivi. 

Offre una vista rapida delle principali tendenze finanziarie, come ricavi, redditività, margini e altre metriche chiave, senza dover leggere prima l’intero report.

Un dettaglio importante è che non scarichiamo semplicemente qualunque file l’agente abbia creato. 

Il notebook confronta prima i contenuti del sandbox con EXPECTED_ARTIFACTS.

Se manca uno dei file richiesti, l’asserzione fallisce. Controlliamo anche che ogni file scaricato non sia vuoto.

Questo ci fornisce un semplice passaggio di verifica prima di accettare l’output dell’agente.

8. Pulisci il sandbox

Una volta che i file sono stati scaricati e verificati, non ci servono più il sandbox temporaneo o il file sorgente caricato.

Elimina entrambe le risorse:

client.containers.delete(container.id)
client.files.delete(uploaded_input.id)

Questo rimuove il container ospitato e il dataset finanziario caricato al termine del workflow.

Pulire le risorse temporanee è un buon passaggio finale, soprattutto quando crei sandbox regolarmente come parte di un workflow per agenti.

Considerazioni finali

Il vantaggio più grande del sandbox ospitato da OpenAI è che l’intero workflow rimane all’interno di un unico ecosistema.

Non devi collegare un fornitore di sandbox separato, effettuare il provisioning di un tuo ambiente cloud o creare e mantenere un’infrastruttura container tua. 

Puoi creare un sandbox, allegare file, controllare l’accesso di rete, lasciare che l’agente lavori al suo interno, recuperare i risultati ed eliminare l’ambiente quando hai finito, tutto tramite la piattaforma OpenAI.

Questo rende il workflow molto più semplice da gestire.

In questo tutorial ho usato l’OpenAI Agents SDK con ShellTool perché mi offre un modo lineare per collegare un agente a un container esistente, mantenendo comunque il controllo su istruzioni, file, strumenti e flusso di esecuzione.

Ci sono altri modi per costruire lo stesso tipo di workflow nell’ecosistema OpenAI, incluse API per agenti più dirette e astrazioni di sandbox di livello superiore. 

Per questo esempio, però, l’Agents SDK mi è sembrato il giusto equilibrio tra semplicità e controllo.

Il punto chiave è che ora puoi dare a un agente AI un vero ambiente di esecuzione senza uscire dall’ecosistema OpenAI:

Crea il sandbox → allega i dati → collega l’agente → esegui il task → recupera gli artefatti → elimina il sandbox.

Per applicazioni di agenti che devono eseguire codice, manipolare file, generare report o svolgere analisi multi‑step, è un pattern davvero utile.