Utiliser le harness Codex : comment OpenAI a construit App Server

• Codex est proposé avec une architecture App Server standardisée et un protocole JSON-RPC afin de pouvoir être intégré dans ses propres produits
• Au départ centré sur un harness TUI orienté CLI, il a ensuite adopté le protocole JSON-RPC, permettant à plusieurs clients — IDE, web, applications locales — de partager la même boucle d’agent
• App Server est un processus de longue durée qui héberge la bibliothèque cœur de Codex et expose au client l’ensemble de l’expérience agent, notamment la gestion du cycle de vie des threads, la configuration/l’authentification et l’exécution des outils
• Trois primitives conversationnelles — item, turn et thread — permettent de structurer les interactions complexes de la boucle d’agent et de créer des interfaces riches
• Le même harness est réutilisé sur divers environnements comme VS Code, JetBrains, Xcode, l’application desktop et le runtime web, avec prise en charge de bindings clients multilingues en Go, Python, TypeScript, Swift et Kotlin
• D’autres modes d’intégration existent, comme le serveur MCP, le mode CLI et le SDK TypeScript, mais App Server s’est imposé comme le standard d’intégration prioritaire
• OpenAI maintient App Server comme voie principale d’intégration de Codex et permet à chacun d’intégrer Codex à ses propres workflows via le dépôt open source du CLI

---

Contexte de base d’App Server

• Au départ, c’était une manière pragmatique de réutiliser le harness Codex dans plusieurs produits, avant d’évoluer progressivement vers un protocole standard
• Codex CLI a commencé comme une TUI (interface utilisateur en terminal), et lors de la création de l’extension VS Code, il fallait un moyen d’exécuter le même harness dans l’interface d’un IDE
  • Il fallait prendre en charge des interactions allant au-delà du simple schéma requête/réponse, comme l’exploration du workspace, le streaming de la progression du raisonnement ou l’affichage de diffs
• Une première tentative consistait à exposer Codex comme serveur MCP, mais il était difficile de conserver les sémantiques MCP d’une manière adaptée à VS Code
• En alternative, un protocole JSON-RPC reflétant la boucle TUI a été introduit, devenant la première version officieuse d’App Server
  • À l’époque, il n’avait pas été conçu comme une API stable, car on n’anticipait pas que d’autres clients en dépendraient
• À mesure que l’adoption de Codex s’est élargie, les équipes internes comme les partenaires externes (JetBrains, Xcode, etc.) ont demandé la possibilité d’embarquer le harness dans leurs propres produits
  • Il fallait donc concevoir une surface de plateforme permettant de faire évoluer le protocole tout en préservant la compatibilité ascendante

Structure interne du harness Codex

• Le cœur de Codex est à la fois une bibliothèque contenant tout le code agent et un runtime qui exécute la boucle d’agent et gère la persistance d’un thread Codex (conversation)
• En plus de la boucle d’agent principale, on y trouve trois grandes zones fonctionnelles :
  • Cycle de vie et persistance des threads : création, reprise, fork et archivage des threads, avec conservation de l’historique des événements afin que les clients puissent se reconnecter et restituer une timeline cohérente
  • Configuration et authentification : chargement de la configuration, gestion des valeurs par défaut, de l’état des identifiants et exécution de flux d’authentification comme « Se connecter avec ChatGPT »
  • Exécution et extension des outils : exécution d’outils shell/fichier dans un sandbox, connexion d’intégrations comme les serveurs MCP et les skills afin qu’ils participent à la boucle d’agent sous un modèle de politiques cohérent

Architecture d’App Server

• App Server est à la fois un protocole JSON-RPC entre client et serveur et un processus de longue durée qui héberge les threads du cœur de Codex
• Quatre composants principaux :
  • Lecteur stdio : lit les entrées du client
  • Processeur de messages Codex : communique directement avec chaque session du cœur pour soumettre les requêtes client et recevoir les mises à jour
  • Gestionnaire de threads : démarre une session du cœur pour chaque thread
  • Thread du cœur : exécute la boucle d’agent proprement dite
• Une seule requête client peut produire de nombreuses mises à jour d’événements, et ces événements détaillés permettent de concevoir des interfaces riches
• Le lecteur stdio et le processeur de messages Codex jouent un rôle de couche de traduction, transformant les requêtes JSON-RPC du client en opérations du cœur de Codex, puis le flux d’événements internes en notifications JSON-RPC stables et exploitables par l’UI
• Le protocole JSON-RPC entre le client et App Server est pleinement bidirectionnel
  • Quand l’agent a besoin d’une entrée, par exemple une approbation, le serveur peut initier une requête et suspendre le turn jusqu’à la réponse du client

Primitives conversationnelles

• Le point clé dans la conception d’une API pour une boucle d’agent est que l’interaction entre l’utilisateur et l’agent ne se résume pas à une simple requête/réponse, mais se déploie comme une suite structurée d’opérations
• Trois primitives essentielles :

• Item

  • Unité de base des entrées/sorties dans Codex
  • Typé : message utilisateur, message agent, exécution d’outil, demande d’approbation, diff, etc.
  • Cycle de vie explicite : item/started → item/*/delta optionnel (streaming) → item/completed (payload final)
  • Le client peut commencer à afficher dès started, diffuser les mises à jour progressivement via delta, puis finaliser avec completed

• Turn

  • Une unité de travail de l’agent déclenchée par une entrée utilisateur
  • Exemple : lorsqu’un client soumet « run tests and summarize failures », le turn commence, puis se termine quand l’agent a fini de produire sa sortie
  • Un turn contient une série d’items représentant les étapes intermédiaires et les résultats

• Thread

  • Conteneur persistant d’une session Codex en cours entre l’utilisateur et l’agent
  • Peut contenir plusieurs turns, et être créé, repris, forké ou archivé
  • L’historique du thread est conservé de manière persistante, permettant aux clients de se reconnecter et de restituer une timeline cohérente

Flux de conversation client-serveur

• Au début d’une conversation, le client et le serveur doivent établir un handshake initialize
  • Le client envoie une unique requête initialize avant toute autre méthode, et le serveur la confirme par une réponse
  • Les deux parties s’accordent sur la gestion des versions du protocole, les feature flags et les valeurs par défaut
• Lors d’une nouvelle requête, le serveur crée un thread puis un turn, et envoie les notifications thread/started et turn/started
• Les appels d’outils sont eux aussi transmis au client comme des items, et le serveur peut demander l’autorisation d’exécuter l’action
  • En cas de demande d’approbation, le turn est suspendu jusqu’à ce que le client réponde « autoriser » ou « refuser »
• Le serveur envoie ensuite le message de l’agent et termine le turn avec turn/completed
  • Les événements delta du message agent diffusent des morceaux du message, puis item/completed apporte la finalisation
• Pour voir le JSON complet d’un turn, il est possible d’exécuter la commande codex debug app-server send-message-v2 "run tests and summarize failures"

Schémas d’intégration côté client

• Applications locales et IDE

  • Le transport se fait via JSON-RPC sur stdio (JSONL)
  • Les clients locaux embarquent ou récupèrent un binaire App Server spécifique à leur plateforme, puis l’exécutent comme sous-processus de longue durée
  • Dans l’extension VS Code et l’application desktop, les artefacts de déploiement incluent des binaires Codex spécifiques à chaque plateforme, figés sur des versions validées en test
  • Des clients App Server ont déjà été implémentés dans plusieurs langages, dont Go, Python, TypeScript, Swift et Kotlin
    • TypeScript : génération directe des définitions avec la commande codex app-server generate-ts
    • Autres langages : génération d’un bundle de schémas JSON via codex app-server generate-json-schema, puis alimentation d’un générateur de code
  • Des partenaires comme Xcode peuvent dissocier leur cycle de release en maintenant un client stable pointant vers le binaire App Server le plus récent
    • Cela permet de déployer des améliorations côté serveur (meilleure compaction automatique, nouvelles clés de configuration, etc.) et des correctifs sans attendre une release client
    • La surface JSON-RPC restant compatible avec les versions précédentes, des clients plus anciens peuvent dialoguer en toute sécurité avec des serveurs plus récents

• Runtime web Codex

  • S’exécute dans un environnement conteneurisé
  • Des workers provisionnent des conteneurs avec un workspace checkouté, y lancent le binaire App Server et maintiennent le canal JSON-RPC via stdio
  • L’application web (navigateur utilisateur) communique avec le backend Codex via HTTP et SSE pour streamer les événements de tâche
  • Cela permet de garder une UI côté navigateur légère tout en offrant un runtime cohérent entre desktop et web
  • Les sessions web étant éphémères (onglet fermé, coupure réseau), l’état et la progression sont conservés côté serveur
    • Même si l’onglet disparaît, la tâche continue, et une nouvelle session peut facilement se reconnecter pour reprendre là où elle s’était arrêtée

• Plan de refactorisation de la TUI

  • La TUI actuelle est un client « natif » exécuté dans le même processus que la boucle d’agent, et communique directement avec les types du cœur Rust plutôt que via le protocole App Server
  • Il est prévu de la refactoriser pour qu’elle fonctionne comme les autres clients, en utilisant App Server
    • Elle pourrait alors se connecter à un serveur Codex tournant sur une machine distante
    • L’agent resterait étroitement lié à l’infrastructure de calcul, et continuerait à travailler même si le laptop passe en veille ou perd la connexion
    • Tout en conservant localement les mises à jour en direct et les capacités de contrôle

Choisir le bon protocole

• App Server est le mode d’intégration prioritaire, mais des alternatives plus limitées existent

• Serveur MCP

  • Exécuter codex mcp-server puis s’y connecter depuis n’importe quel client MCP prenant en charge un serveur stdio (par exemple OpenAI Agents SDK)
  • Pertinent si l’on dispose déjà d’un workflow fondé sur MCP et que l’on souhaite utiliser Codex comme outil appelable
  • Inconvénient : on ne peut utiliser que ce que MCP expose, et des interactions propres à Codex comme les mises à jour de diff peuvent ne pas se mapper proprement

• Interface portable

  • Pertinente lorsqu’il faut une abstraction unique visant plusieurs fournisseurs de modèles et runtimes
  • Inconvénient : elle tend à converger vers le plus petit sous-ensemble commun de fonctionnalités, ce qui peut compliquer l’expression d’interactions riches
  • Ce domaine évolue rapidement, et davantage de standards communs devraient émerger (ex. : agentskills.io)

• App Server

  • Expose l’intégralité du harness Codex via un flux d’événements stable et adapté aux interfaces utilisateur
  • En plus de toutes les fonctions de la boucle d’agent, il donne accès à des fonctions de support comme la connexion avec ChatGPT, l’exploration des modèles ou la gestion de configuration
  • Coût principal : il faut construire des bindings JSON-RPC côté client dans le langage utilisé
    • En fournissant schémas JSON et documentation, Codex peut prendre en charge une grande partie du travail complexe, ce qui a permis à de nombreuses équipes d’intégrer rapidement la solution

• Mode CLI

  • Mode léger de type script pour les tâches ponctuelles et les exécutions CI
  • Exécute une commande unique de façon non interactive, streame une sortie structurée et se termine avec un signal clair de succès ou d’échec
  • Bien adapté à l’automatisation et aux pipelines

• SDK TypeScript

  • Bibliothèque TypeScript permettant de piloter programmatiquement un agent Codex local dans sa propre application
  • Pertinente lorsqu’on a besoin d’une interface de bibliothèque native sans construire un client JSON-RPC séparé
  • Lancée avant App Server, elle prend en charge moins de langages et couvre un périmètre plus étroit
  • Il existe la possibilité de proposer d’autres SDK encapsulant le protocole App Server selon l’intérêt des développeurs

Prochaines étapes

• App Server expose le cœur de Codex, permet aux clients de piloter la boucle d’agent complète et prend en charge une large variété d’environnements, dont la TUI, les intégrations IDE locales et le runtime web
• L’ensemble du code source est publié dans le dépôt open source de Codex CLI
• Les demandes de fonctionnalités et les retours sont bienvenus, et des améliorations continues sont prévues pour rendre les agents plus faciles à utiliser

• Documentation officielle de Codex App Server