Bacs à sable hébergés par OpenAI : créez un analyste financier IA sécurisé

Les agents IA vont bien au-delà de la simple génération de texte. Ils savent désormais écrire du code, exécuter des commandes, manipuler des fichiers, corriger des erreurs et mener seuls des tâches en plusieurs étapes.

Mais les LLM ne sont pas toujours prévisibles. 

Même avec des consignes claires, un agent peut générer une commande inattendue ou modifier quelque chose qui ne devait pas l’être. Exécuter ce code directement sur votre machine locale ou votre serveur applicatif introduit donc un risque inutile.

Dans ce tutoriel, j’utiliserai un bac à sable hébergé par OpenAI pour créer un analyste financier IA sécurisé. Nous téléverserons un jeu de données financières, connecterons un agent à cet environnement isolé, le laisserons réaliser l’analyse et y générer les artefacts, puis téléchargerons les rapports, graphiques et fichiers de données produits.

L’analyste financier n’est qu’un exemple. L’objectif est surtout de comprendre comment offrir à un agent IA un environnement contrôlé où il peut exécuter du code et travailler sur des fichiers en toute sécurité.

Qu’est-ce que le bac à sable hébergé par OpenAI ?

Un bac à sable est un environnement isolé où le code s’exécute sans avoir un accès illimité au système qui héberge votre application.

C’est particulièrement utile pour les agents IA, dont le comportement n’est pas totalement prévisible. 

Un agent peut être invité à modifier un fichier et générer une commande qui affecte un autre répertoire, installer une dépendance inattendue ou exécuter quelque chose d’imprévu.

Plutôt que d’autoriser ces commandes à s’exécuter directement sur votre ordinateur ou votre serveur, vous pouvez placer l’agent dans un bac à sable.

OpenAI propose son propre environnement de bac à sable hébergé à cet effet. 

Il fournit à l’agent un véritable espace de travail Linux avec système de fichiers et shell, tout en isolant son exécution de votre système local.

Dans le bac à sable, l’agent peut :

• Lire et écrire des fichiers.
• Créer et exécuter des scripts.
• Lancer des commandes shell.
• Examiner la sortie des commandes.
• Corriger les erreurs et relancer son code.
• Générer des rapports, jeux de données, graphiques et autres artefacts.

Vous pouvez également contrôler à quoi le bac à sable a accès. 

Par exemple, vous pouvez ne téléverser que les fichiers nécessaires à la tâche et désactiver l’accès réseau si l’agent n’a pas besoin d’informations externes.

Différentes façons d’utiliser les bacs à sable OpenAI

OpenAI propose plusieurs manières d’exécuter des agents ou des modèles dans des environnements isolés. La principale différence tient au niveau de prise en charge par OpenAI de l’exécution et du cycle de vie de l’agent.

1. Shell Tool

Le Shell tool est l’option la plus simple. Il permet à un modèle d’exécuter des commandes shell dans un conteneur hébergé par OpenAI via l’API Responses.

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

C’est un bon choix lorsque vous avez surtout besoin d’exécuter du code, de traiter des fichiers ou d’automatiser des tâches en ligne de commande.

2. Agents API

L’Agents API est une option plus encadrée. OpenAI gère à la fois la session de l’agent et l’environnement hébergé.

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,
)Propulsé par

C’est utile quand vous souhaitez déléguer davantage la gestion de l’exécution de l’agent et du cycle de vie du bac à sable.

3. SandboxAgent

SandboxAgent fait partie du SDK Agents et convient aux agents pour lesquels l’espace de travail du bac à sable est au cœur de l’application.

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

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

Cette approche est indiquée si vous avez besoin d’espaces de travail persistants, de fichiers, d’artefacts, ou de flexibilité quant au fournisseur de bac à sable.

4. Agents SDK + ShellTool

C’est l’approche utilisée dans ce guide.

Nous créons nous-mêmes le conteneur hébergé par OpenAI, puis connectons l’agent à cet environnement précis via ShellTool.

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

Nous avons choisi cette approche, qui offre un bon compromis entre simplicité et contrôle. 

OpenAI gère l’infrastructure du bac à sable, tandis que nous conservons la main sur le conteneur, les fichiers, l’accès réseau, les consignes, les outils et le déroulé d’exécution.

Comment utiliser le bac à sable hébergé par OpenAI

Voyons comment utiliser le bac à sable hébergé par OpenAI pour créer un agent analyste financier sécurisé. 

1. Configurer l’environnement et le projet

Nous utiliserons un Jupyter Notebook pour mettre en place et tester le flux de travail. 

Le notebook gèrera l’installation des SDK requis, le téléversement du jeu de données, la création du bac à sable, le démarrage de l’agent et le téléchargement des artefacts finaux.

Point important : l’analyse financière elle-même ne s’exécutera pas dans Jupyter. 

Une fois l’agent connecté au bac à sable OpenAI, l’exécution du code, les commandes shell, la validation, les calculs et la génération des artefacts auront lieu dans l’environnement hébergé.

Considérez Jupyter comme la couche de pilotage, et le bac à sable comme l’environnement d’exécution.

Commencez par installer le SDK Python OpenAI et le SDK OpenAI Agents :

%pip install -q -U openai openai-agentsPropulsé par

Vous aurez également besoin d’une clé API OpenAI disponible via la variable d’environnement OPENAI_API_KEY.

Pour ce tutoriel, nous utiliserons un jeu de données d’une entreprise fictive, stocké ici :

financial_data/northstar_cloud_financial_statements.csvPropulsé par

Importez ensuite les bibliothèques nécessaires et définissez le modèle, le CSV d’entrée, le répertoire de sortie local et la liste des fichiers que nous attendons de l’agent.

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)"
)Propulsé par

Sortie :

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

Ces assertions offrent un contrôle rapide avant de créer des ressources OpenAI. Si la clé API manque ou si le jeu de données est introuvable, le notebook s’arrête immédiatement au lieu d’échouer plus loin.

OUTPUT_DIR est un répertoire Jupyter local dans lequel nous enregistrerons les fichiers téléchargés depuis le bac à sable. 

EXPECTED_ARTIFACTS, quant à lui, définit les fichiers que nous attendons de l’agent dans le bac à sable.

2. Téléverser les données financières

Avant que le bac à sable puisse utiliser nos données financières, nous devons d’abord téléverser le CSV vers OpenAI.

Le Jupyter Notebook se charge de cette étape : il lit le fichier local et l’envoie via l’API Files d’OpenAI.

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}")Propulsé par

Sortie :

Uploaded raw statements: file-C6Pb6RhZrVPR4Fiq9tZ6HnPropulsé par

Votre ID de fichier sera différent.

Cet ID est important, car nous l’utiliserons lors de la création du bac à sable. Plutôt que de copier le contenu du CSV dans une invite, nous joignons directement le fichier original à l’environnement de travail de l’agent.

À ce stade, les états financiers de Northstar sont stockés chez OpenAI, mais l’agent n’a pas encore d’environnement d’exécution.

Nous allons le créer maintenant.

3. Créer le bac à sable hébergé par OpenAI

Nous pouvons à présent créer l’environnement hébergé dans lequel l’agent réalisera l’analyse financière.

Utilisez l’API Containers pour créer un nouveau bac à sable et y attacher le CSV téléversé via son 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}")Propulsé par

Sortie :

OpenAI sandbox: cntr_6ab7a1080b4081938d8d08ab67ac963c084798905ec997e9Propulsé par

Le bac à sable est créé avec 4 Go de mémoire, et les états financiers téléversés y sont disponibles dès le départ.

Nous désactivons également l’accès réseau :

network_policy={"type": "disabled"}Propulsé par

Notre analyse financière n’exige pas d’informations issues d’internet, il n’y a donc aucune raison d’accorder un accès réseau externe à l’agent. Tout ce dont il a besoin se trouve dans le CSV.

4. Définir la mission de l’analyste financier

Le bac à sable offre à l’agent un espace de travail sécurisé, mais il faut encore préciser exactement ce que nous attendons.

Au lieu de donner une consigne vague du type « analyser cette entreprise », nous définissons une tâche détaillée décrivant les calculs, les vérifications, les fichiers à générer et la manière dont l’agent doit valider son propre travail.

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.
"""Propulsé par

C’est un choix important de conception.

Nous ne demandons pas au modèle de raisonner uniquement dans sa réponse. 

Les consignes lui indiquent explicitement d’écrire du code, de l’exécuter, d’examiner les résultats, de vérifier certains calculs et de corriger les écarts.

Nous précisons aussi que chaque opération analytique doit s’exécuter sous /mnt/data dans le bac à sable hébergé.

Cela donne à l’agent un déroulé clair :

Trouver les données → les valider → écrire le script d’analyse → l’exécuter → générer les artefacts → examiner les résultats → vérifier les calculs → corriger si besoin.

Le bac à sable devient ainsi un véritable environnement de travail, et pas seulement un stockage temporaire.

5. Connecter l’agent au bac à sable

Nous connectons ensuite un agent OpenAI au conteneur créé plus tôt.

Pour cela, nous utilisons 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"),
)Propulsé par

La partie essentielle :

"type": "container_reference",
"container_id": container.id,Propulsé par

Elle indique à ShellTool de connecter l’agent au bac à sable que nous avons déjà créé, au lieu d’utiliser un autre environnement d’exécution.

Nous définissons aussi :

tool_choice="required"Propulsé par

Cela force l’agent à utiliser un outil pendant l’exécution, plutôt que d’achever la tâche avec une simple réponse textuelle.

C’est exactement ce que nous voulons pour ce tutoriel. 

L’agent ne doit pas seulement expliquer comment calculer les métriques financières. Il doit utiliser le shell, exécuter du code dans le bac à sable et produire les fichiers demandés.

6. Laisser l’agent réaliser l’analyse

Le jeu de données étant téléversé, le bac à sable lancé et l’agent connecté via ShellTool, nous pouvons démarrer l’analyse.

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

display(Markdown(result.final_output))Propulsé par

Cela lance l’agent analyste financier et lui donne accès au bac à sable créé plus tôt.

La sortie finale de l’agent confirme que l’analyse s’est bien déroulée dans /mnt/data, avec validation des données, vérification des métriques et création des six artefacts requis.

7. Télécharger les artefacts générés

L’analyse est terminée, mais les fichiers générés résident encore dans le bac à sable OpenAI.

Nous allons maintenant lister les fichiers du conteneur, vérifier que tous les artefacts attendus ont été créés, puis les télécharger dans notre répertoire local.

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"
    )Propulsé par

Sortie :

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 bytesPropulsé par

À ce stade, vous pouvez ouvrir le répertoire local financial_analysis_output et inspecter tout ce que l’agent a produit.

Le dossier contient le script d’analyse, les métriques calculées, les alertes sur mouvements inhabituels, le mémo d’investissement complet, le manifeste de validation et une visualisation SVG des tendances financières.

Le fichier investment_analysis.md contient l’analyse rédigée principale, incluant la vue d’ensemble, la rentabilité, la liquidité, l’effet de levier, les flux de trésorerie, les mouvements inhabituels, ainsi que les scénarios haussier et baissier.

Vous pouvez aussi ouvrir financial_trends.svg pour examiner les résultats visuels. 

Vous obtenez ainsi une vue rapide des grandes tendances financières — revenus, rentabilité, marges et autres indicateurs clés — sans devoir parcourir l’intégralité du rapport d’abord.

Un point important : nous ne téléchargeons pas simplement tout ce que l’agent a pu créer. 

Le notebook commence par comparer le contenu du bac à sable à EXPECTED_ARTIFACTS.

Si l’un des fichiers requis manque, l’assertion échoue. Nous vérifions aussi que chaque fichier téléchargé n’est pas vide.

Cela offre une étape de vérification simple avant d’accepter la sortie de l’agent.

8. Nettoyer le bac à sable

Une fois les fichiers téléchargés et vérifiés, nous n’avons plus besoin du bac à sable temporaire ni du fichier source téléversé.

Supprimez les deux ressources :

client.containers.delete(container.id)
client.files.delete(uploaded_input.id)Propulsé par

Cela supprime le conteneur hébergé et le jeu de données financiers téléversé une fois le flux de travail terminé.

Nettoyer les ressources temporaires est une bonne pratique finale, surtout si vous créez régulièrement des bacs à sable dans le cadre d’un flux d’agents.

Pour conclure

Le principal avantage d’un bac à sable hébergé par OpenAI est que tout le flux se déroule au sein d’un même écosystème.

Vous n’avez pas à connecter un fournisseur de bac à sable tiers, à provisionner votre propre environnement cloud, ni à construire et maintenir votre propre infrastructure de conteneurs. 

Vous pouvez créer un bac à sable, y joindre des fichiers, contrôler l’accès réseau, laisser l’agent y travailler, récupérer les résultats et supprimer l’environnement une fois terminé — le tout via la plateforme OpenAI.

La gestion du flux de travail s’en trouve nettement simplifiée.

Dans ce tutoriel, j’ai utilisé le SDK OpenAI Agents avec ShellTool car il offre un moyen direct de connecter un agent à un conteneur existant tout en conservant le contrôle sur les consignes, les fichiers, les outils et l’exécution.

D’autres options existent dans l’écosystème OpenAI, avec des API d’agents plus directes et des abstractions de bac à sable de plus haut niveau. 

Pour cet exemple, toutefois, le SDK Agents offre le bon équilibre entre simplicité et contrôle.

À retenir : vous pouvez désormais offrir à un agent IA un véritable environnement d’exécution sans quitter l’écosystème OpenAI :

Créer le bac à sable → joindre les données → connecter l’agent → exécuter la tâche → récupérer les artefacts → supprimer le bac à sable.

Pour des applications d’agents qui doivent exécuter du code, manipuler des fichiers, générer des rapports ou mener des analyses en plusieurs étapes, c’est un schéma très pertinent.