OpenAI-gehoste sandboxes: bouw een veilige AI-financieel analist

AI-agents gaan inmiddels veel verder dan simpele tekstgeneratie. Ze kunnen nu code schrijven, commando’s uitvoeren, met bestanden werken, fouten herstellen en zelfstandig meerstaps taken afronden.

Maar LLM’s zijn niet altijd voorspelbaar. 

Zelfs met duidelijke instructies kan een agent een onverwacht commando genereren of iets wijzigen wat niet de bedoeling was. Dat soort code direct op je lokale machine of applicatieserver draaien kan dus onnodig risico met zich meebrengen.

In deze tutorial gebruik ik een door OpenAI gehoste sandbox om een veilige AI-financieel analist te bouwen. We uploaden een financiële dataset, koppelen een agent aan de geïsoleerde omgeving, laten die daar de analyse uitvoeren en artefacten genereren, en downloaden vervolgens de resulterende rapporten, grafieken en databestanden.

De financieel analist is slechts een voorbeeld. Het hoofddoel is begrijpen hoe je een AI-agent een gecontroleerde omgeving geeft waarin hij veilig code kan draaien en met bestanden kan werken.

Wat is de door OpenAI gehoste sandbox?

Een sandbox is een geïsoleerde omgeving waarin code kan draaien zonder onbeperkte toegang tot het systeem waarop je applicatie draait.

Dit is vooral nuttig voor AI-agents omdat hun gedrag niet volledig voorspelbaar is. 

Een agent kan bijvoorbeeld de opdracht krijgen één bestand te wijzigen, maar een commando genereren dat een andere map beïnvloedt, een onverwachte dependency installeren of iets uitvoeren wat je niet had voorzien.

In plaats van die commando’s direct op je laptop of server toe te staan, kun je de agent in een sandbox plaatsen.

OpenAI biedt hiervoor een eigen gehoste sandbox-omgeving. 

Het geeft een agent een echte Linux-werkruimte met een bestandssysteem en shell, terwijl die uitvoering gescheiden blijft van je lokale systeem.

Binnen de sandbox kan de agent:

• Bestanden lezen en schrijven.
• Scripts maken en uitvoeren.
• Shell-commando’s draaien.
• Commando-uitvoer inspecteren.
• Fouten herstellen en zijn code opnieuw draaien.
• Rapporten, datasets, grafieken en andere artefacten genereren.

Je kunt ook bepalen waartoe de sandbox toegang heeft. 

Je kunt bijvoorbeeld alleen de bestanden uploaden die voor een taak nodig zijn en netwerktoegang uitschakelen als de agent geen externe informatie nodig heeft.

Verschillende manieren om OpenAI-sandboxes te gebruiken

OpenAI biedt een paar verschillende manieren om agents of modellen in geïsoleerde omgevingen te draaien. Het belangrijkste verschil is hoeveel van de uitvoering en agent-workflow je door OpenAI wilt laten beheren.

1. Shell-tool

De Shell-tool is de eenvoudigste optie. Hiermee kan een model shell-commando’s uitvoeren in een door OpenAI gehoste container via de Responses API.

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

Dit is een goede keuze wanneer je vooral code-executie, bestandsverwerking of commandline-taken nodig hebt.

2. Agents API

De Agents API is een meer beheerde optie. OpenAI verzorgt zowel de agentsessie als de gehoste omgeving.

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

Dit is handig wanneer je wilt dat OpenAI meer van de agent-runtime en de sandbox-levenscyclus voor je beheert.

3. SandboxAgent

SandboxAgent maakt deel uit van de Agents SDK en is bedoeld voor agents waarbij de sandbox-werkruimte een kernonderdeel van de applicatie is.

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

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

Dit werkt goed wanneer je persistente werkruimtes, bestanden, artefacten of flexibiliteit over de gekozen sandboxprovider nodig hebt.

4. Agents SDK + ShellTool

Dit is de aanpak die we in deze gids gebruiken.

We maken zelf de door OpenAI gehoste container en koppelen de agent vervolgens aan die specifieke omgeving met ShellTool.

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

We kozen deze aanpak omdat die een goede balans biedt tussen eenvoud en controle. 

OpenAI beheert de sandbox-infrastructuur, terwijl wij nog steeds de container, bestanden, netwerktoegang, agentinstructies, tools en de uitvoeringsstroom bepalen.

Hoe gebruik je de door OpenAI gehoste sandbox

Laten we bekijken hoe je de door OpenAI gehoste sandbox gebruikt om een veilige financieel-analistagent te maken. 

1. Stel de omgeving en het project in

We gebruiken een Jupyter Notebook om de workflow in te richten en te testen. 

Het notebook verzorgt taken zoals het installeren van de vereiste SDK’s, het uploaden van de dataset, het aanmaken van de sandbox, het starten van de agent en het downloaden van de uiteindelijke artefacten.

Belangrijk is echter dat de financiële analyse zelf niet in Jupyter zal draaien. 

Zodra de agent is verbonden met de OpenAI-sandbox, vinden de code-executie, shell-commando’s, validatie, berekeningen en artefactgeneratie plaats binnen de gehoste sandbox-omgeving.

Zie Jupyter als de besturingslaag, terwijl de sandbox de uitvoeringsomgeving is.

Begin met het installeren van de OpenAI Python SDK en de OpenAI Agents SDK:

%pip install -q -U openai openai-agents

Je hebt ook een OpenAI API-sleutel nodig via de OPENAI_API_KEY-omgevingsvariabele.

Voor deze tutorial gebruiken we een dataset van een fictief bedrijf, opgeslagen op:

financial_data/northstar_cloud_financial_statements.csv

Importeer vervolgens de vereiste libraries en definieer het model, de input-CSV, de lokale outputmap en de bestanden waarvan we verwachten dat de agent ze genereert.

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

Uitvoer:

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

De assertions geven een snelle sanity check voordat we OpenAI-resources aanmaken. Als de API-sleutel ontbreekt of de dataset niet gevonden kan worden, stopt het notebook direct in plaats van later in de workflow te falen.

OUTPUT_DIR is een lokale Jupyter-map waar we uiteindelijk de uit de sandbox gedownloade bestanden opslaan. 

EXPECTED_ARTIFACTS definieert daarentegen de bestanden waarvan we verwachten dat de agent ze binnen de sandbox aanmaakt.

2. Upload de financiële data

Voordat de sandbox met onze financiële data kan werken, moeten we de CSV eerst naar OpenAI uploaden.

Het Jupyter Notebook verzorgt deze stap. Het leest het lokale bestand en stuurt het via de 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}")

Uitvoer:

Uploaded raw statements: file-C6Pb6RhZrVPR4Fiq9tZ6Hn

Jouw bestands-ID zal anders zijn.

De teruggegeven bestands-ID is belangrijk, omdat we die gebruiken bij het aanmaken van de sandbox. In plaats van de inhoud van de CSV in een prompt te kopiëren, kunnen we het originele bestand direct aan de werkomgeving van de agent koppelen.

Op dit moment zijn de Northstar-jaarrekeningen bij OpenAI opgeslagen, maar de agent heeft nog geen uitvoeringsomgeving.

Die maken we nu.

3. Maak de door OpenAI gehoste sandbox aan

Nu kunnen we de gehoste omgeving maken waarin de agent de financiële analyse daadwerkelijk zal uitvoeren.

Gebruik de Containers API om een nieuwe sandbox te maken en koppel de geüploade CSV met zijn bestands-ID:

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

Uitvoer:

OpenAI sandbox: cntr_6ab7a1080b4081938d8d08ab67ac963c084798905ec997e9

De sandbox wordt gemaakt met 4 GB geheugen, en de geüploade jaarrekeningen zijn vanaf het begin binnenin beschikbaar.

We schakelen ook netwerktoegang uit:

network_policy={"type": "disabled"}

Onze financiële analyse heeft geen informatie van internet nodig, dus er is geen reden om de agent externe netwerktoegang te geven. Alles wat nodig is staat al in de CSV.

4. Definieer de taak van de financieel analist

De sandbox geeft de agent een veilige plek om te werken, maar we moeten nog precies bepalen wat hij moet doen.

In plaats van het model een vage instructie te geven zoals "analyseer dit bedrijf", geven we een gedetailleerde taak die de berekeningen, validatiecontroles, te genereren bestanden en hoe de agent zijn eigen werk moet verifiëren beschrijft.

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.
"""

Hier zit een belangrijke ontwerpkeuze.

We vragen het model niet om de financiële analyse alleen in zijn antwoord te beredeneren. 

De instructies zeggen expliciet dat het code moet schrijven, die code moet uitvoeren, de resultaten inspecteren, geselecteerde berekeningen verifiëren en eventuele afwijkingen corrigeren.

We vertellen de agent ook dat elke analytische handeling moet plaatsvinden onder /mnt/data in de gehoste sandbox.

Dit geeft de agent een duidelijke workflow:

Vind de data → valideer die → schrijf het analysescript → voer het uit → genereer artefacten → inspecteer de resultaten → verifieer berekeningen → herstel fouten indien nodig.

Zo wordt de sandbox een echte werkomgeving in plaats van alleen tijdelijke bestandsopslag.

5. Verbind de agent met de sandbox

Vervolgens koppelen we een OpenAI-agent aan de container die we eerder hebben gemaakt.

We doen dit met 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"),
)

Het belangrijkste deel is:

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

Dit vertelt ShellTool dat de agent moet verbinden met de sandbox die we al hebben gemaakt, in plaats van een andere uitvoeringsomgeving te maken of te gebruiken.

We stellen ook in:

tool_choice="required"

Dit dwingt de agent om tijdens de run een tool te gebruiken in plaats van de taak alleen met een normaal tekstantwoord af te ronden.

Voor deze tutorial is dat precies wat we willen. 

De agent moet niet alleen uitleggen hoe je de financiële kengetallen berekent. Hij moet de shell gebruiken, code in de sandbox uitvoeren en de gevraagde bestanden produceren.

6. Laat de agent de analyse uitvoeren

Met de dataset geüpload, de sandbox draaiend en de agent verbonden via ShellTool kunnen we nu de analyse starten.

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

display(Markdown(result.final_output))

Dit start de financieel-analistagent en geeft hem toegang tot de sandbox die we eerder hebben gemaakt.

De uiteindelijke output van de agent bevestigt dat de analyse succesvol is afgerond binnen /mnt/data, inclusief datavalidatie, metrische checks en het aanmaken van alle zes vereiste artefacten.

7. Download de gegenereerde artefacten

De analyse is voltooid, maar de gegenereerde bestanden staan nog in de OpenAI-sandbox.

Vervolgens sommen we de bestanden in de container op, controleren we of alle verwachte artefacten zijn gemaakt en downloaden we ze naar onze lokale map.

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

Uitvoer:

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

Op dit punt kun je de lokale map financial_analysis_output openen en alles inspecteren wat de agent heeft gemaakt.

De map bevat het analysescript, berekende kengetallen, vlaggen voor ongewone bewegingen, de volledige investeringsmemo, het validatiemanifest en een SVG-visualisatie van de financiële trends.

Het bestand investment_analysis.md bevat de hoofdtekst van de analyse, inclusief de executive view, winstgevendheid, liquiditeit, leverage, kasstromen, ongewone bewegingen en de bull- en bearcases.

Je kunt ook financial_trends.svg openen om de visuele resultaten te bekijken. 

Het geeft je snel zicht op de belangrijkste financiële trends, zoals omzet, winstgevendheid, marges en andere kerncijfers, zonder dat je eerst het hele rapport hoeft te lezen.

Belangrijk detail: we downloaden niet zomaar welke bestanden de agent ook maar heeft aangemaakt. 

Het notebook vergelijkt eerst de inhoud van de sandbox met EXPECTED_ARTIFACTS.

Als een van de vereiste bestanden ontbreekt, faalt de assertion. We controleren ook dat elk gedownload bestand niet leeg is.

Dit geeft ons een eenvoudige verificatiestap voordat we de output van de agent accepteren.

8. Ruim de sandbox op

Zodra de bestanden zijn gedownload en geverifieerd, hebben we de tijdelijke sandbox of het geüploade bronbestand niet meer nodig.

Verwijder beide resources:

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

Hiermee verwijder je de gehoste container en de geüploade financiële dataset nadat de workflow is voltooid.

Het opschonen van tijdelijke resources is een goede laatste stap, zeker als je regelmatig sandboxes aanmaakt als onderdeel van een agent-workflow.

Tot slot

Het grootste voordeel van de door OpenAI gehoste sandbox is dat de hele workflow binnen één ecosysteem blijft.

Je hoeft geen aparte sandboxprovider te koppelen, geen eigen cloudomgeving te voorzien of je eigen containerinfrastructuur te bouwen en te onderhouden. 

Je kunt een sandbox maken, bestanden koppelen, netwerktoegang beheren, de agent erin laten werken, de resultaten ophalen en de omgeving verwijderen wanneer je klaar bent — allemaal via het OpenAI-platform.

Dat maakt de workflow veel eenvoudiger te beheren.

In deze tutorial gebruikte ik de OpenAI Agents SDK met ShellTool omdat dit een eenvoudige manier biedt om een agent met een bestaande container te verbinden, terwijl ik de controle houd over de instructies, bestanden, tools en uitvoeringsstroom.

Er zijn andere manieren om dezelfde soort workflow binnen het OpenAI-ecosysteem te bouwen, waaronder directere agent-API’s en abstracties op hoger niveau voor sandboxes. 

Voor dit voorbeeld voelde de Agents SDK echter als de juiste balans tussen eenvoud en controle.

De kernboodschap is dat je een AI-agent nu een echte uitvoeringsomgeving kunt geven zonder het OpenAI-ecosysteem te verlaten:

Maak de sandbox → koppel de data → verbind de agent → voer de taak uit → haal de artefacten op → verwijder de sandbox.

Voor agent-applicaties die code moeten draaien, met bestanden werken, rapporten genereren of meerstaps analyses uitvoeren, is dat een heel bruikbaar patroon.