For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navigation principale

Bacs à sable hébergés par OpenAI

Exécutez du code et créez des fichiers téléchargeables sans gérer les ressources de calcul.

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 ou npm globaux à l’aide des listes python, system ou npm. Fixez les versions si nécessaire, par exemple avec pandas==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 facultatif cwd, 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, notamment PATH, CODEX_* et OPENAI_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.accessComportement
enabledAutorise 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.
disabledBloque l’accès sortant.
restrictedAutorise 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.

Créez summary.json
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èmePoints à vérifier
La configuration échoueInspectez 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éeVérifiez network ainsi que les hôtes atteints par des redirections.
Une opération sur un fichier du bac à sable actif échoueVé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 5xxRé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.