Test de sandbox hébergé pour les agents API : exécuteur CSV, vérifications des artefacts et gestion des échecs

Cet experiment part d’une question concrète : une session d’Agents API peut-elle accepter un fichier, le traiter à l’intérieur d’un environnement isolé et retourner un résultat vérifiable ? Un petit exécuteur Python y répond. L’entrée est un fichier CSV de transactions contenant quatre ventes, un remboursement et une ligne invalide. L’agent génère un résumé au format JSON, et l’application calcule elle-même la réponse attendue afin de pouvoir les comparer. Toutes les opinions exprimées ici sont personnelles et proviennent de tests effectués avec un compte OpenAI personnel sur le plan Pro, ainsi que de la documentation disponible à ce moment-là.

Le 10 septembre 2026, l’Agents API d’OpenAI est entrée en bêta publique, mettant à disposition un outil Codex géré qui pilote le cycle modèle-outil. L’application appelante définit la tâche à effectuer et choisit l’endroit où les commandes seront exécutées. Ce qui suit décrit la manière dont le moteur d’exécution a été conçu. Les cinq essais enregistrés proviennent d’une version antérieure de celui-ci. Le moteur révisé assure la reproductibilité et conserve les preuves, et jusqu’à présent il n’a été testé qu’en mode hors ligne.

01 Comment l’Agents API fonctionne

Quatre éléments doivent rester distincts : l’agent contient le modèle, les instructions et les outils ; l’environnement fournit des ressources de calcul optionnelles ; la session rassemble les différentes étapes au fil du temps ; les événements et les éléments indiquent ce qui se passe en temps réel ainsi que ce qui a été enregistré. Une manche correspond à une seule itération de ce cycle.

L’organisation hébergée dans cette expérience est la suivante : l’exécuteur Python ouvre la session et récupère les résultats, tandis qu’OpenAI gère le framework et le sandbox d’exécution.

La première question de conception concerne l’endroit où le cycle de l’agent doit être placé. Avec l’API Agents, OpenAI héberge le framework et assure la durabilité des sessions. Le SDK Agents exécute ce cycle dans votre propre application, ce qui vous permet de choisir le stockage et les intégrations. L’API Responses offre un accès direct au modèle tout en laissant le flux de travail associé entre vos mains.

Responses peut également exécuter des commandes de shell hébergées, de sorte qu’un calcul CSV ne nécessite pas l’API Agents. L’exécuteur utilise l’API pour gérer l’ensemble du processus, de la session à l’artefact généré. Chaque essai crée une session nouvelle et exécute une seule tâche ; il ne teste ni la persistance sur plusieurs tours ni les sous-agents.

02 Pourquoi un sandbox hébergé

Le travail ne nécessite que un endroit pour stocker le fichier CSV ainsi que le fichier Python généré par l’agent. Aucun réseau privé ni image personnalisée n’est requis, c’est pourquoi le lanceur choisit openai_hosted avec le réseau de sandbox désactivé. Les alternatives modifient principalement le propriétaire de l’espace de travail et la manière dont les fichiers sont restitués.

La valeur none signifie qu’il n’y a ni système de fichiers d’environnement ni exécution intégrée de Bash, bien que les fonctions de l’application et les serveurs MCP distants puissent encore exécuter du code ailleurs. Avec self_hosted, OpenAI continue de gérer l’infrastructure, mais c’est vous qui gérez l’environnement d’exécution.

La gestion des sorties relève de ce choix. Les fichiers dans un environnement auto-hébergé ne sont pas publiés via l’API Artifacts d’OpenAI, même lorsque l’agent les enregistre sous /workspace/outputs. Votre application doit les récupérer et les conserver elle-même.

Paramètres hébergés importants ici

Le guide hébergé aborde également les variables d’environnement, les compétences, les plugins et les répertoires de capacités. Ici, des fichiers de départ et un accès réseau de sandbox désactivé suffisent. Les connexions MCP à distance partent du service d’OpenAI, donc les paramètres de sortie du sandbox ne doivent pas être considérés comme une politique applicable à chaque connexion d’outil.

03 À l’intérieur du lanceur CSV

Le code se trouve dans openai-agents-api/sandbox_check.py, et l’exemple complet est disponible dans le répertoire openai-agents-api du dépôt techforum-repo ai-agents-experimentation sur GitHub. Le lanceur génère des montants sous forme de centimes entiers et enregistre son seed. Chaque fichier CSV inclut délibérément des cas complexes : des symboles monétaires, des séparateurs de milliers, des espaces inutiles, un remboursement négatif et une entrée N/A.

La saisie seed-42

amount,note
 $981.96 ,sale
" $1,838.10 ",sale
 $42.78 ,sale
-$100.12,refund
N/A,voided
 $155.92 ,sale

Le générateur local dérive la référence ci-dessous directement à partir de ces montants entiers. Il s’agit du résultat attendu pour cet équipement, et non d’une réponse provenant d’un agent en direct.

{
  "total_cents": 291864,
  "valid_rows": 5,
  "invalid_rows": 1
}

Les instructions envoyées

L’agent reçoit un fichier CSV ainsi qu’une tâche écrite, et la réponse attendue ne quitte jamais l’application. L’essentiel de la tâche : créer /workspace/outputs/calculate.py et l’exécuter avec Python ; charger /workspace/data.csv ; supprimer les espaces blancs, les signes dollar et les séparateurs de milliers de chaque montant ; ignorer les valeurs qui ne sont pas numériques mais conserver les remboursements négatifs ; effectuer les calculs en utilisant Decimal ou des centimes entiers, jamais des flottants binaires ; générer /workspace/outputs/summary.json contenant exactement trois champs entiers nommés total_cents, valid_rows et invalid_rows ; compter chaque ligne de données une seule fois en excluant l’en-tête ; et conserver calculate.py comme fichier de sortie.

La fonction run_trial() ouvre une session via client.beta.agents.sessions.create(), en passant gpt-6-astra ainsi que ces instructions comme agent, et charge /workspace/data.csv sous forme de base64 intégré. L’environnement est openai_hosted avec network.access défini sur disabled. Il s’agit de la même voie API utilisée dans l’expérience originale.

Qu’est-ce qui est vérifié et enregistré

1. Suivre le bon tour. Après avoir récupéré la session, le programme vérifie le tour racine. Une session échouée, une action requise, un tour échoué, une annulation ou épuisement du budget de vérification entraînent chacun un résultat distinct.
2. Récupérer les deux fichiers demandés. summary.json et calculate.py sont comparés tant par leur chemin que par leur ID de tour, ce qui signifie qu’un fichier manquant ou obsolète ne peut jamais être accepté.
3. Vérifiez le résumé. Exactement trois champs entiers doivent correspondre à la référence locale : le total en centimes, le nombre de lignes valides et le nombre de lignes invalides. Le analyseur refuse les valeurs supplémentaires, manquantes, dupliquées, booléennes, flottantes ou non finies.
4. Conservez les preuves. Pour chaque essai, l’exécutant enregistre les données d’entrée, la réponse attendue, la requête, la session la plus récente, les enregistrements des tours, les éléments sauvegardés, les métadonnées de l’artefact, les fichiers téléchargés ainsi qu’un fichier de résultats que les machines peuvent analyser.

Le guide sur les artefacts explique comment les fichiers sont liés aux tours, tandis que le guide sur l’observabilité traite de l’examen de l’activité des commandes. La vérification automatisée confirme que les fichiers existent et que la sortie structurée est exacte. Le script et les éléments sauvegardés méritent néanmoins d’être examinés avant que quiconque ne prétende connaître la manière dont le calcul a été effectué. Le code téléchargé n’est jamais exécuté sur la machine de l’application.

04 Ce que révèlent les cinq essais enregistrés

La première exécution a enregistré ses résultats le 15 septembre 2026, et chaque essai utilisait un CSV nouvellement aléatoire. Les chiffres proviennent de cette exécution. Il s’agit d’observations effectuées du côté client après la réponse de création, et les temps indiqués excluent à la fois la création de la session et le téléchargement de l’artefact.

Tous les cinq totaux rapportés par l’agent correspondaient aux valeurs de référence. Cette vérification a utilisé l’arithmétique à virgule flottante avec une tolérance inférieure à un centime. Les enregistrements de temps montrent que la première consultation a permis d’obtenir une réponse et une session établie, de sorte qu’ils ne mesurent ni le temps d’exécution précis du serveur ni la latence globale. Cinq essais réussis décrivent ce qui s’est passé lors d’une petite exécution et ne donnent aucune indication sur le taux de fiabilité général.

Quelles modifications apporte le lanceur mis à jour

Le programme révisé répète le même petit experiment avec une définition plus stricte du succès. Les centimes entiers et le nombre de lignes sont comparés avec précision, chaque entrée de départ est stockée, et le script généré ainsi que l’historique de la session sont conservés. Le chronométrage commence avant la création de la session, le téléchargement et la vérification étant eux aussi chronométrés séparément. Huit tests hors ligne couvrent ces vérifications, et les chiffres indiqués ci-dessus appartiennent toujours à l’exécution en direct précédente.

05 Gestion des échecs

La boucle de sondage utilise des délais d’attente HTTP explicites, désactive les tentatives automatiques et vérifie le budget d’essai restant entre les requêtes. Ce budget n’est pas un délai strict de fermeture du processus. Un essai enregistre son résultat avant d’essayer de nettoyer, et une réponse correcte associée à un nettoyage échoué produit néanmoins un code de sortie différent de zéro.

Une session peut avoir quatre états : idle, in_progress, requires_action et failed. La tâche CSV ne configure aucune fonctionnalité d’application, de sorte que si une action est nécessaire, l’exécuteur enregistre cet état et le signale pour inspection au lieu d’attendre indéfiniment.

Les flux en direct ne rejouent pas les événements manqués. Pour rétablir l’affichage de l’application, il faut se reconnecter et mettre en mémoire tampon les événements reçus tout en récupérant les éléments de session enregistrés, puis synchroniser les données par identifiant d’élément. Cela permet de restaurer l’affichage du travail enregistré, mais cela ne garantit pas que la commande interrompue ait été exécutée avec succès.

Un incident correspondant mérite d’être mentionné. Les notes d’enquête précédentes décrivaient des sessions restées inactives sans tours visibles, et le rapport d’incident d’OpenAI du 14 septembre 2026 mentionne des délais ou des blocages dans le lancement des tours à partir de 13h30, heure du Pacifique, ce jour-là, avant d’être finalement qualifié de résolu. Les symptômes sont similaires, mais en l’absence de preuves au niveau des requêtes, ils ne permettent pas d’établir la cause de chaque défaillance locale. Comparez l’état du service avec les sessions enregistrées et les erreurs de tours. Le programme enregistre les sessions échouées, les tours échoués, les artefacts manquants, les résumés invalides et les résultats incorrects en tant qu’éléments distincts, et il ne considère plus un tour non observé comme une preuve du retour de l’incident précédent.

Lorsque les résultats sont enfin enregistrés, si le travail n’est pas terminé, l’exécuteur demande leur annulation et tente de supprimer la session, en effectuant au maximum trois tentatives en cas de conflit lors de la suppression. Tout erreur de nettoyage reste enregistrée dans result.json. Si la création de la session échoue avant qu’un ID ne soit retourné, le nettoyage par ID n’est pas possible et l’exécuteur enregistre cette incertitude.

Un espace de travail hébergé peut expirer après une heure d’inactivité ou en l’absence de messages de maintien de connexion, tandis que les environnements de test connectés reçoivent des messages de maintien entre chaque exécution. Les artefacts publiés survivent à l’expiration de l’environnement, mais les résultats requis doivent être enregistrés avant que la session ne soit supprimée.

06 Quand utiliser sa propre ressource de calcul

Une ligne pointillée dans le diagramme d’architecture plus détaillé concerne uniquement les ressources informatiques auto-hébergées, tandis que l’expérience CSV reste hébergée sur les serveurs d’OpenAI. L’auto-hébergement devient avantageux lorsque la tâche nécessite une image spécifique, un accès à un réseau privé ou des machines déjà présentes dans votre parc. À l’intérieur de cet environnement, vous lancez codex exec-server, en lui fournissant l’URL distante et l’ID d’environnement, ainsi qu’une clé restreinte spécifique à cet environnement ; la clé d’application principale doit quant à elle rester en dehors de cet environnement.

Par la suite, l’application est responsable de la mise à disposition des ressources, du stockage, de la réconnexion et du démantèlement de celles-ci. La suppression d’une session OpenAI n’arrête pas le fonctionnement des serveurs du fournisseur, et la réutilisation d’un ID d’environnement ne restaure pas les fichiers sur une machine de remplacement.

Le self-hébergement ne rend pas non plus tout le service local. L’API Agents actuelle conserve l’état des sessions, prend en charge la résidence des données aux États-Unis et ne supporte pas la politique de zéro conservation des données.

Les coûts doivent être pris en compte dans la décision. Les tokens du modèle et les ressources de calcul hébergées sont facturés séparément, avec des tarifs pour les conteneurs basés sur la mémoire et les intervalles de facturation ; il est donc nécessaire d’enregistrer l’utilisation réelle et de ne pas estimer la facture d’une période d’essai uniquement en se basant sur le nombre de secondes écoulées.

07 Exécution de l’expérience

Le fait de l’exécuter coûte de l’argent réel, car il nécessite une utilisation d’API facturée séparément sous forme de crédits ou un arrangement de facturation API actif, et une abonnement Pro ne couvre pas ces appels. Le moteur d’exécution utilise GPT-6 Astra (gpt-6-astra), de sorte que de nombreuses tentatives ou des exécutions prolongées peuvent épuiser rapidement les crédits, et le temps de fonctionnement dans un environnement sandbox hébergé ajoute des frais de calcul. Faites d’abord une tentative, consultez le tableau de bord d’utilisation et lisez la page de tarification d’Astra avant d’en exécuter davantage.

Dans le répertoire, créez un environnement virtuel et installez le SDK correspondant. Une clé API d’application est nécessaire, avec des permissions de lecture et d’écriture des sessions ainsi que pour exécuter des inférences de modèle. Chaque tentative consomme des tokens API en temps réel et des ressources de calcul hébergées.

cd openai-agents-api
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
export OPENAI_API_KEY="your-key"
python sandbox_check.py --seed 42       # Start with one trial
# python sandbox_check.py 5 --seed 42   # Optional: five trials

La première commande exécute une seule tentative avec la graine 42, tandis que la commande optionnelle permettant cinq tentatives utilise les graines de 42 à 46. Les résultats sont stockés dans un nouveau répertoire runs/, avec un dossier par tentative. La version fixe du SDK est openai==3.13.0, et le fichier README décrit les fichiers de sortie ainsi que les options de commande.

trial-001/
  data.csv           # Exact input
  expected.json      # Local reference
  request.json       # Submitted configuration
  session.json       # Latest retrieved session
  turns.json         # Turn status, timestamps, usage
  items.json         # Saved messages and tool calls
  artifacts.json     # Published file metadata
  summary.json       # Downloaded result
  calculate.py       # Downloaded agent script
  result.json        # Checks, timing, errors, cleanup

Les exécutions échouées conservent tous les fichiers obtenus avant l’échec. Un code de sortie zéro exige des vérifications précises des résultats et la suppression confirmée de la session pour chaque tentative. Pour tester l’outil localement sans aucune appel API :

python -m unittest discover -s . -p test_sandbox_check.py -v

Sans interagir avec le réseau, l’ensemble de tests met à l’épreuve les calculs de référence, les sorties de modèles mal formatées, les artefacts obsolètes ou absents, les sessions et les tours qui échouent, les actions requises, les erreurs de requête, la gestion des délais et le nettoyage défaillant. Le lanceur révisé n’a pas encore été validé par rapport au service en ligne.

La valeur durable de ce projet réside dans une méthode reproductible pour examiner comment l’API Agents transfère des fichiers en artefacts. Un tour terminé constitue un signal, tandis qu’une sortie téléchargée et vérifiée indépendamment représente le véritable test d’acceptation. La documentation a été vérifiée le 15 septembre 2026 ; les valeurs de test proviennent de l’expérience initiale sans nouvelles mesures en temps réel, et les guides liés décrivent la version bêta actuelle, qui peut changer.