Análisis del funcionamiento interno de OpenAI Codex CLI: bucle de agente y estrategia de caché de prompts

Resumen:

• Estructura del bucle de agente (Agent Loop): se explica en detalle el proceso cíclico con el que Codex CLI coordina la entrada del usuario, la inferencia del modelo y la ejecución de herramientas para realizar tareas reales.
• Construcción del prompt y Responses API: se analiza el proceso mediante el cual las instrucciones del sistema, las definiciones de herramientas y el contexto del entorno local se convierten en una carga JSON de la Responses API, así como el flujo de datos.
• Optimización de rendimiento y gestión de estado: se abordan las estrategias para maximizar el caché de prompts (Prompt Caching), la técnica de compactación de conversaciones (Compaction) para superar los límites de la ventana de contexto y los principios de diseño sin estado (Stateless) para ZDR (Zero Data Retention).

Resumen detallado:
El equipo de ingeniería de OpenAI publicó un artículo técnico que analiza en profundidad el principio de funcionamiento del “bucle de agente” (Agent Loop), la lógica central de Codex CLI, un agente de software local. El texto describe, desde una perspectiva técnica, todo el ciclo de vida en el que recibe una instrucción del usuario, interactúa con el modelo, ejecuta herramientas y devuelve el resultado.

1. Bucle de agente (The Agent Loop)

El bucle de agente es una estructura cíclica que recibe la entrada del usuario e interactúa con el modelo hasta completar la tarea.

• Proceso: entrada del usuario -> generación del prompt -> inferencia del modelo -> (solicitud de llamada a herramienta -> ejecución de la herramienta -> adjuntar resultado -> nueva inferencia) repetición -> respuesta final.
• Turno (Turn): al proceso que va desde la entrada del usuario hasta que el modelo finalmente envía un mensaje al usuario (Assistant Message) se le llama un “turno”. En este proceso, el agente puede realizar cientos de llamadas a herramientas, por ejemplo ejecutar ls o editar archivos.

2. Inferencia del modelo y Responses API

Codex CLI se comunica con el modelo a través de la Responses API. Esta API puede configurarse para usar https://chatgpt.com/backend-api/codex/responses, https://api.openai.com/v1/responses o un host local como Ollama.

Construcción del prompt inicial (Building the Initial Prompt)

El prompt no es solo texto simple, sino datos estructurados compuestos por instructions, tools, input, etc.

• Instructions: mensajes del sistema o del desarrollador que definen las instrucciones de comportamiento del modelo. (Por ejemplo, consultar el archivo de configuración ~/.codex/config.toml)
• Tools: lista de definiciones de herramientas que el modelo puede usar. Incluye ejecución de shell, actualización de planes (update_plan), búsqueda web y herramientas de servidores MCP (Model Context Protocol) personalizados.
• Input: lista de datos reales que se envían al modelo. Aquí se incluyen la configuración de permisos del sandbox, instrucciones específicas del proyecto y el contexto del entorno (Environment Context), como el directorio de trabajo actual (cwd) y el tipo de shell.

Ejemplo de payload JSON:

{  
  "type": "message",  
  "role": "user",  
  "content": [  
    {  
      "type": "input_text",  
      "text": "Agrega un diagrama de arquitectura a README.md"  
    }  
  ]  
  // ... también se envían juntos el contexto del entorno y la configuración de permisos definidos anteriormente  
}  
  

3. Ejecución de herramientas y flujo de datos

Cuando el modelo solicita una llamada a herramienta (Function Call), el agente la ejecuta, agrega el resultado al historial de la conversación y vuelve a invocar al modelo.

Ejemplo de JSON de nueva solicitud tras ejecutar la herramienta:

[  
  /* ... elementos de entrada anteriores ... */  
  {  
    "type": "reasoning", // proceso de razonamiento del modelo (CoT)  
    "summary": [...],  
    "encrypted_content": "gAAAAABpaDW..." // contenido de razonamiento cifrado  
  },  
  {  
    "type": "function_call",  
    "name": "shell",  
    "arguments": "{\"command\":\"cat README.md\",\"workdir\":\"/Users/mbolin/code/codex5\"}",  
    "call_id": "call_8675309..."  
  },  
  {  
    "type": "function_call_output", // resultado de la ejecución de la herramienta  
    "call_id": "call_8675309...",  
    "output": "<p align=\"center\"><code>npm i -g @openai/codex</code>..."  
  }  
]  
  

Es importante construirlo de modo que el prompt anterior sea el prefijo exacto (Prefix) del nuevo prompt. Esto determina la eficiencia del caché de prompts que se describe más adelante.

4. Consideraciones de rendimiento: caché y ZDR

Cuanto más larga sea la conversación, el tamaño del prompt crece linealmente, lo que incrementa el costo y la latencia.

• Caché de prompts (Prompt Caching): los modelos de OpenAI reutilizan resultados de cómputo previos para acelerar el proceso cuando la parte inicial del prompt coincide (Prefix Match).

• Prevención de fallos de caché (Cache Miss): si durante la conversación cambian la lista de herramientas o la configuración del sandbox, el caché puede romperse. Para evitarlo, Codex maneja los cambios de configuración agregando nuevos mensajes (Append) en lugar de modificar mensajes existentes.

• Sin estado (Stateless) y ZDR: no se usan parámetros como previous_response_id; en su lugar, se envía el contexto completo en cada ocasión. Esto es para cumplir con la política de Zero Data Retention (ZDR), que evita almacenar datos en el servidor. Al recibir el cliente el contenido de razonamiento cifrado (encrypted_content) y reenviarlo luego al servidor, este puede restaurar el contexto de razonamiento previo sin guardar estado.

5. Gestión de la ventana de contexto (Compaction)

Para no superar el límite de tokens, Codex usa el endpoint /responses/compact para compactar el historial de la conversación. No devuelve un simple resumen, sino una lista de elementos compactados que incluye encrypted_content para preservar la comprensión latente del modelo, reemplazando así la entrada existente.

[iolothebard]

Claude Code estuvo en la documentación oficial desde el principio…

[iolothebard]

https://code.claude.com/docs/en/how-claude-code-works