OpenAI Agents SDK Sandbox 2026 : validation avant lancement

Trois modes d’exécution sont actuellement décrits pour les Sandbox Agents — local, Docker et client hébergé — dans la documentation officielle, qui rappelle aussi que la fonctionnalité reste en bêta (guide officiel des Sandbox Agents). Le gagnant n’est donc pas l’environnement qui réussit une démonstration, mais celui qui apporte des preuves reproductibles sur six points : contrat de l’espace de travail, tests déterministes, intégration réelle, permissions, reprise d’état et retour arrière. Pour les chaînes dépendantes de macOS, les tests parallèles ou une campagne courte de validation, ajoutez un Mac cloud isolé ; sinon, conservez un environnement local ou conteneurisé maîtrisé.

Cette procédure s’adresse aux développeurs qui ont déjà exécuté un exemple SandboxAgent, aux ingénieurs de plateforme qui doivent contrôler les accès aux fichiers, aux commandes, au réseau et aux identifiants, ainsi qu’aux responsables IA qui répartissent les essais entre poste local, conteneur et Mac cloud. Elle ne remplace pas un tutoriel d’installation. Elle fixe plutôt le moment où un prototype doit cesser d’être jugé sur son résultat final et commencer à être jugé sur ses preuves d’exploitation.

Le point de départ : un succès visible peut cacher un échec bloquant

Un agent génère correctement un fichier audio, lance une commande de traitement vidéo et renvoie un résultat exploitable sur le poste du développeur. Le scénario semble validé. Pourtant, le même scénario peut échouer ailleurs pour des raisons qui ne concernent pas le raisonnement du modèle :

• le répertoire de travail existe localement, mais n’est jamais créé dans l’environnement cible ;
• une variable d’environnement fournit sans contrôle un jeton ou un chemin hôte ;
• une commande dispose d’un accès en écriture plus large que nécessaire ;
• un fichier produit lors d’un essai précédent est réutilisé comme s’il appartenait à la session courante ;
• l’interruption d’une tâche laisse une opération destructive partiellement exécutée ;
• une dépendance de macOS, un outil de signature ou un composant audio n’existe pas dans le conteneur de test.

Le premier risque est donc la confusion entre orchestration et exécution. Les outils de test du SDK peuvent remplacer le modèle et la session réelle pour vérifier la logique d’appel. Ils ne prouvent pas qu’un processus, un système de fichiers ou une frontière d’isolation se comporte correctement dans l’environnement livré (guide officiel des tests).

La validation d’OpenAI Agents SDK Sandbox doit commencer par le périmètre autorisé, et non par une nouvelle démonstration réussie.

Première étape : figer le contrat de l’espace de travail

Avant toute exécution, l’équipe rédige un contrat lisible par un tiers. Ce document devient la référence de comparaison entre le poste de développement, l’environnement d’intégration et l’environnement de livraison.

Le contrat doit préciser :

• les fichiers que l’agent peut lire ;
• les fichiers qu’il peut modifier ;
• les artefacts qu’il peut créer ;
• le répertoire de travail attendu ;
• les répertoires explicitement inaccessibles ;
• les variables d’environnement indispensables ;
• les identifiants interdits dans les journaux et les sorties ;
• les outils disponibles et leurs arguments acceptés ;
• la politique applicable au réseau et aux stockages externes.

Le Manifest ne doit pas être traité comme une simple formalité de démarrage. Il doit permettre de reconstruire l’environnement sans fichier caché présent sur la machine d’un seul développeur. La configuration attendue de SandboxRunConfig doit également être enregistrée : capacités demandées, montage des répertoires, mode d’exécution, état de session et paramètres de conservation. La référence officielle de SandboxRunConfig sert de base pour vérifier que les champs utilisés correspondent toujours à l’API publiée.

Que faut-il tester avant la mise en ligne d’un Sandbox ?
Il faut d’abord tester le contrat, puis les chemins normaux et les erreurs, avant de tester la performance. Un résultat final correct ne compense pas une permission excessive, un répertoire non reproductible ou une absence de règle de récupération.

Le contrat doit être versionné avec le code. Une modification de chemin, de capacité ou de variable sensible doit déclencher une nouvelle validation. Si l’environnement ne peut pas être recréé à partir de cette description, le défaut est bloquant, même si le scénario principal fonctionne.

Deuxième étape : séparer le test déterministe du test réel

L’étape suivante vérifie l’orchestration sans dépendre d’un modèle ni d’un bac à sable réellement exécuté. Le test déterministe fournit des entrées et des réponses prévisibles. Il permet d’observer si l’agent choisit le bon outil, transmet les bons paramètres et traite correctement le retour.

La campagne doit couvrir au minimum ces branches :

1. appel normal avec paramètres valides ;
2. commande refusée ou terminée en erreur ;
3. fichier demandé absent ;
4. sortie d’outil mal formée ou incomplète ;
5. interruption prématurée du flux ;
6. nouvelle tentative après une erreur récupérable.

Ces branches ne constituent pas des mesures de robustesse du système d’exploitation. Elles vérifient plutôt la discipline du code : validation des arguments, routage des capacités, distinction entre erreur temporaire et erreur définitive, arrêt propre et traitement de la sortie finale.

L’API scripted_sandbox_session est utile ici pour simuler une session contrôlée et rejouable (documentation de scripted_sandbox_session). Les assertions doivent porter sur des éléments précis : commande appelée, chemin transmis, nombre de tentatives prévu par la politique, état final et message d’erreur exposé à l’utilisateur.

Attention. Un test déterministe qui simule une permission accordée ne prouve pas que le système d’exécution refusera réellement un accès hors périmètre. Il faut conserver une frontière nette entre « le code a demandé la bonne action » et « l’environnement a effectivement empêché la mauvaise action ».

Le principal avantage de cette étape est sa lisibilité. Quand elle échoue, l’équipe peut attribuer le défaut à la logique d’orchestration. Elle évite de masquer une erreur de routage derrière les variations d’un modèle ou d’un système de fichiers.

Troisième étape : confronter l’agent à l’environnement livré

Après l’orchestration, l’agent doit exécuter des tâches représentatives dans une sandbox réelle. La structure des dossiers, les dépendances, l’identité d’exécution et le mode de lancement doivent correspondre à la cible. Le test ne doit pas utiliser un poste « enrichi » par des outils absents de l’environnement final.

Pour un projet audio, cela signifie vérifier l’import d’un fichier, le traitement, l’écriture de l’export et la présence des métadonnées attendues. Pour un flux vidéo ou de design, il faut contrôler les formats, les ressources, les fichiers temporaires et les artefacts finaux. Un projet lié à la signature, à un composant système ou à une chaîne exclusivement macOS doit être rejoué sur un Mac réel. Un résultat obtenu dans un conteneur Linux ne peut pas remplacer cette preuve de compatibilité.

La campagne d’intégration doit conserver :

• l’identifiant de version du code et de la configuration ;
• le contenu utile du Manifest ;
• l’arborescence initiale et finale, sans secret ;
• l’identité et les capacités de la session ;
• les commandes autorisées et refusées ;
• les artefacts produits, avec leur empreinte si le processus le permet ;
• les journaux filtrés ;
• les erreurs observées lors d’une exécution à froid, continue ou parallèle.

Aucune durée, aucun débit et aucune amélioration de performance ne doivent être présentés comme universels sans mesure attribuée. Dans cette phase, l’objectif est la reproductibilité : une seconde création de l’environnement doit produire les mêmes conditions de départ, et non nécessairement une sortie binaire identique si le flux dépend d’un traitement non déterministe.

Pourquoi un agent validé localement échoue-t-il après sa mise en ligne ?
La cause est souvent extérieure au scénario nominal : chemin local implicite, dépendance non déclarée, permission héritée, variable absente, outil macOS indisponible ou état résiduel. La comparaison doit commencer par l’environnement et les droits, pas par une nouvelle modification du prompt.

Quatrième étape : réduire les permissions avant de rechercher la vitesse

Une sandbox n’est pas sûre parce qu’elle possède un nom rassurant. L’équipe doit vérifier ce que l’agent peut réellement atteindre. Le principe de moindre privilège s’applique à chaque capacité : lecture, écriture, exécution, réseau et accès à un stockage externe.

Pour chaque action, deux questions doivent recevoir une réponse écrite :

• cette capacité est-elle indispensable à la tâche ?
• que se passe-t-il si l’agent tente une action plus large ?

Les montages doivent être conçus en lecture seule lorsque l’écriture n’est pas nécessaire. Les chemins hôtes, les répertoires de configuration et les fichiers d’identifiants ne doivent pas être rendus accessibles par commodité. Les variables d’environnement doivent être classées. Une valeur nécessaire à une opération ne doit pas devenir un moyen indirect de découvrir d’autres ressources.

La validation de SandboxAgent doit inclure des tentatives contrôlées de lecture hors périmètre, d’écriture dans un répertoire interdit, d’envoi d’un artefact vers un emplacement externe et d’exécution d’une commande à haut risque. Chaque tentative doit aboutir à un refus explicite, à une demande d’approbation ou à un arrêt conforme à la politique.

La documentation officielle sur le cycle de vie et les limites des Sandbox Agents doit être relue avant de transformer cette vérification en engagement de sécurité. Le statut bêta signifie que l’API, les réglages par défaut et les capacités prises en charge peuvent encore évoluer. Une validation doit donc enregistrer la version examinée et non déclarer une garantie permanente.

Comment vérifier les droits sur les fichiers et les commandes d’un SandboxAgent ?
Il faut comparer les capacités déclarées aux actions effectivement observées, puis tenter des accès interdits dans un environnement sans données sensibles. La preuve attendue n’est pas seulement l’absence d’erreur : c’est le refus vérifiable, journalisé et reproductible de l’action hors contrat.

Le client local ne doit pas être assimilé à une isolation de production. Un poste peut contenir des sessions ouvertes, des clés, des extensions ou des chemins accessibles par héritage. Une exécution destinée à des données réelles doit disposer de sa propre frontière contrôlée.

Comparer les preuves avant de changer d’environnement

Au milieu de la campagne, une comparaison simple aide à éviter les conclusions excessives. Chaque type de test répond à une question différente.

Couche d’acceptation	Ce qu’elle permet de prouver	Ce qu’elle ne prouve pas	Décision attendue
Test déterministe du SDK	Routage, paramètres, erreurs, reprises prévues et sortie finale	Isolation réelle, droits du système et compatibilité macOS	Corriger le code avant toute intégration
Sandbox réelle d’intégration	Fichiers, processus, dépendances, répertoires et artefacts dans l’environnement cible	Résistance générale à toutes les menaces ou stabilité d’un autre hôte	Reproduire ou bloquer selon les écarts
Validation d’isolation de type production	Limites de capacité, secrets, réseau, approbations et actions destructives	Compatibilité avec une cible non testée	Autoriser, compléter les preuves ou changer d’environnement

Le poste local reste adapté lorsque l’équipe possède la machine, maîtrise sa réinitialisation et cherche à diagnostiquer rapidement. Un conteneur convient à une partie des dépendances reproductibles, mais il ne représente pas automatiquement macOS. Un Mac cloud devient pertinent lorsque l’équipe doit isoler des sessions, répéter une campagne sur une période courte ou tester des outils audio, vidéo, de signature et de système propres à macOS.

Pour organiser ces accès, la console ProxyMac peut être consultée comme point de départ opérationnel. Elle ne remplace toutefois pas le contrat d’acceptation : l’équipe doit conserver ses propres versions de configuration, résultats et décisions.

Cinquième étape : interrompre la tâche et vérifier la reprise

Un long traitement réussi ne suffit pas. Il faut provoquer une interruption à un moment significatif : avant l’écriture d’un artefact, après une étape de transformation ou pendant une opération nécessitant une approbation. La reprise doit être observée, pas déduite du fait que la session possède un identifiant.

L’équipe vérifie alors :

• si l’état de session est conservé comme prévu ;
• si le snapshot ou l’espace de travail sauvegardé correspond au bon point de reprise ;
• si les fichiers temporaires sont identifiés ;
• si une étape déjà terminée n’est pas exécutée une seconde fois ;
• si une commande destructive possède une protection contre la répétition ;
• si une nouvelle session démarre réellement sans récupérer les fichiers de l’ancienne ;
• si le nettoyage échoue, quelle règle impose l’arrêt ou la recréation.

Comment tester la reprise d’un snapshot et la poursuite d’une tâche d’agent ?
Il faut interrompre activement le traitement, relever l’état sauvegardé, relancer dans une session contrôlée, puis comparer les opérations effectuées avant et après l’arrêt. Toute répétition non autorisée, tout fichier ancien réutilisé ou tout état divergent doit être classé comme défaut jusqu’à analyse.

Une stratégie saine préfère parfois la recréation complète à une reprise incertaine. Si l’équipe ne peut pas prouver que l’état est cohérent, elle doit détruire l’environnement de travail, nettoyer les artefacts et repartir d’un contrat neuf. Cette décision peut coûter du temps, mais elle évite de poursuivre une tâche avec un historique partiellement corrompu.

Les traces doivent être suffisamment détaillées pour relier un appel d’outil, une décision et un changement d’état, sans exposer de secret. Les principes de traçage des Agents SDK aident à structurer cette observation. Ils ne dispensent pas d’un filtrage des données sensibles ni d’une politique de conservation validée par l’équipe.

Sixième étape : transformer les résultats en décision de mise en ligne

La dernière étape ne consiste pas à compter les scénarios réussis. Elle consiste à classer chaque observation en trois catégories :

• validé : preuve obtenue, répétable et rattachée à la version examinée ;
• à compléter : résultat partiel, environnement différent ou preuve insuffisante ;
• bloquant : défaut qui expose une donnée, invalide la reproductibilité ou empêche une récupération sûre.

Les blocages doivent inclure l’accès hors périmètre, l’exposition d’un identifiant, l’environnement impossible à recréer, la reprise incohérente, le nettoyage incomplet et l’absence de retour arrière. Une campagne parallèle ne doit pas être déclarée sûre simplement parce que chaque tâche isolée fonctionne.

La checklist suivante peut être jointe au ticket de livraison :

• [ ] Le contrat de l’espace de travail est versionné avec le code.
• [ ] Le Manifest, l’identité d’exécution et le SandboxRunConfig attendu sont archivés.
• [ ] Les tests déterministes couvrent appel normal, commande en échec, fichier absent, arrêt prématuré et nouvelle tentative.
• [ ] Une sandbox réelle a été créée sans dépendre de fichiers personnels du poste.
• [ ] Les chemins, permissions, commandes et artefacts correspondent à l’environnement prévu.
• [ ] Les dépendances macOS ont été vérifiées sur un Mac réel lorsqu’elles sont nécessaires.
• [ ] Les accès réseau, variables sensibles et stockages externes ont été contrôlés.
• [ ] Les actions destructives disposent d’un refus ou d’une approbation explicite.
• [ ] Une interruption volontaire a vérifié l’état, le snapshot et le nettoyage.
• [ ] La reprise ne répète pas une opération à risque et n’importe pas un ancien fichier.
• [ ] Une règle écrite impose la recréation de l’environnement en cas d’état incertain.
• [ ] Les versions, journaux filtrés, anomalies et responsables sont conservés.
• [ ] Chaque élément « à compléter » possède une date et un propriétaire.
• [ ] Aucun blocage de sécurité, de reproductibilité ou de retour arrière ne reste ouvert.

Cette liste répond à la question des tests nécessaires avant la mise en ligne, mais elle ne doit pas devenir une formalité. Un item non démontré reste non validé. Le statut bêta d’OpenAI Agents SDK Sandbox impose aussi de relancer cette revue après une évolution documentée de l’API, des clients ou des capacités prises en charge.

Choisir un Mac cloud sans déplacer aveuglément la production

Un environnement Mac cloud est justifié lorsque la validation dépend de macOS, lorsqu’un projet audio ou vidéo exige ses outils natifs, lorsque plusieurs sessions doivent être isolées ou lorsqu’une équipe veut concentrer une campagne de régression sans immobiliser le poste d’un développeur. Il est moins pertinent pour une charge longue et stable qui nécessite une machine dédiée en permanence, ou pour un flux exigeant des interfaces physiques locales.

La bonne méthode consiste à louer un environnement séparé pour la validation, à appliquer le même contrat d’espace de travail, puis à rejouer les cas de permissions, d’artefacts, d’interruption et de reprise. Il ne faut pas copier l’état du poste de développement et l’appeler production. Si une campagne doit manipuler des données sensibles, la politique de confidentialité de ProxyMac doit être rapprochée des règles internes de conservation et d’effacement.

Par rapport à un poste local, la solution actuelle peut cumuler trois défauts : dépendances personnelles invisibles, accès partagé difficile à auditer et disponibilité limitée pour les essais parallèles. Par rapport à un conteneur, elle peut aussi masquer les incompatibilités macOS jusqu’au dernier moment. Dans ces cas précis, louer un Mac auprès de ProxyMac offre un environnement distinct à soumettre au même protocole, avec une séparation plus nette entre développement, intégration et validation finale.

La décision reste conditionnelle : un projet sans dépendance macOS n’a pas besoin d’un Mac cloud par principe ; un projet audio, vidéo, de design ou de signature qui échoue à reproduire son environnement doit en revanche l’évaluer avant livraison. Le bon usage de ProxyMac n’est pas de contourner la checklist, mais de fournir une cible isolée sur laquelle elle peut être rejouée et documentée.