OpenAI-gehostete Sandboxes: Baue eine sichere KI-Finanzanalystin

KI-Agenten sind längst über einfache Textgenerierung hinaus. Sie können Code schreiben, Befehle ausführen, mit Dateien arbeiten, Fehler beheben und mehrstufige Aufgaben eigenständig erledigen.

Aber LLMs verhalten sich nicht immer völlig vorhersehbar. 

Selbst mit klaren Anweisungen kann ein Agent einen unerwarteten Befehl erzeugen oder etwas ändern, das nicht verändert werden sollte. Lässt du diesen Code direkt auf deinem lokalen Rechner oder App-Server laufen, gehst du unnötige Risiken ein.

In diesem Tutorial nutze ich eine von OpenAI gehostete Sandbox, um eine sichere KI-Finanzanalystin zu bauen. Wir laden einen Finanzdatensatz hoch, verbinden einen Agenten mit der isolierten Umgebung, lassen ihn dort die Analyse durchführen und Artefakte erzeugen und laden anschließend die Berichte, Charts und Datendateien herunter.

Die Finanzanalystin ist nur ein Beispiel. Das Ziel ist zu verstehen, wie du einem KI-Agenten eine kontrollierte Umgebung gibst, in der er sicher Code ausführen und mit Dateien arbeiten kann.

Was ist die von OpenAI gehostete Sandbox?

Eine Sandbox ist eine isolierte Umgebung, in der Code laufen kann, ohne uneingeschränkten Zugriff auf das System deiner Anwendung zu erhalten.

Das ist besonders nützlich für KI-Agenten, weil ihr Verhalten nicht vollständig vorhersehbar ist. 

Ein Agent könnte angewiesen sein, eine Datei zu ändern, aber einen Befehl generieren, der ein anderes Verzeichnis betrifft, eine unerwartete Abhängigkeit installieren oder etwas ausführen, womit du nicht gerechnet hast.

Anstatt diese Befehle direkt auf deinem Laptop oder Server zuzulassen, kannst du den Agenten in eine Sandbox setzen.

OpenAI stellt dafür eine eigene gehostete Sandbox-Umgebung bereit. 

Sie bietet einem Agenten einen echten Linux-Arbeitsbereich mit Dateisystem und Shell – und hält die Ausführung dabei getrennt von deinem lokalen System.

In der Sandbox kann der Agent:

• Dateien lesen und schreiben.
• Skripte erstellen und ausführen.
• Shell-Befehle ausführen.
• Befehlsausgaben prüfen.
• Fehler beheben und Code erneut ausführen.
• Berichte, Datensätze, Charts und andere Artefakte erzeugen.

Du kannst außerdem steuern, worauf die Sandbox Zugriff hat. 

Zum Beispiel kannst du nur die für die Aufgabe benötigten Dateien hochladen und den Netzwerkzugriff deaktivieren, wenn der Agent keine externen Informationen braucht.

Verschiedene Einsatzwege für OpenAI-Sandboxes

OpenAI bietet mehrere Optionen, um Agenten oder Modelle in isolierten Umgebungen auszuführen. Der Hauptunterschied liegt darin, wie viel der Ausführung und des Agenten-Workflows OpenAI für dich übernimmt.

1. Shell Tool

Das Shell Tool ist die einfachste Option. Es erlaubt einem Modell, über die Responses API Shell-Befehle in einem von OpenAI gehosteten Container auszuführen.

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

Das ist sinnvoll, wenn du vor allem Code-Ausführung, Dateiverarbeitung oder Kommandozeilen-Aufgaben brauchst.

2. Agents API

Die Agents API ist die stärker gemanagte Option. OpenAI verwaltet sowohl die Agenten-Session als auch die gehostete Umgebung.

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

Das ist hilfreich, wenn du möchtest, dass OpenAI mehr vom Agenten-Runtime und dem Sandbox-Lebenszyklus übernimmt.

3. SandboxAgent

SandboxAgent ist Teil des Agents SDK und für Agenten gedacht, bei denen der Sandbox-Arbeitsbereich ein Kernbestandteil der Anwendung ist.

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

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

Das eignet sich, wenn du persistente Arbeitsbereiche, Dateien, Artefakte oder Flexibilität bei der Wahl des Sandbox-Anbieters brauchst.

4. Agents SDK + ShellTool

Dieses Vorgehen nutzen wir in diesem Guide.

Wir erstellen den von OpenAI gehosteten Container selbst und verbinden den Agenten dann mit genau dieser Umgebung über ShellTool.

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

Wir haben diesen Ansatz gewählt, weil er einen guten Kompromiss aus Einfachheit und Kontrolle bietet. 

OpenAI betreibt die Sandbox-Infrastruktur, während wir weiterhin Container, Dateien, Netzwerkzugriff, Agenten-Instruktionen, Tools und den Ausführungsablauf steuern.

So nutzt du die von OpenAI gehostete Sandbox

Schauen wir uns an, wie wir mit der OpenAI-Sandbox eine sichere Finanzanalystin als Agentin erstellen. 

1. Umgebung und Projekt einrichten

Wir verwenden ein Jupyter Notebook, um das Setup und den Workflow zu testen. 

Das Notebook übernimmt Aufgaben wie das Installieren der benötigten SDKs, den Daten-Upload, das Erstellen der Sandbox, das Starten des Agenten und das Herunterladen der finalen Artefakte.

Wichtig ist jedoch: Die eigentliche Finanzanalyse läuft nicht in Jupyter. 

Sobald der Agent mit der OpenAI-Sandbox verbunden ist, finden Code-Ausführung, Shell-Befehle, Validierung, Berechnungen und die Artefakt-Erzeugung in der gehosteten Sandbox-Umgebung statt.

Denk an Jupyter als Steuerungsschicht, während die Sandbox die Ausführungsumgebung ist.

Installiere zuerst das OpenAI Python SDK und das OpenAI Agents SDK:

%pip install -q -U openai openai-agentsBereitgestellt von

Du brauchst außerdem einen OpenAI API-Schlüssel in der Umgebungsvariablen OPENAI_API_KEY.

Für dieses Tutorial nutzen wir den Datensatz eines fiktiven Unternehmens unter:

financial_data/northstar_cloud_financial_statements.csvBereitgestellt von

Als Nächstes importieren wir die benötigten Bibliotheken und definieren Modell, Input-CSV, lokales Ausgabeverzeichnis sowie die Dateien, die der Agent erzeugen soll.

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

Ausgabe:

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

Die Assertions sind ein schneller Sanity-Check, bevor wir Ressourcen bei OpenAI erstellen. Fehlt der API-Schlüssel oder ist der Datensatz nicht auffindbar, bricht das Notebook sofort ab – statt später im Workflow zu scheitern.

OUTPUT_DIR ist ein lokales Jupyter-Verzeichnis, in dem wir später die aus der Sandbox heruntergeladenen Dateien speichern.

EXPECTED_ARTIFACTS definiert hingegen die Dateien, die der Agent innerhalb der Sandbox erzeugen soll.

2. Finanzdaten hochladen

Bevor die Sandbox mit den Finanzdaten arbeiten kann, müssen wir die CSV bei OpenAI hochladen.

Das übernimmt das Jupyter Notebook: Es liest die lokale Datei und sendet sie über die 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}")Bereitgestellt von

Ausgabe:

Uploaded raw statements: file-C6Pb6RhZrVPR4Fiq9tZ6HnBereitgestellt von

Deine File-ID wird anders sein.

Die zurückgegebene File-ID ist wichtig, weil wir sie beim Erstellen der Sandbox nutzen. Statt den CSV-Inhalt in einen Prompt zu kopieren, hängen wir die Originaldatei direkt an die Arbeitsumgebung des Agenten an.

Zu diesem Zeitpunkt liegen die Northstar-Finanzstatements bei OpenAI, aber der Agent hat noch keine Ausführungsumgebung.

Die erstellen wir als Nächstes.

3. Die von OpenAI gehostete Sandbox erstellen

Jetzt erstellen wir die gehostete Umgebung, in der der Agent die Finanzanalyse tatsächlich durchführt.

Nutze die Containers API, um eine neue Sandbox zu erstellen und die hochgeladene CSV über ihre File-ID anzuhängen:

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

Ausgabe:

OpenAI sandbox: cntr_6ab7a1080b4081938d8d08ab67ac963c084798905ec997e9Bereitgestellt von

Die Sandbox wird mit 4 GB RAM erstellt, und die hochgeladenen Finanzstatements stehen darin von Beginn an zur Verfügung.

Außerdem deaktivieren wir den Netzwerkzugriff:

network_policy={"type": "disabled"}Bereitgestellt von

Unsere Finanzanalyse benötigt keine Informationen aus dem Internet, daher gibt es keinen Grund, dem Agenten externen Netzwerkzugriff zu gewähren. Alles Nötige steckt bereits in der CSV.

4. Die Aufgabe der Finanzanalystin definieren

Die Sandbox bietet dem Agenten einen sicheren Arbeitsbereich, aber wir müssen noch genau festlegen, was er tun soll.

Anstatt dem Modell eine vage Anweisung wie „analysiere dieses Unternehmen“ zu geben, formulieren wir eine detaillierte Aufgabe mit Berechnungen, Validierungen, zu erzeugenden Dateien und der Art, wie der Agent seine Arbeit selbst überprüft.

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

Hier gibt es eine wichtige Designentscheidung.

Wir bitten das Modell nicht, die Finanzanalyse nur in seiner Textantwort durchzudenken. 

Die Instruktionen fordern explizit, Code zu schreiben, auszuführen, Ergebnisse zu prüfen, ausgewählte Berechnungen zu verifizieren und Abweichungen zu korrigieren.

Wir geben dem Agenten außerdem vor, dass jede analytische Operation unter /mnt/data in der gehosteten Sandbox stattfinden muss.

Das gibt dem Agenten einen klaren Ablauf:

Daten finden → validieren → Analyseskript schreiben → ausführen → Artefakte erzeugen → Ergebnisse prüfen → Berechnungen verifizieren → Fehler ggf. beheben.

So wird die Sandbox zu einer echten Arbeitsumgebung statt nur zu einem temporären Dateispeicher.

5. Den Agenten mit der Sandbox verbinden

Als Nächstes verbinden wir einen OpenAI-Agenten mit dem zuvor erstellten Container.

Dazu nutzen wir 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"),
)Bereitgestellt von

Wichtig ist Folgendes:

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

Das teilt ShellTool mit, den Agenten mit der bereits erstellten Sandbox zu verbinden – statt eine andere Ausführungsumgebung zu erzeugen oder zu nutzen.

Außerdem setzen wir:

tool_choice="required"Bereitgestellt von

Dadurch ist der Agent gezwungen, während des Laufs ein Tool zu verwenden, anstatt die Aufgabe nur mit einer normalen Textantwort abzuschließen.

Für dieses Tutorial ist das exakt gewünscht. 

Der Agent soll nicht nur erklären, wie Kennzahlen zu berechnen sind. Er soll die Shell nutzen, Code in der Sandbox ausführen und die angeforderten Dateien erzeugen.

6. Den Agenten die Analyse durchführen lassen

Mit hochgeladenem Datensatz, laufender Sandbox und über ShellTool verbundener Agentin können wir die 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))Bereitgestellt von

Damit starten wir die Finanzanalystin und geben ihr Zugriff auf die zuvor erstellte Sandbox.

Die finale Ausgabe des Agenten bestätigt, dass die Analyse erfolgreich in /mnt/data durchgeführt wurde – inklusive Datenvalidierung, Kennzahlenchecks und Erstellung aller sechs erforderlichen Artefakte.

7. Erzeugte Artefakte herunterladen

Die Analyse ist abgeschlossen, aber die erzeugten Dateien liegen noch in der OpenAI-Sandbox.

Als Nächstes listen wir die Dateien im Container auf, prüfen, ob alle erwarteten Artefakte erzeugt wurden, und laden sie in unser lokales Verzeichnis.

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

Ausgabe:

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 bytesBereitgestellt von

Jetzt kannst du das lokale Verzeichnis financial_analysis_output öffnen und alles inspizieren, was der Agent erzeugt hat.

Der Ordner enthält das Analyseskript, berechnete Kennzahlen, Markierungen ungewöhnlicher Bewegungen, das vollständige Investment-Memo, das Validierungsprotokoll sowie eine SVG-Visualisierung der finanziellen Trends.

Die Datei investment_analysis.md enthält die Hauptanalyse, inklusive Executive View, Profitabilität, Liquidität, Leverage, Cashflow, ungewöhnlichen Bewegungen sowie Bull- und Bear-Case.

Du kannst auch financial_trends.svg öffnen, um die Visualisierung zu prüfen. 

Sie liefert dir einen schnellen Überblick über zentrale Trends – etwa Umsatz, Profitabilität, Margen und weitere Kennzahlen –, ohne gleich den ganzen Bericht lesen zu müssen.

Ein wichtiger Punkt: Wir laden nicht einfach beliebige vom Agenten erzeugte Dateien herunter. 

Das Notebook vergleicht den Sandbox-Inhalt zuerst mit EXPECTED_ARTIFACTS.

Fehlt eine der Pflichtdateien, schlägt die Assertion fehl. Wir prüfen außerdem, dass jede heruntergeladene Datei nicht leer ist.

So erhalten wir einen einfachen Verifizierungsschritt, bevor wir das Agenten-Ergebnis akzeptieren.

8. Sandbox aufräumen

Sobald die Dateien heruntergeladen und geprüft sind, benötigen wir die temporäre Sandbox und die hochgeladene Quelldatei nicht mehr.

Lösche beide Ressourcen:

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

Damit entfernst du den gehosteten Container und den hochgeladenen Finanzdatensatz nach Abschluss des Workflows.

Das Aufräumen temporärer Ressourcen ist ein guter letzter Schritt – besonders, wenn du im Rahmen eines Agenten-Workflows regelmäßig Sandboxes erstellst.

Fazit

Der größte Vorteil der von OpenAI gehosteten Sandbox ist, dass der gesamte Workflow in einem Ökosystem bleibt.

Du musst keinen separaten Sandbox-Anbieter anbinden, keine eigene Cloud-Umgebung bereitstellen und keine Container-Infrastruktur selbst aufbauen und warten. 

Du kannst eine Sandbox erstellen, Dateien anhängen, den Netzwerkzugriff steuern, den Agenten darin arbeiten lassen, die Ergebnisse abrufen und die Umgebung am Ende wieder löschen – alles über die OpenAI-Plattform.

Das macht den Workflow deutlich einfacher zu managen.

In diesem Tutorial habe ich das OpenAI Agents SDK mit ShellTool genutzt, weil es eine unkomplizierte Möglichkeit bietet, einen Agenten mit einem bestehenden Container zu verbinden – bei voller Kontrolle über Instruktionen, Dateien, Tools und Ausführungsfluss.

Es gibt weitere Wege, denselben Workflow im OpenAI-Ökosystem umzusetzen – inklusive direkterer Agent-APIs und höherer Sandbox-Abstraktionen. 

Für dieses Beispiel war das Agents SDK jedoch der richtige Mittelweg aus Einfachheit und Kontrolle.

Das Wichtigste: Du kannst einem KI-Agenten jetzt eine echte Ausführungsumgebung geben, ohne das OpenAI-Ökosystem zu verlassen:

Sandbox erstellen → Daten anhängen → Agent verbinden → Aufgabe ausführen → Artefakte abrufen → Sandbox löschen.

Für Agenten-Anwendungen, die Code ausführen, Dateien manipulieren, Berichte erstellen oder mehrstufige Analysen durchführen müssen, ist das ein sehr nützliches Muster.