Décomposer la boucle agent de Codex

• Codex CLI est conçu comme un agent capable d’effectuer des modifications logicielles de haute qualité de manière sûre et efficace dans un environnement local
• Sa structure centrale, la boucle agent (agent loop), relie de façon cyclique l’entrée utilisateur, le raisonnement du modèle et les appels d’outils afin d’accomplir des tâches utiles
• Lors de cette boucle, la composition des prompts, la gestion de la fenêtre de contexte et le cache de prompts jouent un rôle clé pour les performances et la stabilité
• Codex communique avec le modèle via la Responses API ; chaque requête est constituée d’une charge utile JSON complète, ce qui maintient un fonctionnement sans état (stateless)
• Cette architecture permet des fonctionnalités avancées comme Zero Data Retention (ZDR), le cache de prompts et la compaction automatique, et sert de base à la conception d’agents à grande échelle

---

Vue d’ensemble de la boucle agent de Codex

• Codex CLI fonctionne autour d’une structure en boucle qui orchestre les interactions entre l’utilisateur, le modèle et les outils
  • il reçoit l’entrée de l’utilisateur et construit le prompt à transmettre au modèle
  • si le modèle génère une réponse ou demande un appel d’outil (tool call), l’agent l’exécute puis ajoute le résultat au prompt
  • lorsqu’aucun nouvel appel d’outil n’est demandé et que le modèle produit un message assistant, un tour se termine
• Chaque tour fait partie d’une conversation ; les messages précédents ainsi que l’historique des appels d’outils sont tous inclus dans le prompt de la requête suivante
• Comme la longueur du prompt est limitée par la fenêtre de contexte (context window) du modèle, Codex doit la gérer activement

Structure de communication entre Responses API et Codex

• Codex CLI envoie des requêtes HTTP à la Responses API pour l’inférence du modèle
  • le point d’accès API varie selon la configuration et peut être utilisé avec OpenAI, ChatGPT, Azure ou des environnements locaux (LM Studio, Ollama, etc.)
• Les requêtes API sont structurées sous forme de charge utile JSON, avec notamment les champs suivants
  • messages system/developer : définissent le contexte de base du modèle
  • instructions : liste des outils que le modèle peut appeler
  • tools : définitions des outils fournis par Codex CLI, la Responses API ou l’utilisateur (serveur MCP, etc.)
  • input : liste de messages incluant l’historique de la conversation et les informations d’environnement
• Codex lit automatiquement la configuration ~/.codex/config.toml ainsi que des fichiers tels que AGENTS.md et skills dans le projet afin d’injecter les consignes utilisateur et les informations d’environnement

Composition des prompts et traitement des événements

• Codex structure chaque message comme un objet JSON (type, role, content) puis l’envoie à la Responses API
• Le serveur génère ensuite le prompt du modèle à partir de ce JSON et renvoie la réponse sous forme de flux SSE (Server-Sent Events)
  • l’événement response.output_text.delta est utilisé pour la sortie en streaming
  • l’événement response.output_item.added est ajouté au champ input de la requête suivante afin de poursuivre la boucle
• Le système est conçu pour que l’ancien prompt soit un préfixe exact du nouveau, ce qui permet d’exploiter le cache de prompts (prompt caching)

Optimisation des performances : cache et architecture sans état

• Codex n’utilise pas previous_response_id, ce qui lui permet de conserver une structure de requêtes entièrement sans état (stateless)
  • cela rend possible la prise en charge des clients Zero Data Retention (ZDR) et une minimisation de la conservation des données
• Le cache de prompts réutilise le même préfixe pour linéariser le coût d’échantillonnage
  • un hit de cache ne se produit qu’en cas de correspondance exacte du préfixe du prompt
  • une modification de la liste d’outils, du modèle, des paramètres de sandbox ou du répertoire de travail provoque un cache miss
• Les changements dynamiques des outils MCP peuvent faire perdre le cache ; Codex reflète donc ces changements en insérant de nouveaux messages

Gestion de la fenêtre de contexte et compaction automatique

• Quand la conversation s’allonge, une compaction de la conversation est effectuée afin d’éviter de dépasser la fenêtre de contexte
  • au départ, un résumé manuel était réalisé via la commande /compact, mais aujourd’hui l’endpoint /responses/compact de la Responses API est utilisé automatiquement
  • cet endpoint renvoie des éléments de type=compaction ainsi qu’un encrypted_content chiffré afin de préserver la compréhension du modèle
• Codex exécute automatiquement la compaction dès que auto_compact_limit est dépassé, afin d’assurer la continuité de la conversation

Conclusion et orientations à venir

• La boucle agent de Codex constitue la structure centrale qui intègre inférence du modèle, appels d’outils, cache et gestion du contexte
• Cette architecture permet une conception d’agents performante, sans état et centrée sur la sécurité
• Les prochains articles aborderont plus en détail la structure interne de Codex, notamment l’architecture CLI, l’implémentation de l’usage des outils et le modèle de sandboxing