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 prépare et connecte le bac à sable. Votre application fournit la tâche à exécuter 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é.
Pour les tâches qui interagissent avec des sites web via un navigateur, consultez Utilisation de l’ordinateur.
Pour préparer l’espace de travail avant de créer une session, consultez Préparation des bacs à sable en amont.
Configurez le bac à sable
Définissez environment.type sur openai_hosted dans votre requête de création de session. Ajoutez uniquement les paramètres nécessaires à votre tâche. Le répertoire de travail du bac à sable est /workspace.
Choisissez les ressources et l’accès réseau nécessaires à votre tâche avec container_size et network. Si vous utilisez un modèle d’environnement, les paramètres que vous omettez reprennent les valeurs du modèle.
Préparez les paquets et les fichiers
Utilisez les paramètres suivants pour mettre les dépendances et les fichiers d’entrée à disposition dans le bac à sable :
packages: installez des paquets Python, des paquets système ou des paquetsnpmglobaux à l’aide des listespython,systemounpm, respectivement. Fixez les versions si nécessaire, par exemple avecpandas==2.2.3.files: fournissez les fichiers d’entrée en indiquant leur identifiant dans l’API Files ou en intégrant directement leur contenu encodé en base64.
Exécutez les commandes d’initialisation
Utilisez setup_commands pour exécuter des commandes shell dans l’ordre indiqué avant le démarrage de l’agent. Par exemple, [{ "command": "mkdir -p reports" }] crée un répertoire. Chaque commande peut définir son propre répertoire de travail avec cwd. Le répertoire par défaut est /workspace.
Le bac à sable prépare les paquets et les fichiers d’entrée avant d’exécuter les commandes d’initialisation. Utilisez une commande d’initialisation pour vérifier la présence des dépendances ou des fichiers requis. Si une commande d’initialisation renvoie un code de sortie différent de zéro, l’agent ne démarre pas.
Définissez les variables d’environnement
Utilisez env pour définir des variables d’environnement dont les valeurs sont des chaînes de caractères. Le code généré par l’agent peut lire ces valeurs.
Pour les secrets, utilisez les identifiants du coffre-fort afin de conserver leurs valeurs réelles hors du bac à sable. L’environnement d’exécution refuse les noms qu’il réserve, notamment PATH, CODEX_* et OPENAI_API_KEY.
Choisissez la taille du conteneur
À la création d’une session, définissez environment.container_size pour choisir le nombre de vCPU et la quantité de mémoire dont disposera votre bac à sable. La valeur par défaut est medium.
| Taille | vCPU | Mémoire |
|---|---|---|
small |
1 | 1 Go |
medium |
2 | 4 Go |
large |
4 | 16 Go |
Par exemple, incluez cet environnement dans votre requête POST /v1/agents/sessions pour sélectionner small :
{
"environment": {
"type": "openai_hosted",
"container_size": "small"
}
}
La session renvoyée indique la taille sélectionnée dans environment.container_size. Ce paramètre s’applique uniquement aux bacs à sable hébergés par OpenAI.
Contrôlez l’accès réseau
network.access |
Comportement |
|---|---|
enabled |
Autorise les connexions sortantes. Ce mode s’applique par défaut, sauf si le bac à sable hérite de la politique réseau d’un modèle. |
disabled |
Bloque les connexions sortantes. |
restricted |
Autorise uniquement les connexions aux hôtes figurant dans allowed_domains. |
Le mode restreint accepte de 1 à 100 noms d’hôte exacts, par exemple api.example.com. N’incluez ni caractères génériques, ni protocoles, ni chemins, ni ports. Ajoutez une entrée distincte pour chaque sous-domaine et chaque destination de redirection. Les serveurs MCP hébergés qui utilisent stdio nécessitent actuellement le mode d’accès enabled. Consultez les prérequis pour les serveurs MCP utilisant stdio.
Ajoutez des skills et des plugins
Utilisez skills, plugins et capability_directories pour ajouter des skills et des plugins.
Réutilisez une configuration dans plusieurs sessions
Définissez environment_template_id pour réutiliser une configuration enregistrée. Les paramètres que vous omettez reprennent les valeurs du modèle. Si vous redéfinissez les paramètres réseau, vous ne pouvez pas étendre l’accès au-delà de ce qu’autorise le modèle. Les modèles enregistrent la configuration, mais ne conservent pas l’espace de travail en cours d’exécution.
Vérifiez que l’initialisation a réussi
La réponse à la requête de création de session indique que l’initialisation a commencé. Pour en vérifier l’état, envoyez une requête GET /v1/agents/environments/{environment_id} en utilisant la valeur de environment.id de la session.
| État | Marche à suivre |
|---|---|
provisioning |
Patientez pendant l’initialisation. |
connected |
L’initialisation a réussi. Vous pouvez ajouter des fichiers dans le bac à sable ou en obtenir la liste. |
failed |
Consultez environment.error dans l’événement agent.session.environment.failed. |
Attendez que le bac à sable passe à l’état connected avant d’y ajouter des fichiers ou d’en obtenir la liste.
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 le bac à sable existe. À la fin de chaque tour, les fichiers situés sous /workspace/outputs sont publiés sous forme d’artefacts immuables. Ces copies restent téléchargeables après l’expiration du bac à sable.
Consultez Fichiers et artefacts pour connaître les modalités d’envoi et de téléchargement, les règles relatives aux chemins, les opérations sur les fichiers du bac à sable actif et les limites applicables. 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 de connexion, y compris entre les tours. Si le bac à sable reste inactif et ne reçoit aucun de ces signaux pendant une heure, il 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 requête de suppression renvoie 409 alors que l’initialisation ou l’exécution est encore en cours, patientez, puis réessayez en limitant le nombre de tentatives. La fermeture d’un flux d’événements n’annule pas la tâche.
Tarification
Les tarifs standard des conteneurs s’appliquent aux bacs à sable hébergés par OpenAI. L’utilisation du modèle est facturée séparément aux tarifs de l’API correspondant au modèle sélectionné.
Exemple de création d’un rapport
Fournissez à l’agent un fichier CSV contenant 10, 20 et 30. L’agent exécute du code Python pour calculer la somme et écrit le résultat dans /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é hors du bac à sable. Utilisez une version du SDK OpenAI qui inclut l’API Agents en version 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.with_result_collection():
for event in stream:
print(event.model_dump_json())
result = stream.get_final_result()
client.beta.agents.sessions.artifacts.for_result(result).download(
"/workspace/outputs/summary.json", to="summary.json"
)La valeur encodée en base64 dans files contient les données CSV d’entrée. Le code affiche les événements de la session. Enregistrez la valeur de session.id figurant dans l’événement agent.session.created. Après l’événement agent.session.turn.completed, récupérez la liste des artefacts, repérez summary.json et téléchargez-le. Il devrait contenir :
{ "total": 60 }
La fin d’un tour ne garantit pas que chaque outil a fonctionné correctement. Si la tâche échoue ou si le flux s’interrompt avant la fin du tour, examinez les éléments enregistrés dans la session. Supprimez la session lorsque vous avez terminé.
Dépannage
| Problème | Points à vérifier |
|---|---|
| L’initialisation échoue | Examinez l’événement signalant l’échec de l’environnement et corrigez l’erreur liée au paquet, au fichier d’entrée ou à la commande d’initialisation avant de créer une autre session. |
| Une requête du bac à sable est bloquée | Vérifiez network ainsi que les hôtes auxquels les redirections mènent. |
| 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 fichiers d’entrée. |
Une requête visant à consulter l’état ou à obtenir la liste des fichiers renvoie 5xx |
Réessayez en espaçant de plus en plus les tentatives et en fixant une échéance. Conservez l’identifiant de la requête si l’erreur persiste. |