Codex explica su agent loop: cómo funciona el agente local | Keryc
Codex CLI es un agente de software que corre en tu máquina y se diseñó para producir cambios de código de forma fiable y segura. ¿Qué hace al corazón de ese agente? El llamado agent loop, la lógica que orquesta la conversación entre tú, el modelo y las herramientas que el modelo invoca para ejecutar trabajo real en tu entorno.
Qué es el "agent loop" de Codex
Piensa en el agent loop como una conversación con memoria y habilidades: tú das una instrucción, Codex prepara un prompt para el modelo, el modelo responde y a veces pide ejecutar una herramienta (por ejemplo, "ejecuta ls y muéstrame el resultado").
Si el modelo solicita una herramienta, el agente la ejecuta, añade la salida al prompt y vuelve a preguntar al modelo. Esto se repite hasta que el modelo emite un mensaje de asistente que normalmente indica que la tarea terminó, por ejemplo "Añadí el archivo architecture.md que pediste". Ese mensaje marca el final de un turno y te devuelve el control.
Cómo se arma el prompt y por qué importa
Cuando Codex llama a la Responses API no envías un único texto, sino una lista de elementos (input) con roles: system, developer, user, assistant. El orden y el contenido influyen en cómo el modelo prioriza la información.
Antes de tu mensaje, Codex agrega varios items importantes: instrucciones de desarrollo, contexto del entorno (directorio de trabajo, shell), y notas sobre el sandbox de la herramienta de shell que usa. También puede leer archivos como AGENTS.md o instrucciones locales para adaptar el comportamiento.
¿Por qué esto es relevante? Porque el prompt crece cada vez que continúa la conversación. Más contexto significa más tokens usados, y eso impacta en costos y límites técnicos.
Herramientas, sandbox y seguridad
Codex puede llamar herramientas locales o remotas (MCP servers). La herramienta de shell que incluye Codex se ejecuta en un sandbox descrito en el prompt. Otras herramientas deben gestionar sus propias guardias.
Esto permite que el agente no solo responda con texto sino que edite archivos, ejecute comandos y modifique el entorno local. Por eso la claridad sobre permisos y sandboxing es crucial: Codex inserta mensajes con formato controlado para indicar límites y acciones permitidas.
Cómo Codex interactúa con la Responses API
El CLI envía un POST a la Responses API y recibe eventos por Server-Sent Events (SSE). Mientras llegan response.output_text.delta el cliente puede mostrar streaming en la interfaz. Cuando llegan eventos como response.output_item.added o response.output_item.done esos resultados se reincorporan al input para la siguiente llamada.
Una decisión de diseño importante: Codex no usa previous_response_id por defecto para mantener los requests sin estado y soportar configuraciones Zero Data Retention (ZDR). Esto simplifica la privacidad, pero obliga a enviar de nuevo todo el historial en cada petición.
Rendimiento: prompt caching y ventana de contexto
¿Te preocupa que enviar todo el historial se vuelva lento o caro? La mayor parte del costo sigue siendo muestrear el modelo, pero el crecimiento del prompt puede hacer las cosas ineficientes. Aquí nacen dos mecanismos clave:
Prompt caching: si el nuevo prompt es exactamente un prefijo del anterior, el servidor puede reutilizar trabajo previo y evitar volver a procesar todas las partes estáticas. Por eso conviene poner contenido estático (instrucciones, ejemplos) al inicio y lo variable (entrada del usuario, salidas de herramientas) al final.
Ventana de contexto: cada modelo tiene un límite de tokens. Si una conversación crece demasiado, puedes quedarte sin contexto. Para evitarlo, Codex detecta cuando se supera un umbral y compacta la conversación.
Algunas acciones rompen el cache: cambiar las herramientas disponibles, cambiar el modelo o alterar configuraciones como el sandbox o el directorio de trabajo. Incluso un reordenamiento accidental de la lista de herramientas puede generar un cache miss, y el equipo de Codex lo ha enfrentado en el pasado.
Compactación: resumir para seguir funcionando
Antes había que ejecutar un comando manual /compact. Hoy la Responses API ofrece un endpoint responses/compact que devuelve una versión reducida del input, incluyendo un item de tipo compaction con contenido cifrado que preserva la comprensión latente del modelo.
Codex usa esto automáticamente cuando excede auto_compact_limit, lo que le permite seguir la conversación sin perder la "memoria" relevante ni consumir toda la ventana de contexto.
Qué debes sacar de esto
Si usas o vas a usar agentes locales como Codex CLI, hay tres lecciones prácticas:
Coloca instrucciones estáticas al inicio del prompt y lo variable al final para aprovechar el cache.
Atiende a las herramientas que habilitas: cambios en la lista de herramientas pueden afectar rendimiento.
Confía en la compactación automática para conversaciones largas, pero revisa permisos y sandbox si tu agente modifica archivos en tu máquina.
Codex no es solo una interfaz para pedirle cosas al modelo: es un motor que gestiona prompts, herramientas, privacidad y rendimiento mientras trabaja en tu entorno local. En próximas entregas, Codex promete detallar la arquitectura del CLI, la implementación de herramientas y el modelo de sandboxing.
