Comment configurer l’accès réseau des OpenAI Hosted Sandboxes ? Guide de déploiement sécurisé des Agents 2026

Un exemple du guide officiel de démarrage des Sandbox Agents s’appuie sur une seule commande d’installation avant de créer l’environnement d’exécution dans la documentation OpenAI Agents SDK. Ce point est révélateur : la facilité de lancement ne doit pas être confondue avec une autorisation réseau suffisante pour la production.

Symptôme : votre Agent exécute du code, mais échoue dès qu’il doit installer un paquet, appeler une API ou atteindre un service interne. Solution la plus rapide : partez d’un environnement sans accès réseau, autorisez seulement les destinations indispensables et basculez vers un environnement autogéré dès qu’un service privé, une base de données ou une politique réseau complexe entre en jeu.

Cette règle constitue le cœur de la configuration réseau des OpenAI Hosted Sandboxes. Les Hosted Sandboxes peuvent fournir un espace Linux, l’exécution de code, la manipulation de fichiers et la configuration de dépendances, mais la disponibilité précise des fonctions réseau, l’état de l’environnement et les options autogérées doivent être vérifiés dans la documentation officielle au moment du déploiement. Le guide Sandbox Agents officiel décrit le rôle de ces environnements ; il ne remplace pas une politique de sécurité adaptée à votre application.

À qui ce guide s’adresse-t-il ?

Vous êtes concerné si vous transformez une démonstration en tâche répétable, si votre Agent doit lire et produire des fichiers, ou si vous devez lui faire appeler une API métier.

• Développeur indépendant : vous cherchez à éviter qu’une installation improvisée ou une connexion externe rende votre prototype non reproductible.
• Ingénieur d’application IA : vous devez coordonner code exécutable, dépendances, fichiers et outils distants.
• Ingénieur plateforme : vous êtes responsable des sorties réseau, des secrets, des journaux, des artefacts et de la séparation entre le Sandbox et vos systèmes.

Le premier choix : aucune sortie, sortie limitée ou environnement autogéré

Avant d’ajouter un outil réseau dans votre Agent, classez la tâche. Le traitement d’un fichier local n’a pas le même profil qu’une opération dans une base de données interne.

Choisissez l’absence de réseau si

• les données d’entrée sont déjà déposées dans le répertoire de travail ;
• le code réalise du nettoyage, une conversion ou une analyse locale ;
• les bibliothèques nécessaires peuvent être préparées avant l’exécution ;
• l’Agent n’a pas à consulter une source externe pendant sa tâche.

C’est le point de départ le plus facile à auditer. Vous pouvez alors vérifier précisément les fichiers accessibles, les commandes exécutées et les artefacts produits, sans introduire une dépendance à un service tiers.

Choisissez une sortie limitée si

• l’Agent doit consulter une API publique déterminée ;
• il doit télécharger une dépendance ou interroger une documentation contrôlée ;
• les destinations sont connues à l’avance ;
• vous pouvez journaliser la destination, la méthode, le statut et le résultat filtré.

Une sortie limitée n’est pas un accès Internet général. Elle doit être définie comme une exception de fonctionnement, avec une liste de destinations, une durée et un usage documenté.

Préférez un environnement autogéré si

• l’Agent doit atteindre une base de données ou un réseau privé ;
• il doit utiliser un proxy d’entreprise, une authentification réseau ou des règles de routage spécifiques ;
• vous devez conserver un espace de travail durable ;
• vous devez imposer une politique détaillée sur les paquets, les journaux, les sauvegardes et les téléchargements.

La documentation des clients Sandbox doit servir à vérifier les interfaces disponibles. Elle ne doit pas être interprétée comme une promesse d’accès direct à votre réseau interne. Pour un service privé, le choix le plus sûr est souvent un relais contrôlé ou une infrastructure dont vous maîtrisez entièrement les règles.

Attention : ne demandez pas au modèle de décider seul qu’une connexion réseau est nécessaire. Il peut proposer une commande techniquement valide mais incompatible avec votre politique de sortie, vos obligations de confidentialité ou la durée de vie attendue du secret.

Dépendances, répertoire de travail et commandes de préparation

Un Agent peut échouer sans que le réseau soit réellement en cause. Le paquet a peut-être été installé dans un autre environnement, le répertoire courant peut être différent de celui attendu, ou le script peut dépendre d’un outil système absent.

Le référentiel des outils de l’Agents SDK aide à comprendre le lien entre un outil et l’exécution d’une action. Dans votre propre déploiement, séparez toutefois trois moments :

1. Préparer l’environnement : installez les versions approuvées de Python, de Node.js et des paquets système nécessaires.
2. Vérifier la préparation : exécutez un test d’import, affichez la version de l’interpréteur et vérifiez le chemin du répertoire de travail.
3. Lancer la tâche : ne laissez pas le modèle modifier silencieusement la base logicielle pendant l’opération métier.

Les dépendances de production doivent être déterminées par le code et la configuration du projet, non par une décision improvisée du modèle. Une commande de réparation peut installer une version différente, remplacer un paquet et rendre le résultat impossible à reproduire.

Pour une tâche audio ou vidéo, cette distinction est particulièrement importante : un Agent peut devoir manipuler de gros fichiers, appeler un encodeur ou produire plusieurs formats. Avant de lui permettre une sortie réseau, vérifiez d’abord que le traitement local fonctionne avec un fichier témoin, un format connu et un répertoire de sortie isolé.

API publiques, services privés et secrets ne se traitent pas de la même façon

Une API publique peut sembler anodine, mais elle présente déjà un risque de fuite de données, de consommation incontrôlée ou de réponse falsifiée. Une API interne ajoute le risque d’atteindre des ressources auxquelles l’Agent ne devrait jamais avoir accès. Une base de données demande en plus une politique précise sur les lectures, les écritures et les requêtes coûteuses.

Pour une API publique, imposez :

• une destination explicitement autorisée ;
• des méthodes HTTP limitées ;
• un délai d’attente et une taille maximale de réponse ;
• une validation du schéma retourné ;
• un traitement des erreurs qui ne révèle pas de secret.

Pour un système interne, ne connectez pas directement le Sandbox au réseau privé lorsque vous pouvez interposer un relais. Ce relais reçoit une demande structurée, vérifie l’identité de l’Agent, applique une liste d’opérations permises, utilise ses propres identifiants et renvoie uniquement les champs nécessaires. L’Agent ne voit donc ni le secret permanent ni la topologie complète du système.

Les clés ne doivent pas être écrites dans l’instruction, déposées dans un fichier accessible au code généré ou incluses dans une trace de débogage. Même si la réponse paraît correcte, le contenu d’un fichier temporaire, d’une exception ou d’un artefact téléchargé peut exposer la valeur.

Le principe de l’introduction officielle des Agents API est de composer des Agents avec des outils et des étapes d’exécution. Cela ne signifie pas que chaque outil doit obtenir un accès direct à vos services. Le contrôle doit rester dans la couche qui possède l’identité, le secret et la décision d’autorisation.

Diagnostic des échecs : suivre une chronologie plutôt que modifier au hasard

Quand l’accès réseau échoue, commencez par l’état de l’environnement, puis remontez vers la connexion. Cette méthode évite d’ajouter des droits alors que la vraie cause est un paquet absent ou un mauvais chemin.

Environnement impossible à créer

Vérifiez la configuration déclarée, le nom de l’environnement, les commandes de préparation et l’événement exact retourné par le client. Un échec avant l’exécution ne doit pas être diagnostiqué comme une panne DNS.

Connexion refusée

Confirmez la destination, le protocole et le port, puis comparez cette destination avec la politique de sortie. Si la requête atteint un relais, vérifiez également que le relais accepte l’identité et l’opération demandée.

DNS ou TLS en erreur

Une résolution DNS incorrecte, un certificat non reconnu ou une horloge incohérente produisent des symptômes différents d’un refus de permission. Conservez le message complet, sans inclure de jeton, et testez le même endpoint depuis un environnement autorisé pour distinguer le service distant du Sandbox.

Installation de dépendance échouée

Ne concluez pas immédiatement à un blocage réseau. Le paquet peut être incompatible avec la version de l’interpréteur, manquer d’un outil de compilation ou être installé dans un chemin non utilisé par l’Agent. Rejouez la préparation dans un environnement propre et comparez la sortie.

Tâche interrompue ou trop longue

Enregistrez l’étape courante, la commande lancée, l’état des fichiers et le dernier appel externe. Un Agent peut interpréter une réponse lente comme une absence de service et répéter une opération, avec un risque de doublon ou de dépassement de quota.

Le guide de démarrage rapide de l’Agents SDK fournit la base pour construire un premier Agent ; votre procédure de production doit ajouter les journaux d’état, la version des entrées, les commandes et les artefacts. Sans cette chronologie, vous ne pourrez pas savoir si l’erreur vient de la configuration, du fournisseur externe ou d’une mauvaise décision du modèle.

FAQ : les décisions qui bloquent le plus souvent un déploiement

Les Hosted Sandboxes ont-ils accès à Internet par défaut ?

Ne partez pas du principe qu’un accès Internet général est disponible ou souhaitable. La capacité exacte dépend de la configuration et de la documentation actuelle des environnements Hosted Sandbox. Concevez d’abord votre Agent pour fonctionner sans réseau, puis ajoutez uniquement les sorties indispensables, vérifiées par un test de connexion vers une destination autorisée.

Comment installer Python, Node.js et les dépendances système ?

Déclarez les dépendances reproductibles dans la phase de préparation de l’environnement, plutôt que de laisser le modèle choisir des commandes au moment de l’exécution. Vérifiez ensuite les versions, le chemin du répertoire de travail et l’import réel d’un module Python ou d’un paquet Node.js avant de lancer une tâche métier.

Quelle architecture utiliser pour une API externe ?

Pour une API publique, autorisez uniquement le domaine et la méthode nécessaires. Pour une API interne, une base de données ou un webhook, préférez un relais contrôlé qui valide la requête, applique des droits minimaux et remet un résultat filtré au Sandbox. Le Sandbox ne devrait pas recevoir un accès direct et permanent au réseau privé.

Comment éviter la fuite d’une clé API ?

Ne placez jamais une clé dans l’instruction, un fichier lisible par l’Agent ou une sortie de journal. Conservez le secret dans un composant de confiance, utilisez un identifiant temporaire lorsque c’est possible, limitez sa portée et masquez les valeurs sensibles dans les journaux. Testez aussi les erreurs et les fichiers produits, car une fuite peut venir d’un artefact.

Que vérifier lorsque l’accès réseau échoue ?

Séparez la création de l’environnement, la résolution DNS, la négociation TLS, l’authentification et l’exécution de la tâche. Conservez l’état de l’environnement, la commande exacte, la sortie d’erreur, la version des dépendances et l’entrée utilisée. Cette chronologie permet de distinguer une règle réseau incorrecte, une panne du service distant et une mauvaise interprétation par l’Agent.

Choisir l’environnement selon la tâche

Utilisez les conditions suivantes avant de valider une architecture :

• Si la tâche lit des fichiers locaux, transforme des données ou produit un rapport sans service externe, choisissez un Sandbox sans réseau.
• Si elle appelle une API publique connue et sans données sensibles, choisissez une sortie limitée, avec validation de destination et réponse filtrée.
• Si elle doit utiliser un webhook ou un service d’écriture, choisissez un relais contrôlé plutôt qu’un accès direct depuis le code généré.
• Si elle doit atteindre une base de données, un réseau privé ou une authentification d’entreprise, préférez un environnement autogéré ou une passerelle dédiée.
• Si elle conserve un espace de travail durable, exécute des tâches longues ou manipule régulièrement des artefacts volumineux, évaluez un environnement cloud contrôlé avec stockage, réseau et observabilité sous votre responsabilité.
• Sinon, revenez à l’absence de réseau et ajoutez une seule capacité à la fois, avec un test qui démontre son utilité.

Cette grille est plus fiable qu’une autorisation globale accordée parce qu’un premier prototype a rencontré une erreur. Dans un Agent de montage vidéo, par exemple, l’installation et la validation d’un outil local peuvent suffire ; dans un Agent qui prépare une publication, un relais peut être nécessaire pour éviter de donner au code généré les droits directs sur votre système de contenu.

Vérifications avant mise en production

Avant d’autoriser une tâche réelle, faites valider les points suivants par un test reproductible :

• le répertoire d’entrée ne contient pas de fichier sensible sans nécessité ;
• le code ne peut pas lire des chemins situés hors du périmètre prévu ;
• les dépendances sont déclarées, versionnées et testées avant l’exécution ;
• les sorties réseau sont limitées aux destinations documentées ;
• les secrets sont fournis hors du prompt, hors des fichiers de travail et hors des journaux ;
• les réponses externes sont validées avant d’être utilisées par le modèle ;
• les commandes, erreurs, états et artefacts possèdent un identifiant de tâche ;
• un échec réseau arrête proprement l’opération au lieu de déclencher des répétitions illimitées ;
• le téléchargement d’un résultat ne donne pas accès à un fichier temporaire inattendu.

L’évolution de l’Agents SDK rappelle que les architectures d’Agents évoluent avec les outils et les environnements d’exécution. Vous devez donc réexaminer les noms d’interfaces, les champs réseau, le mode de préparation et les options autogérées lorsque la documentation change. Une procédure correcte aujourd’hui peut devenir incomplète si elle suppose une capacité qui n’est plus exposée de la même manière.

Si votre environnement actuel est un poste local ou une machine Windows/Linux, il peut aussi présenter des défauts concrets : réseau trop large, secrets persistants, absence d’audit centralisé et environnement difficile à reproduire. Pour des essais temporaires, un poste distant ou un service cloud peut dépanner ; pour une longue tâche Agent nécessitant un espace de travail contrôlé, la location d’un Mac via kvmboot peut offrir une base plus cohérente qu’un poste personnel partagé, à condition que votre application accepte ce type d’environnement et que vous n’ayez pas besoin d’un accès physique spécifique.

Avant de choisir, comparez donc votre solution actuelle avec un Mac distant : votre poste peut laisser des identifiants persistants, mélanger les fichiers personnels et professionnels, et rendre les règles réseau difficiles à auditer. Un environnement loué par l’intermédiaire de kvmboot ne remplace pas une passerelle de sécurité pour une base interne, mais il peut fournir un espace de travail isolé et temporaire pour tester un Agent, traiter des fichiers audio ou vidéo et valider une chaîne de développement sans modifier votre machine principale. Consultez ensuite le centre d’aide de kvmboot pour vérifier si ce mode d’accès correspond à vos contraintes avant de déplacer un usage réel.