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

Bacs à sable hébergés par OpenAI

Exécutez du code et créez des fichiers téléchargeables sans avoir à 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 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 paquets npm globaux à l’aide des listes python, system ou npm, respectivement. Fixez les versions si nécessaire, par exemple avec pandas==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.

Création de 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.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.