> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Exécuter l’API OpenAI Agents sur des Sandboxes

> Connectez des agents managés par OpenAI à une sandbox CoreWeave pour l’exécution d’outils et l’analyse dans un workspace partagé.

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.

<h2 id="execution-model">
  Modèle d’exécution
</h2>

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](https://developers.openai.com/api/docs/guides/agents-api/multi-agent) d’OpenAI.

<h2 id="requirements">
  Prérequis
</h2>

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

* Une [clé API Forge](https://forge.coreweave.com/settings#apikeys), 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](/fr/products/sandboxes/placement#choose-and-get-credentials).
* 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.

<h2 id="keep-application-and-executor-credentials-separate">
  Séparer les identifiants d’authentification de l’application et de l’exécuteur
</h2>

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**](https://platform.openai.com/agents?tab=environments\&environment_view=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](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted#authentication).

<Warning>
  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.
</Warning>

<h2 id="connect-an-agent-session">
  Connecter une session d’agent
</h2>

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

1. 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é.
2. Créez une sandbox CoreWeave dotée d’une durée de vie maximale explicite, ainsi que de Python
   et de Node.
3. 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`.
4. 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.
5. 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()` :

```python theme={"system"}
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.

<h2 id="run-the-example">
  Exécuter l’exemple
</h2>

Suivez les [étapes de configuration et d’exécution de la recette](https://github.com/coreweave/cwsandbox-recipes/tree/main/recipes/openai-agents-api).
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**](https://platform.openai.com/logs?api=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](https://github.com/coreweave/cws-agent/blob/main/docs/openai-agents.md).
La recette utilise directement les SDK et ne nécessite pas cette CLI.

<h2 id="session-sandbox-and-file-lifetimes">
  Durées de vie de la session, de la sandbox et des fichiers
</h2>

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.

<h2 id="handle-failures">
  Gérer les échecs
</h2>

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](https://developers.openai.com/api/docs/guides/agents-api/environments/lifecycle) d’OpenAI.