Un bac à sable hébergé par OpenAI fournit à votre agent un espace de travail Linux avec Python, Node.js et des outils en ligne de commande. OpenAI le provisionne et le connecte ; votre application fournit la tâche et récupère les résultats. Choisissez un bac à sable auto-hébergé si vous avez besoin de votre propre image, de vos propres ressources de calcul ou de votre réseau privé.
Configurez le bac à sable
Définissez environment.type sur openai_hosted et ajoutez uniquement les paramètres nécessaires
à votre charge de travail. Le répertoire de travail est /workspace.
packages: Installez des paquets Python, système ounpmglobaux à l’aide des listespython,systemounpm. Fixez les versions si nécessaire, par exemple avecpandas==2.2.3.setup_commands: Exécutez des commandes shell dans l’ordre avant le démarrage de l’agent, par exemple[{ "command": "mkdir -p reports" }]. Chaque commande possède son propre paramètre facultatifcwd, dont la valeur par défaut est/workspace.files: Fournissez des fichiers d’entrée à l’aide de leur identifiant dans l’API Files ou de leur contenu base64 intégré directement.env: Définissez des variables d’environnement dont les valeurs sont des chaînes de caractères. Les noms réservés par l’environnement d’exécution, notammentPATH,CODEX_*etOPENAI_API_KEY, sont refusés.skills,plugins,capability_directories: Ajoutez des skills et des plugins.environment_template_id: Réutilisez une configuration enregistrée dans plusieurs sessions. Les paramètres omis héritent des valeurs du modèle de configuration ; les paramètres réseau de remplacement ne peuvent pas élargir les accès autorisés par sa politique.
Les paquets et les fichiers d’entrée sont préparés avant l’exécution des commandes de configuration. Un code de sortie de configuration non nul empêche l’agent de démarrer. Utilisez une commande de configuration pour vérifier les dépendances ou les fichiers requis. Les modèles enregistrent la configuration, pas un espace de travail en cours d’exécution.
Contrôlez l’accès réseau
network.access | Comportement |
|---|---|
enabled | Autorise l’accès sortant. C’est le comportement par défaut, sauf si vous héritez de la politique d’un modèle de configuration. |
disabled | Bloque l’accès sortant. |
restricted | Autorise uniquement les hôtes répertoriés dans allowed_domains. |
Le mode restreint accepte de 1 à 100 noms d’hôtes exacts, par exemple api.example.com.
N’incluez ni caractères génériques, ni protocoles, ni chemins, ni ports. Les sous-domaines et les destinations
de redirection doivent avoir leurs propres entrées. Les serveurs MCP hébergés utilisant stdio nécessitent actuellement
un accès défini sur enabled ; consultez les prérequis de MCP sur stdio.
Vérifiez que la configuration a réussi
La réponse à la création de session indique que la configuration a commencé. Récupérez l’état via
GET /v1/agents/environments/{environment_id} en utilisant le champ environment.id de la session :
provisioning indique que la configuration est en cours ; connected indique qu’elle a réussi.
Si l’état est failed, consultez environment.error dans l’événement agent.session.environment.failed.
Attendez l’état connected avant d’ajouter des fichiers au bac à sable actif ou de les répertorier.
Fichiers et durée de vie
Chaque session dispose d’un espace de travail distinct. Les fichiers sont conservés d’un tour à l’autre tant que son
bac à sable existe. Les fichiers situés sous /workspace/outputs sont publiés sous forme d’artefacts immuables
à la fin d’un tour ; ces copies restent téléchargeables après
l’expiration du bac à sable.
Consultez Fichiers et artefacts pour les envois de fichiers, les règles relatives aux chemins, les opérations sur les fichiers du bac à sable actif, les téléchargements et les limites. Enregistrez les résultats dont vous avez besoin avant de supprimer la session.
Expiration du bac à sable
Les bacs à sable connectés reçoivent des signaux de maintien en activité, y compris entre les tours. Si l’activité et ces signaux cessent pendant une heure, le bac à sable peut être supprimé. Ce délai n’est pas configurable.
Supprimez la session lorsque vous avez terminé pour demander le nettoyage du bac à sable. Si la suppression
renvoie 409 pendant que la configuration ou l’exécution se termine, attendez et réessayez en limitant
le nombre de tentatives. La fermeture d’un flux d’événements n’annule pas la tâche.
Tarifs
Les bacs à sable hébergés par OpenAI sont facturés aux tarifs standard des conteneurs. L’utilisation du modèle est facturée séparément aux tarifs de l’API du modèle sélectionné.
Exemple : Créez un rapport
Fournissez à l’agent un fichier CSV contenant 10, 20 et 30. Il exécute du code Python pour calculer
la somme et écrit le fichier /workspace/outputs/summary.json.
Définissez OPENAI_API_KEY dans le terminal de votre application en suivant les
prérequis du guide de démarrage rapide.
Conservez cette clé en dehors du bac à sable. Utilisez une version de votre
SDK OpenAI qui inclut l’API Agents en bêta.
from openai import OpenAI
client = OpenAI()
stream = client.beta.agents.sessions.create(
agent={"model": "gpt-6-astra"},
environment={
"type": "openai_hosted",
"network": {"access": "disabled"},
"files": [
{
"type": "inline",
"path": "/workspace/amounts.csv",
"data": "YW1vdW50CjEwCjIwCjMwCg==",
}
],
},
input="Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
stream=True,
)
with stream:
for event in stream:
print(event.model_dump_json())La valeur base64 de files contient les données CSV d’entrée. Le code affiche les événements de la session.
Enregistrez la valeur de session.id fournie par agent.session.created. Après agent.session.turn.completed,
répertoriez les artefacts, recherchez summary.json
et téléchargez-le. Son contenu devrait être le suivant :
{ "total": 60 }
Un tour terminé ne garantit pas que tous les outils ont réussi. Si la tâche échoue ou si le flux se termine avant la fin de l’exécution, inspectez les éléments enregistrés de la session. Supprimez la session lorsque vous avez terminé.
Dépannage
| Problème | Points à vérifier |
|---|---|
| La configuration échoue | Inspectez l’événement d’échec de l’environnement et corrigez l’erreur liée au paquet, au fichier d’entrée ou à la commande de configuration avant de créer une autre session. |
| Une requête du bac à sable est bloquée | Vérifiez network ainsi que les hôtes atteints par des redirections. |
| Une opération sur un fichier du bac à sable actif échoue | Vérifiez que le bac à sable est à l’état connected. S’il a expiré, créez une nouvelle session et fournissez à nouveau les données d’entrée. |
Une requête d’état ou de liste de fichiers renvoie 5xx | Réessayez en augmentant les délais entre les tentatives et en fixant une durée limite. Conservez l’identifiant de la requête si l’erreur persiste. |