Architecture

OpenAI fait fonctionner le harnais de l’agent. Votre application lui confie des tâches et en reçoit les résultats. Ajoutez un environnement lorsque l’agent a besoin de ressources de calcul ou de fichiers.

Les composants

• Harnais : instance de Codex hébergée par OpenAI qui gère la boucle d’appels au modèle et aux outils et maintient la session de l’agent.
• Environnement : espace dans lequel l’agent exécute des commandes et du code et travaille sur des fichiers. Il peut s’agir d’un bac à sable distant, de votre ordinateur portable, d’un conteneur Docker ou d’une fonction AWS Lambda.
• Serveur d’application : votre code qui relie l’agent à votre produit. Il soumet les tâches, reçoit les événements et traite les appels aux outils de type fonction. Lorsque vous fournissez l’environnement, votre code en gère également le cycle de vie.

Commencez avec les composants nécessaires à votre tâche. Le harnais peut fonctionner sans environnement, et votre application peut suivre la progression en continu ou par webhook.

Commencez sans environnement

Un agent qui répond à des questions ou qui accède à des services externes à l’aide d’outils peut se passer de ressources de calcul et de fichiers propres. Définissez environment.type sur none. L’extrait suivant montre comment configurer l’environnement. Pour créer une session, vous devez également spécifier un agent et fournir une entrée initiale.

12345{
  "environment": {
    "type": "none"
  }
}

Votre application envoie des données d’entrée à une session. Le harnais appelle le modèle, utilise les outils configurés et renvoie les résultats. OpenAI conserve la session pour que vous puissiez y poursuivre le travail ultérieurement.

Le harnais peut appeler directement des outils MCP distants. Pour les outils de type fonction, votre code reçoit chaque appel, exécute la fonction et en renvoie le résultat.

Sans environnement, l’agent n’a accès ni aux outils intégrés Bash et apply-patch, ni aux fichiers de l’espace de travail, ni aux serveurs MCP de l’exécuteur.

L’environnement d’exécution virtuel facultatif illustré ici donne accès à des fichiers et à des commandes shell via les outils de type fonction de votre application.

Ajoutez un environnement hébergé par OpenAI

Lorsque l’agent doit exécuter des scripts, modifier des fichiers ou créer des artefacts, définissez environment.type sur openai_hosted. OpenAI crée et gère un bac à sable pour la session.

Vous configurez les paquets, les fichiers et les accès réseau dont l’agent a besoin. Le harnais exécute les commandes directement dans le bac à sable. Votre application continue d’envoyer les tâches, de recevoir les événements et de traiter les appels aux éventuels outils de type fonction.

La flèche en pointillés s’applique uniquement lorsque vous gérez vous-même l’environnement, comme indiqué dans la section suivante.

Pour connaître les options de configuration, consultez la page Environnements hébergés par OpenAI.

Connectez votre propre environnement

Utilisez environment.type: "self_hosted" lorsque l’agent a besoin de votre infrastructure, de votre réseau privé ou de logiciels personnalisés.

Votre code démarre l’environnement et connecte un exécuteur à la session. L’exécuteur lance les commandes et les outils à la demande du harnais. Votre application gère la connexion et le cycle de vie de l’environnement sans avoir à relayer chaque commande.

Vous gérez la mise à disposition des ressources, la reconnexion, l’arrêt et la conservation des fichiers dont vous aurez besoin. Votre serveur d’application ou un gestionnaire de webhooks peut se charger de ces opérations.

Avant d’arrêter les ressources de calcul, coordonnez la prise en charge des nouvelles tâches et vérifiez qu’aucune exécution n’est en attente.

Pour connaître les conditions de mise en place et d’arrêt, consultez les pages Connexion d’un bac à sable et Cycle de vie du bac à sable.

Suivez la progression et recevez les résultats

Quelle que soit la configuration choisie, vous pouvez utiliser l’un des mécanismes suivants ou combiner les deux.

• Diffusion en continu : recevez des événements détaillés à mesure que l’agent travaille, par exemple les données de sortie à afficher dans votre produit.
• Webhooks : recevez les changements d’état de la session sans avoir à maintenir un flux ouvert. Votre gestionnaire peut récupérer les résultats, exécuter des outils de type fonction ou gérer un environnement auto-hébergé.

Les outils de type fonction nécessitent un gestionnaire qui reçoit les appels et renvoie les résultats. Si ce gestionnaire est indisponible, l’agent peut rester en attente d’un résultat. Une défaillance des gestionnaires d’événements ou de cycle de vie peut également interrompre le suivi de la progression ou la gestion de l’environnement.

Pour en savoir plus sur l’intégration, consultez les pages Événements de session et Webhooks.