Exécuter l’API OpenAI Agents sur des Sandboxes

Utilisez CoreWeave Sandboxes comme environnement d’exécution pour un agent managé par OpenAI. Votre application crée une session de l’API Agents et une sandbox CoreWeave. Un exécuteur Codex, au sein de cette sandbox, se connecte à OpenAI et exécute les commandes de l’agent. Cette page présente le modèle d’exécution, les identifiants d’authentification requis par chaque composant et les durées de vie des ressources que vous gérez. Vous pourrez ensuite exécuter la recette associée et reproduire ce modèle dans votre propre application. La recette associée examine un incident fictif survenu sur un service d’inférence. Trois sous-agents spécialisés analysent respectivement la latence, les erreurs et la capacité. Leur coordinateur regroupe les résultats dans un rapport d’incident et répond à une question complémentaire. L’application télécharge les résultats, puis un vérificateur local distinct contrôle les calculs et l’activité enregistrée des agents.

Modèle d’exécution

OpenAI exécute la boucle de l’agent, gère le contexte de la conversation et fournit les outils de délégation. CoreWeave fait tourner l’exécuteur ainsi que les programmes écrits par les agents. Votre application se charge du provisionnement de la sandbox, du transfert de fichiers et du nettoyage. Le coordinateur et ses sous-agents partagent une seule et même sandbox, ainsi qu’un même système de fichiers. Créer un sous-agent ne crée pas de sandbox CoreWeave distincte. Attribuez à chaque spécialiste ses propres fichiers de sortie et confiez la responsabilité du rapport final au coordinateur. Ces attributions de fichiers sont de simples conventions destinées à éviter les conflits d’écriture, et non des contrôles d’accès. Voir le guide multi-agent d’OpenAI.

Prérequis

Avant d’exécuter l’exemple, vérifiez que vous remplissez les conditions suivantes :

Une clé API Forge, ou un jeton d’accès à l’API CoreWeave disposant de l’action SANDBOX_USER, ainsi qu’une capacité suffisante pour une sandbox CPU. Suivez Choisir un identifiant d’authentification.
Un projet OpenAI ayant accès à l’API Agents et au modèle sélectionné.
Python et uv, dans les versions indiquées par le fichier de verrouillage de la recette associée.
Un accès HTTPS sortant vers api.openai.com et un accès WebSocket sécurisé vers codex-cloud-environments.chatgpt.com. La configuration de l’image nécessite également l’accès aux registres de paquets utilisés pour installer l’exécuteur et les dépendances du runtime.

Cet exemple utilise des ressources de calcul CPU pour analyser les données de télémétrie fournies. Il ne lance pas de serveur d’inférence et ne demande pas de GPU. L’utilisation des modèles OpenAI et les ressources de calcul des Sandboxes CoreWeave sont facturées selon des conditions distinctes.

Séparer les identifiants d’authentification de l’application et de l’exécuteur

Cet exemple utilise trois identifiants d’authentification : un identifiant de sandbox et deux clés OpenAI. Chaque identifiant appartient à un seul composant, ce qui permet de tenir l’accès de l’application à l’écart de la sandbox :

Identifiant d’authentification	Utilisé par	Rôle
`WANDB_API_KEY`	Votre application	Provisionner et exploiter des Sandboxes avec l’authentification Forge (`--sandbox-auth wandb`)
`CWSANDBOX_API_KEY`	Votre application	Provisionner et exploiter des Sandboxes avec l’authentification CoreWeave (par défaut)
`OPENAI_API_KEY`	Votre application	Créer des sessions, soumettre des entrées et inspecter les résultats
`OPENAI_EXECUTOR_API_KEY`	Exécuteur de la sandbox, sous le nom `CODEX_API_KEY`	Connecter cet environnement d’exécution à OpenAI

Par défaut, la recette utilise l’authentification CoreWeave. Pour utiliser la clé API Forge, passez --sandbox-auth wandb. Cette recette exige précisément le nom de variable d’environnement WANDB_API_KEY pour l’authentification Forge ; elle ne lit pas FORGE_API_KEY. Seul l’identifiant de sandbox sélectionné est requis, mais les deux clés OpenAI sont nécessaires quel que soit le mode. L’application enregistre le mode sélectionné afin que le nettoyage utilise les mêmes identifiants d’authentification du fournisseur. La clé d’application OpenAI requiert api.agents.read, api.agents.write et api.responses.write. Créez la clé d’environnement distincte dans Agents > Environments > Keys. Elle doit appartenir à la même organisation, au même projet et au même propriétaire (utilisateur ou compte de service) que la session. Définissez les autorisations sans rapport sur None. La recette transmet la clé restreinte de l’exécuteur via l’argument environment_variables du SDK. Elle ne configure aucun magasin de secrets. Ne téléversez que les entrées de la tâche. Conservez les identifiants d’authentification de l’application, la configuration locale et le vérificateur hors de la sandbox. Suivez les instructions d’authentification d’OpenAI.

Le code généré par l’agent peut lire la clé de l’exécuteur. Restreignez les autorisations de cette clé pour limiter les ressources OpenAI auxquelles ce code peut accéder.

Connecter une session d’agent

La recette exécutable met en œuvre ces étapes avec les SDK OpenAI et CoreWeave :

Créez une session API Agents auto-hébergée, puis enregistrez son ID de session et son ID d’environnement. Au démarrage de l’exécuteur, utilisez exactement le remote_url renvoyé.
Créez une sandbox CoreWeave dotée d’une durée de vie maximale explicite, ainsi que de Python et de Node.
Démarrez codex exec-server avec l’ID d’environnement renvoyé et l’URL distante telle quelle. Injectez uniquement la clé restreinte de l’exécuteur en tant que CODEX_API_KEY.
Téléversez les entrées synthétiques et les instructions de la tâche, puis vérifiez la connexion à l’environnement. Soumettez la tâche et observez son résultat.
Avant le nettoyage, récupérez les artifacts générés et les enregistrements d’activité de l’API.

À l’issue de cette séquence, les fichiers de sortie de l’agent et les enregistrements d’activité de la session sont disponibles localement pour inspection. L’extrait de configuration suivant active la délégation intégrée lors de la création de la session. La recette transmet ces dictionnaires à client.beta.agents.sessions.create() :

agent = {
    "model": "gpt-6-astra",
    "instructions": "Follow TASK.md. Delegate the three independent analyses, then synthesize their findings.",
    "multi_agent": {"enabled": True, "max_concurrent_subagents": 3},
}
environment = {
    "type": "self_hosted",
    "workspace_directory": "/workspace/project",
}

Cette configuration autorise jusqu’à trois sous-agents simultanés, sans compter le coordinateur. Les instructions demandent une délégation. La configuration seule ne prouve pas que le modèle y a eu recours. La recette attribue les commandes de script terminées via l’API grâce aux ID de tour de conversation et de sous-agent. Les commandes qui renvoient explicitement un code de sortie non nul ne sont pas retenues comme preuve d’exécution réussie. Le vérificateur signale les codes de sortie absents comme inconnus. La vérification facultative --require-exit-codes exige, pour chaque spécialiste, une preuve numérique d’un code de sortie nul. Le chevauchement des intervalles started_at et completed_at révèle des tours de sous-agents simultanés. Ces horodatages n’étant précis qu’à la seconde, ils ne prouvent ni l’exécution simultanée de processus shell ni un gain de vitesse par rapport à un run séquentiel.

Exécuter l’exemple

Suivez les étapes de configuration et d’exécution de la recette. La recette comprend des données synthétiques originales, une spécification de tâche, l’application et un vérificateur indépendant. Examinez le rapport téléchargé en regard des constats du vérificateur. Vous pouvez également examiner les tours de la session et les appels d’outils dans OpenAI Logs > Agents tant que la session existe. Sélectionnez l’organisation et le projet correspondants. Cet exemple ne fournit pas d’interface de discussion et n’assure pas de continuité avec les applications ChatGPT ou Codex. Pour un flux de travail existant basé sur une interface de ligne de commande (CLI), consultez OpenAI Agents API in cws-agent. La recette utilise directement les SDK et ne nécessite pas cette CLI.

Durées de vie de la session, de la sandbox et des fichiers

Gérez séparément la conversation, les ressources de calcul et les fichiers du workspace lorsque vous choisissez ce que vous souhaitez conserver.

Ressource	Ce qui la conserve	Ce qui y met fin
Conversation API	Réutilisation du même ID de session OpenAI	Suppression explicite de la session API, sous réserve des politiques de conservation du fournisseur
Sandbox en cours d’exécution	Maintien en activité des ressources de calcul CoreWeave	Arrêt explicite, durée de vie maximale atteinte ou défaillance de l’infrastructure
Fichiers du workspace	Conservation de la sandbox ou enregistrement des fichiers ou d’instantanés	Perte des ressources de calcul sans copie conservée

Définissez explicitement la durée de vie des ressources de calcul. La recette fixe une durée de vie maximale de 20 minutes. Cette durée de vie maximale est un plafond, et non un délai d’inactivité réinitialisé à chaque prompt. Lorsque vous reconnectez un exécuteur à la même sandbox en cours d’exécution, son workspace est conservé. En revanche, démarrer de nouvelles ressources de calcul avec le même ID d’environnement ne restaure pas ses fichiers. Téléchargez les artifacts ou utilisez les fonctionnalités de persistance de CoreWeave avant d’arrêter les ressources de calcul. La recette télécharge les artifacts, puis supprime ses ressources. Elle n’implémente ni récupération automatique, ni mécanisme d’instantané et de restauration. L’arrêt d’une sandbox ne supprime pas sa conversation API, et la suppression de la conversation n’arrête pas la sandbox. Lancez les deux opérations de nettoyage et signalez chaque échec séparément.

Gérer les échecs

Pour diagnostiquer les échecs, suivez les recommandations ci-dessous :

L’exécuteur ne se connecte jamais : vérifiez la propriété de la clé d’environnement, l’accès réseau sortant, la compatibilité de l’exécuteur et l’URL distante exacte renvoyée par OpenAI.
OpenAI signale une limite d’utilisation ou de facturation : vérifiez les limites de facturation de l’organisation et du projet OpenAI avant toute nouvelle tentative. Une connexion de l’exécuteur ne garantit pas à elle seule qu’un tour de conversation du modèle puisse s’exécuter.
Le flux se déconnecte ou le client expire : examinez l’état de la session et les événements enregistrés avant de renvoyer une entrée. Un délai d’expiration n’annule pas en soi le travail en cours dans le cloud.
Aucune délégation ni aucun chevauchement n’est observé : consultez les traces d’activité enregistrées. Un rapport correct ne suffit pas à prouver l’exécution d’un run multi-agent en parallèle.
L’environnement OpenAI expire : examinez son état avant toute nouvelle tentative. La recette peut attendre l’échéance de son travail plutôt que d’échouer immédiatement.
Le sandbox expire : récupérez les artifacts enregistrés, s’ils sont disponibles. Un sandbox de remplacement nécessite une politique explicite de restauration des fichiers.
L’application est interrompue : utilisez le journal des ressources enregistré et la commande de nettoyage de la recette. La durée de vie maximale du sandbox est une solution de repli : elle ne remplace pas la suppression de la session de l’API.

Pour les applications qui conservent des sessions, coordonnez l’arrêt avec le travail entrant. Un événement d’inactivité ne suffit pas à lui seul à garantir un arrêt sûr. Le provisionnement piloté par webhook constitue un modèle de déploiement distinct. Consultez le guide du cycle de vie des Sandboxes d’OpenAI.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Exécuter l’API OpenAI Agents sur des Sandboxes

Modèle d’exécution

Prérequis

Séparer les identifiants d’authentification de l’application et de l’exécuteur

Connecter une session d’agent

Exécuter l’exemple

Durées de vie de la session, de la sandbox et des fichiers

Gérer les échecs

​Modèle d’exécution

​Prérequis

​Séparer les identifiants d’authentification de l’application et de l’exécuteur

​Connecter une session d’agent

​Exécuter l’exemple

​Durées de vie de la session, de la sandbox et des fichiers

​Gérer les échecs

Modèle d’exécution

Prérequis

Séparer les identifiants d’authentification de l’application et de l’exécuteur

Connecter une session d’agent

Exécuter l’exemple

Durées de vie de la session, de la sandbox et des fichiers

Gérer les échecs