Desarmando el bucle del agente de Codex

 (openai.com)
3 puntos por GN⁺ 2026-01-24 | 1 comentarios | Compartir por WhatsApp
  • Codex CLI está diseñado como un agente que realiza cambios de software de alta calidad de forma segura y eficiente en entornos locales
  • Su estructura central, el bucle del agente (agent loop), conecta de manera cíclica la entrada del usuario, la inferencia del modelo y las llamadas a herramientas para ejecutar tareas con sentido
  • En el proceso del bucle, la composición del prompt, la gestión de la ventana de contexto y el caché de prompts actúan como elementos clave para el rendimiento y la estabilidad
  • Codex se comunica con el modelo mediante la Responses API, y cada solicitud está compuesta por una carga JSON completa para mantener un funcionamiento sin estado (stateless)
  • Esta estructura permite funciones avanzadas como Zero Data Retention (ZDR), caché de prompts y compactación automática (compaction), y sienta la base para el diseño de agentes a gran escala

Resumen del bucle del agente de Codex

  • Codex CLI funciona en torno a una estructura de bucle que coordina la interacción entre usuario, modelo y herramientas
    • Recibe la entrada del usuario y construye el prompt que se enviará al modelo
    • Si el modelo genera una respuesta o solicita una llamada a herramienta (tool call), el agente la ejecuta y vuelve a agregar el resultado al prompt
    • Cuando el modelo deja de hacer llamadas a herramientas y genera un mensaje del assistant, termina un turno
  • Cada turno forma parte de una conversación, y los mensajes anteriores junto con el historial de llamadas a herramientas se incluyen en el prompt de la siguiente solicitud
  • Como la longitud del prompt está limitada por la ventana de contexto (context window) del modelo, Codex debe administrarla

Responses API y la estructura de comunicación de Codex

  • Codex CLI envía solicitudes HTTP a la Responses API para la inferencia del modelo
    • El endpoint de la API varía según la configuración, y puede usarse en entornos OpenAI, ChatGPT, Azure y locales (LM Studio, Ollama, etc.)
  • La solicitud a la API está compuesta por una carga JSON, cuyos campos principales son los siguientes
    • mensajes system/developer: establecen el contexto base del modelo
    • instructions: lista de herramientas que el modelo puede invocar
    • tools: definiciones de herramientas proporcionadas por Codex CLI, la Responses API y el usuario (servidores MCP, etc.)
    • input: lista de mensajes que incluye el historial de conversación e información del entorno
  • Codex lee la configuración de ~/.codex/config.toml y archivos como AGENTS.md y skills dentro del proyecto para insertar automáticamente instrucciones del usuario e información del entorno

Composición del prompt y manejo de eventos

  • Codex envía cada mensaje a la Responses API como un objeto JSON (type, role, content)
  • El servidor genera el prompt del modelo a partir de este JSON y devuelve la respuesta mediante un flujo SSE (Server-Sent Events)
    • El evento response.output_text.delta se usa para la salida en streaming
    • El evento response.output_item.added se agrega al input de la siguiente solicitud para mantener el bucle
  • Está diseñado para que el prompt anterior sea un prefijo exacto del nuevo prompt, lo que permite aprovechar el caché de prompts (prompt caching)

Optimización de rendimiento: caché y diseño sin estado

  • Codex no usa previous_response_id, por lo que mantiene una estructura de solicitudes completamente sin estado (stateless)
    • Esto permite dar soporte a clientes con Zero Data Retention (ZDR) y minimizar la retención de datos
  • El caché de prompts reutiliza el mismo prefijo para linealizar el costo de muestreo
    • Un acierto de caché solo ocurre cuando hay una coincidencia exacta del prefijo del prompt
    • Cambios en la lista de herramientas, el modelo, la configuración del sandbox o el directorio de trabajo provocan fallos de caché
  • Como los cambios dinámicos en herramientas MCP pueden causar pérdida de caché, Codex refleja esos cambios insertando mensajes nuevos

Gestión de la ventana de contexto y compactación automática (compaction)

  • Cuando la conversación se alarga, se realiza una compactación de la conversación (compaction) para evitar exceder la ventana de contexto
    • Al principio se hacía un resumen manual con el comando /compact, pero actualmente se usa automáticamente el endpoint /responses/compact de la Responses API
    • Este endpoint devuelve elementos de type=compaction y encrypted_content cifrado para mantener la comprensión del modelo
  • Cuando se supera auto_compact_limit, Codex ejecuta automáticamente la compactación para asegurar la continuidad de la conversación

Conclusión y dirección futura

  • El bucle del agente de Codex es una estructura central que integra inferencia del modelo, llamadas a herramientas, caché y gestión de contexto
  • Esta estructura hace posible un diseño de agentes de alto rendimiento, sin estado y centrado en la seguridad
  • En publicaciones posteriores se abordarán con más detalle la arquitectura de la CLI, la implementación del uso de herramientas y el modelo de sandboxing de Codex

Lecturas relacionadas

1 comentarios

 
GN⁺ 2026-01-24
Comentarios en Hacker News

  • Lo mejor de esta entrada de blog es que no tiene nada de sorprendente. Codex CLI es de código abierto, así que se puede revisar por dentro sin necesidad de hacer ingeniería inversa
    La comunicación de Eric Traut, un desarrollador conocido por Pyright, también es excelente. Participa activamente en issues y PR
    Repositorio de GitHub

    • Cuando el año pasado Codex CLI se publicó como open source, sí me sorprendió bastante. También incluye codex-rs, portado de TypeScript a Rust, así que es muy útil para cualquiera que quiera aprender cómo funciona un agente de programación
      Yo también contribuí algunas mejoras al CLI, y sigo de cerca los releases y PR para seguir aprendiendo
    • Parece que mucha gente no sabe que Claude Code es software privativo
    • Sinceramente, creo que la razón por la que Claude Code no es open source es porque la calidad del código es tan mala que les daría vergüenza mostrarla. Estoy pagando la suscripción de 200 dólares al mes, pero el CLI es lento y se rompe seguido, así que probablemente la cancele pronto
    • Me pregunto si Codex CLI es simplemente un frontend que llama lógica remota, o si puede funcionar completamente offline. También quisiera saber si ofrecen los pesos bajo licencia FLOW y si tienen documentado el proceso de build

  • Lo interesante es la parte donde la compactación se hace como un “mensaje cifrado que preserva la comprensión latente del modelo”
    Cuando Codex supera auto_compact_limit, usa automáticamente ese endpoint para reducir de forma eficiente el contexto de la conversación

    • El endpoint de compactación de Codex es de lo mejor de la industria. El de Claude está casi entre los peores
    • Me pregunto si el endpoint compactor se puede usar de forma independiente. Tenemos nuestro propio loop de agente para un dominio específico, y da la impresión de que el sistema de compactación de Codex rendiría mejor que el nuestro
    • También quisiera saber si esta función funciona con modelos que no sean de OpenAI

  • Algo que me sorprendió al revisar el interior de Codex es que los tokens de razonamiento se conservan dentro del loop de llamadas de herramientas del agente, pero se eliminan cada vez que cambia el turno del usuario
    Así que se puede mantener el contexto a lo largo de varios turnos, pero entre solicitudes relacionadas del usuario se puede perder parte del contexto
    Yo hago que el modelo vaya guardando el progreso, los planes o la info de depuración en archivos Markdown, para que funcionen como una especie de snapshot entre distintas ventanas de contexto

    • Depende de la ruta del API. En chat completions funciona como tú dices, pero en la API responses v1 es al revés. Los tokens de razonamiento se conservan incluso al enviar el siguiente mensaje. Eso sí, el modo xhigh consume contexto mucho más rápido
    • Quizá no conservar los tokens de razonamiento sea, de hecho, una buena decisión. Si no, se seguiría acumulando contexto invisible para el usuario, y eso puede generar un riesgo de desalineación entre lo que entiende el modelo y lo que entiende el usuario
    • Yo hice una Codex Reflect Skill que incorpora conversaciones pasadas y construye contexto con sesiones en paralelo
      Repositorio de GitHub
    • Guardar el registro junto con el código es cómodo, pero causa problemas en entornos de equipo o cuando se trabaja con varias ramas a la vez. Mi siguiente experimento será separar esos datos en un daemon con almacenamiento externo y acceder a ellos desde un cliente CLI
    • Yo uso mucho agent-shell de emacs, que guarda todo el historial de conversación. Gracias a eso puedo decir fácilmente “toma como referencia la conversación anterior”. Como quien deja el log no es el agente sino emacs, no tengo que preocuparme de que falte algo

  • Lo que de verdad quiero en Codex es una función de checkpoints estilo Copilot. Hay varios issues en GitHub al respecto (#2788, #3585), pero no parece ser prioridad del equipo

    • Gemini CLI ya tiene esa función
    • El equipo de Codex dice que define prioridades según la cantidad de upvotes con emoji en GitHub. Si hay una función que quieres, vale la pena votarla

  • Me pregunto cómo gestionan la retención de contexto al agregar instrucciones del usuario dentro del loop del agente, especialmente en conversaciones de varios turnos. También quisiera saber si han probado técnicas para ajustarlo dinámicamente cuando cambian los requisitos del usuario

  • Me gusta Codex, pero se siente más lento que la interfaz web de ChatGPT. Cuando quiero intercambiar ideas rápido, sigo siendo más productivo copiando y pegando en la web
    Codex a menudo empieza a modificar código que no viene al caso, así que el loop de retroalimentación se siente lento y frustrante. Aun así, cuando funciona bien, es excelente. Ojalá algún día llegue al punto de ser tan rápido como la web, pero permitiendo trabajo local

    • En la interfaz web de ChatGPT Plus no está disponible el modo de xhigh reasoning effort del modelo 5.2

  • No fue algo especialmente nuevo, pero igual fue una lectura valiosa. Ojalá en los CLI de programación agentiva fuera más fácil reflexionar sobre los loops o el historial. Probé usar MCP para consultar el historial del chat, pero es incómodo porque hay que indicarlo explícitamente. Tal vez el aprendizaje continuo pueda resolver este tipo de problemas

  • Este comportamiento también se puede observar con telemetría OTEL. Yo uso mucho codex exec en modo headless, pero la falta de soporte integrado de telemetría hace que depurarlo sea difícil
    Por eso hice yo mismo codex-plus. Replica la interfaz de codex exec, está implementado sobre el SDK de TypeScript y, después de cada ejecución, exporta los logs de la sesión a un recolector remoto de OpenTelemetry para poder analizarlos con codex-plus-log-viewer

  • La parte donde explican las skills se me hizo rara
    Enlace al código relacionado
    No entiendo por qué no exponen simplemente los archivos directamente, en vez de hacer que el modelo los solicite como si fueran archivos normales

    • Justamente esa es la clave de las skills. La idea es hacer que solo se abran los archivos relevantes, para reducir el uso de la ventana de contexto

  • Me preguntaba si alguien realmente ha usado Codex CLI en serio. Yo probé la extensión de Codex para VSCode, Gemini CLI y Claude Code CLI, y todos tenían un rendimiento pésimo.
    Pero el nuevo Codex CLI hecho en Rust es una locura en rendimiento. La UX también está muy bien lograda, hasta en detalles como los atajos de teclado. Theo dijo que deberían haberse enfocado en mejorar el modelo en vez de optimizar el CLI, pero después de usarlo no podría estar menos de acuerdo

    • Siento que Codex CLI es muchísimo mejor que Claude Code. Sigue las instrucciones con precisión y no hace cosas que uno no pidió. Con la suscripción de 20 dólares al mes se puede usar bastante el modelo 5.2 codex high. Yo trabajo con modelos SSL de bioacústica
    • OpenCode también es más rápido y más estable que otros CLI. Últimamente estoy usando más Codex, y probablemente cancele Claude Pro. Me gusta que OpenAI dé soporte oficial a OpenCode. Está bueno el momento actual, con varias opciones competitivas
    • Codex da resultados consistentes en más del 95% de las tareas de programación. Pero en tareas no estructuradas como conversación o escritura de historias a veces saca respuestas raras. Una vez se quedó atrapado en un loop durante un git rebase. Probé Aider, pero casi no me sirvió para nada
    • La eficiencia de memoria y CPU de Codex CLI es muy buena. Además, como es open source, uno puede revisar directamente cómo funciona. Lo que dijo Theo me sigue pareciendo una mala queja
    • El problema de Codex es que todavía no tiene soporte para hooks. Yo hice una herramienta que usa hooks para reducir en 30% el consumo de tokens del agente. A través de hooks se puede corregir en tiempo real el comportamiento ineficiente del agente
      Artículo relacionado: Scribe Swebench Benchmark