Pasar al contenido principal
OpenAI

23 de enero de 2026

Ingeniería

Desenrollar el bucle del agente Codex

Por Michael Bolin, miembro del personal técnico

Cargando...

Codex CLI⁠(se abre en una nueva ventana) es nuestro agente de software local multiplataforma, diseñado para realizar cambios de software de alta calidad y confiables, operando de manera segura y eficiente en tu máquina. Hemos aprendido muchísimo sobre cómo desarrollar un agente de software de clase mundial desde que lanzamos por primera vez el CLI en abril⁠. Para desglosar esas ideas, esta es la primera publicación de una serie continua en la que exploraremos varios aspectos de cómo funciona Codex, así como lecciones aprendidas con esfuerzo. (Para una vista aún más detallada de cómo se construye la CLI de Codex, visita nuestro repositorio de código abierto en https://github.com/openai/codex⁠(se abre en una nueva ventana). Muchos de los detalles más sutiles de nuestras decisiones de diseño están documentados en Pull requests e incidencias de GitHub si deseas obtener más información).

Para comenzar, nos enfocaremos en el ciclo del agente, que es la lógica central en Codex CLI encargada de orquestar la interacción entre el usuario, el modelo y las herramientas que el modelo invoca para llevar a cabo un trabajo de software significativo. Esperamos que esta publicación te ofrezca una buena perspectiva del papel que desempeña nuestro agente (o “harness”) al utilizar un LLM.

Antes de profundizar, una nota rápida sobre la terminología: en OpenAI, “Codex” abarca una serie de ofertas de agentes de software, incluyendo Codex CLI, Codex Cloud y la extensión Codex para VS Code. Esta publicación se centra en el harness de Codex, que proporciona el bucle principal del agente y la lógica de ejecución que subyace a todas las experiencias de Codex y se presenta a través de la CLI de Codex. Para facilitar aquí, usaremos los términos “Codex” y “Codex CLI” de manera intercambiable.

El ciclo del agente

En el corazón de cada agente de IA hay algo llamado "el bucle del agente". Una ilustración simplificada del ciclo del agente se ve así:

Diagrama titulado “Bucle del agente” que ilustra cómo un sistema de IA procesa una solicitud del usuario, llama a herramientas, observa los resultados, actualiza su plan y devuelve los resultados. Las flechas conectan pasos como la entrada del usuario, el razonamiento del modelo, las acciones de las herramientas y la respuesta final.

Para empezar, el agente recibe input del usuario para incluirlo en el conjunto de instrucciones textuales que prepara para el modelo, conocido como un prompt.

El siguiente paso es consultar al modelo enviándole nuestras instrucciones y pidiéndole que genere una respuesta, un proceso conocido como inferencia. Durante la inferencia, el prompt de texto se traduce primero en una secuencia de tokens⁠(se abre en una nueva ventana)de entrada: enteros que indexan en el vocabulario del modelo. Luego se utilizan estos tokens para muestrear el modelo, produciendo una nueva secuencia de tokens de salida.

Los tokens de salida se convierten nuevamente en texto, lo que se transforma en la respuesta del modelo. Debido a que los tokens se generan de manera incremental, esta traducción puede realizarse mientras el modelo se ejecuta, por lo que muchas aplicaciones basadas en LLM muestran resultados en tiempo real. En la práctica, la inferencia generalmente se encapsula detrás de una API que opera sobre texto, ocultando los detalles de la tokenización.

Como resultado del paso de inferencia, el modelo (1) produce una respuesta final a la entrada original del usuario, o (2) solicita una llamada a herramienta que se espera que el agente realice (por ejemplo, “ejecuta ls e informa el resultado”). En el caso de (2), el agente ejecuta la llamada a la herramienta y añade su salida al prompt original. Esta salida se utiliza para generar una nueva entrada que se emplea para volver a consultar el modelo; el agente puede entonces considerar esta nueva información e intentarlo nuevamente.

Este proceso se repite hasta que el modelo deja de emitir llamadas a herramientas y, en su lugar, produce un mensaje para el usuario (denominado mensaje de asistente en los modelos de OpenAI). En muchos casos, este mensaje responde directamente a la solicitud original del usuario, pero también puede ser una pregunta de seguimiento para ti.

Dado que el agente puede ejecutar llamadas a herramientas que modifican el entorno local, su “resultado” no se limita al mensaje del asistente. En muchos casos, la salida principal de un agente de software es el código que escribe o edita en tu computadora. Sin embargo, cada turno siempre termina con un mensaje del asistente, como “He agregado el architecture.md que pediste”, que indica un estado de finalización en el ciclo del agente. Desde la perspectiva del agente, su trabajo está completo y el control regresa al usuario.

El recorrido desde la entrada del usuario hasta la respuesta del agente que se muestra en el diagrama se denomina un turno de una conversación (un hilo en Codex). Aunque este turno de conversación puede incluir muchas iteraciones entre la inferencia del modelo y las llamadas a las herramientas. Cada vez que envías un mensaje nuevo a una conversación existente, el historial de la conversación se incluye como parte del prompt para el nuevo turno, que abarca los mensajes y las llamadas a herramientas de turnos anteriores:

Diagrama titulado “Bucle de agente de múltiples turnos” que muestra cómo un agente de IA toma iterativamente la entrada del usuario, genera acciones, consulta herramientas, actualiza el estado y devuelve resultados. Incluye pasos etiquetados, flechas y ejemplos de salidas de herramientas que ilustran el ciclo de razonamiento del agente.

Esto significa que a medida que la conversación crece, también aumenta la longitud del prompt utilizado para muestrear el modelo. Esta longitud importa porque cada modelo tiene una ventana de contexto, que es la cantidad máxima de tokens que puede utilizar en una llamada de inferencia. Ten en cuenta que esta ventana incluye tanto tokens de entrada como tokens de salida. Como te puedes imaginar, un agente podría decidir realizar cientos de llamadas a herramientas en un solo turno, lo que podría agotar la ventana de contexto. Por esta razón, la gestión de la ventana de contexto es una de las muchas responsabilidades del agente. Ahora, vamos a sumergirnos para ver cómo Codex ejecuta el ciclo del agente.

Inferencia de modelo

El Codex CLI envía solicitudes HTTP a la API de Responses⁠(se abre en una nueva ventana) para ejecutar la inferencia del modelo. Examinaremos cómo fluye la información a través de Codex, que utiliza la API de Respuestas para impulsar el ciclo del agente.

El punto de acceso de la API de Responses que utiliza Codex CLI es configurable⁠(se abre en una nueva ventana), por lo que se puede usar con cualquier punto de acceso que implemente la API de Responses⁠(se abre en una nueva ventana):

Exploremos cómo Codex crea el prompt para la primera llamada de inferencia en una conversación.

Construyendo el prompt inicial

Como usuario final, no especificas el prompt utilizado para muestrear el modelo textualmente cuando consultas la API de Responses. En su lugar, especificas varios tipos de entrada como parte de tu consulta, y el servidor de la API de Responses decide cómo estructurar esta información en un prompt que el modelo está diseñado para consumir. Puedes pensar en el prompt como una “lista de elementos”; esta sección explicará cómo tu consulta se transforma en esa lista.

En el prompt inicial, cada elemento de la lista está asociado a un rol. El role indica el peso que debe tener el contenido asociado y es uno de los siguientes valores (en orden decreciente de prioridad): system, developer, user, assistant.

La API de respuestas⁠(se abre en una nueva ventana) acepta una carga útil JSON con muchos parámetros. Nos enfocaremos en estos tres:

En Codex, el campo instructions se lee desde el model_instructions_file⁠(se abre en una nueva ventana) en ~/.codex/config.toml, si está especificado; de lo contrario, se utilizan las base_instructions asociadas con un modelo⁠(se abre en una nueva ventana). Las instrucciones específicas del modelo están en el repositorio de Codex y se integran en el CLI (por ejemplo, gpt-5.2-codex_prompt.md⁠(se abre en una nueva ventana)).

El campo tools es una lista de definiciones de herramientas que se ajustan a un esquema definido por la API de Responses. Para Codex, esto incluye herramientas proporcionadas por el CLI de Codex, herramientas proporcionadas por la API de Respuestas que deberían estar disponibles para Codex, así como herramientas proporcionadas por el usuario, generalmente a través de servidores MCP:

JavaScript

1
[
2
  // Codex's default shell tool for spawning new processes locally.
3
  {
4
    "type": "function",
5
    "name": "shell",
6
    "description": "Runs a shell command and returns its output...",
7
    "strict": false,
8
    "parameters": {
9
      "type": "object",
10
      "properties": {
11
        "command": {"type": "array", "description": "The command to execute", ...},
12
        "workdir": {"description": "The working directory...", ...},
13
        "timeout_ms": {"description": "The timeout for the command...", ...},
14
        ...
15
      },
16
      "required": ["command"],
17
    }
18
  }
19

20
  // Codex's built-in plan tool.
21
  {
22
    "type": "function",
23
    "name": "update_plan",
24
    "description": "Updates the task plan...",
25
    "strict": false,
26
    "parameters": {
27
      "type": "object",
28
      "properties": {"plan":..., "explanation":...},
29
      "required": ["plan"]
30
    }
31
  },
32

33
  // Web search tool provided by the Responses API.
34
  {
35
    "type": "web_search",
36
    "external_web_access": false
37
  },
38

39
  // MCP server for getting weather as configured in the
40
  // user's ~/.codex/config.toml.
41
  {
42
    "type": "function",
43
    "name": "mcp__weather__get-forecast",
44
    "description": "Get weather alerts for a US state",
45
    "strict": false,
46
    "parameters": {
47
      "type": "object",
48
      "properties": {"latitude": {...}, "longitude": {...}},
49
      "required": ["latitude", "longitude"]
50
    }
51
  }
52
]

Finalmente, el campo input del payload JSON es una lista de elementos. Codex inserta los siguientes elementos⁠(se abre en una nueva ventana) en el input antes de agregar el mensaje del usuario:

1. Un mensaje con role=developer que describe el entorno de pruebas que se aplica solo a la herramienta shell proporcionada por Codex definida en la sección tools. Es decir, otras herramientas, como las proporcionadas por servidores MCP, no están aisladas por Codex y son responsables de implementar sus propias medidas de seguridad.

El mensaje se construye a partir de una plantilla donde las piezas clave de contenido provienen de fragmentos de Markdown integrados en el Codex CLI, como workspace_write.md⁠(se abre en una nueva ventana) y on_request.md⁠(se abre en una nueva ventana):

Texto plano

1
<permissions instructions>
2
  - description of the sandbox explaining file permissions and network access
3
  - instructions for when to ask the user for permissions to run a shell command
4
  - list of folders writable by Codex, if any
5
</permissions instructions>

2. (Opcional) Un mensaje con role=developer cuyos contenidos son el valor de developer_instructions leído del archivo config.toml del usuario.

3. (Opcional) Un mensaje con role=user cuyo contenido son las “instrucciones del usuario”, que no provienen de un solo archivo, sino que se agregan de múltiples fuentes⁠(se abre en una nueva ventana). En general, las instrucciones más específicas se presentan más adelante:

4. Un mensaje con role=user que describe el entorno local en el que el agente está operando en este momento. Esto especifica el directorio de trabajo actual y el intérprete de comandos del usuario⁠(se abre en una nueva ventana):

Texto plano

1
<environment_context>
2
  <cwd>/Users/mbolin/code/codex5</cwd>
3
  <shell>zsh</shell>
4
</environment_context>

Una vez que Codex ha realizado todos los cálculos mencionados para inicializar el input, añade el mensaje del usuario para comenzar la conversación.

Los ejemplos anteriores se centraron en el contenido de cada mensaje, pero ten en cuenta que cada elemento de input es un objeto JSON con type, role⁠(se abre en una nueva ventana) y content como se muestra a continuación:

JSON

1
{
2
  "type": "message",
3
  "role": "user",
4
  "content": [
5
    {
6
      "type": "input_text",
7
      "text": "Add an architecture diagram to the README.md"
8
    }
9
  ]
10
}

Una vez que Codex construye la carga útil JSON completa para enviar a la API de Respuestas, realiza la solicitud HTTP POST con un encabezado Authorization según cómo esté configurado el punto de acceso de la API de Respuestas en ~/.codex/config.toml (se añaden encabezados HTTP adicionales y parámetros de consulta si se especifican).

Cuando un servidor de la API de Responses de OpenAI recibe la solicitud, utiliza el JSON para derivar el prompt para el modelo de la siguiente manera (para estar seguro, una implementación personalizada de la API de Responses podría tomar una decisión diferente):

Diagrama de instantánea que muestra un solo paso en el ciclo de un agente de IA. Una solicitud de usuario ingresa al modelo, que genera un pensamiento, una acción con el nombre de una herramienta y una entrada para la herramienta. El diagrama destaca este paso intermedio de razonamiento antes de que se active la herramienta.

Como puedes ver, el orden de los primeros tres elementos en el prompt lo determina el servidor, no el cliente. Dicho esto, de esos tres elementos, solo el contenido del mensaje del sistema también está controlado por el servidor, ya que las tools y las instructions son determinadas por el cliente. A estos les sigue el input del payload JSON para completar el prompt.

Ahora que tenemos nuestro prompt, estamos listos para probar el modelo.

El primer giro

Esta solicitud HTTP a la API de Responses inicia el primer “turno” de una conversación en Codex. El servidor responde con un flujo de eventos enviados por el servidor (SSE⁠(se abre en una nueva ventana)). Los datos de cada evento son una carga útil JSON con un "tipo" que comienza con "response", que podría ser algo como esto (una lista completa de eventos se puede encontrar en nuestra documentación de la API⁠(se abre en una nueva ventana)):

Texto plano

1
data: {"type":"response.reasoning_summary_text.delta","delta":"ah ", ...}
2
data: {"type":"response.reasoning_summary_text.delta","delta":"ha!", ...}
3
data: {"type":"response.reasoning_summary_text.done", "item_id":...}
4
data: {"type":"response.output_item.added", "item":{...}}
5
data: {"type":"response.output_text.delta", "delta":"forty-", ...}
6
data: {"type":"response.output_text.delta", "delta":"two!", ...}
7
data: {"type":"response.completed","response":{...}}

Codex consume el flujo de eventos⁠(se abre en una nueva ventana) y los republica como objetos de eventos internos que un cliente puede utilizar. Eventos como response.output_text.delta se utilizan para admitir la transmisión en la interfaz de usuario, mientras que otros eventos como response.output_item.added se convierten en objetos que se añaden al input para llamadas posteriores a la API de Respuestas.

Supongamos que la primera solicitud a la API de Responses incluya dos eventos response.output_item.done: uno con type=reasoning y otro con type=function_call. Estos eventos deben representarse en el campo input del JSON cuando volvamos a consultar el modelo con la respuesta a la llamada de la herramienta: 

JavaScript

1
[
2
  /* ... original 5 items from the input array ... */
3
  {
4
    "type": "reasoning",
5
    "summary": [
6
      "type": "summary_text",
7
      "text": "**Adding an architecture diagram for README.md**\n\nI need to..."
8
    ],
9
    "encrypted_content": "gAAAAABpaDWNMxMeLw..."
10
  },
11
  {
12
    "type": "function_call",
13
    "name": "shell",
14
    "arguments": "{\"command\":\"cat README.md\",\"workdir\":\"/Users/mbolin/code/codex5\"}",
15
    "call_id": "call_8675309..."
16
  },
17
  {
18
    "type": "function_call_output",
19
    "call_id": "call_8675309...",
20
    "output": "<p align=\"center\"><code>npm i -g @openai/codex</code>..."
21
  }
22
]

El prompt resultante que se usa para muestrear el modelo como parte de la consulta siguiente se vería así:

Diagrama etiquetado “Snapshot 2” que muestra un agente de IA tras una llamada a una herramienta. El modelo recibe una observación de una herramienta y genera un nuevo pensamiento y una nueva acción. Las flechas conectan entradas, observaciones y salidas para mostrar cómo el agente repite su ciclo de razonamiento.

En particular, observa cómo el prompt anterior es un prefijo exacto del nuevo prompt. Esto es intencional, ya que hace que las solicitudes posteriores sean mucho más eficientes porque nos permite aprovechar el almacenamiento en caché de prompt (que discutiremos en la siguiente sección sobre rendimiento).

Al mirar hacia atrás en nuestro primer diagrama del ciclo del agente, vemos que podría haber muchas iteraciones entre la inferencia y la llamada a herramientas. El prompt puede seguir creciendo hasta que finalmente recibamos un mensaje del asistente, indicando el final del turno:

Texto plano

1
data: {"type":"response.output_text.done","text": "I added a diagram to explain...", ...}
2
data: {"type":"response.completed","response":{...}}

En la CLI de Codex, presentamos el mensaje del asistente al usuario y enfocamos el editor para indicarle que es su “turno” de continuar la conversación. Si el usuario responde, tanto el mensaje del asistente del turno anterior como el nuevo mensaje del usuario deben añadirse al input en la solicitud de la API de Respuestas para comenzar el nuevo turno:

JavaScript

1
[
2
  /* ... all items from the last Responses API request ... */
3
  {
4
    "type": "message",
5
    "role": "assistant",
6
    "content": [
7
      {
8
        "type": "output_text",
9
        "text": "I added a diagram to explain the client/server architecture."
10
      }
11
    ]
12
  },
13
  {
14
    "type": "message",
15
    "role": "user",
16
    "content": [
17
      {
18
        "type": "input_text",
19
        "text": "That's not bad, but the diagram is missing the bike shed."
20
      }
21
    ]
22
  }
23
]

Una vez más, porque estamos continuando una conversación, la longitud del input que enviamos a la API de respuestas sigue aumentando:

Diagrama etiquetado “Snapshot 3” que muestra la etapa final de un ciclo de un agente de IA. Después de recibir los resultados de la herramienta, el modelo genera una conclusión y una respuesta final que se devuelve al usuario. Las flechas muestran la transición desde el resultado de la herramienta hasta la respuesta finalizada.

Examinemos qué implica este prompt en constante crecimiento para el rendimiento.

Consideraciones sobre el rendimiento

Quizás te estés preguntando: “Espera, ¿no es el bucle del agente cuadrático en términos de la cantidad de JSON enviada a la API de respuestas a lo largo de la conversación?” Y tendrías razón. Aunque la API de Responses admite un parámetro opcional previous_response_id⁠(se abre en una nueva ventana) para mitigar este problema, Codex no lo utiliza actualmente, principalmente para mantener las solicitudes completamente sin estado y para admitir configuraciones de Retención Cero de Datos (ZDR).

Evitar previous_response_id simplifica las cosas para el proveedor de la API de Respuestas porque garantiza que cada solicitud sea sin estado. Esto también facilita el soporte a los clientes que han optado por Retención Cero de Datos (ZDR)⁠(se abre en una nueva ventana), ya que almacenar los datos necesarios para soportar previous_response_id estaría en conflicto con ZDR. Ten en cuenta que los clientes de ZDR no sacrifican la capacidad de beneficiarse de los mensajes de razonamiento propietarios de turnos anteriores, ya que el encrypted_content asociado se puede descifrar en el servidor. (OpenAI conserva la clave de descifrado de un cliente de Retención Cero de Datos (ZDR), pero no sus datos.) Consulta los Pull requests #642⁠(se abre en una nueva ventana) y #1641⁠(se abre en una nueva ventana) para los cambios relacionados en Codex para soportar ZDR.

En general, el costo de muestrear el modelo supera al costo del tráfico de red, convirtiendo al muestreo en el objetivo principal de nuestros esfuerzos de eficiencia. Por eso el almacenamiento en caché de prompt es tan importante, ya que nos permite reutilizar el cálculo de una llamada de inferencia anterior. Cuando obtenemos aciertos de caché, el muestreo del modelo es lineal en lugar de cuadrático. Nuestra documentación sobre el almacenamiento en caché de prompt ⁠(se abre en una nueva ventana)explica esto con más detalle:

Los aciertos de caché solo son posibles para coincidencias exactas de prefijo dentro de un prompt. Para aprovechar los beneficios del almacenamiento en caché, coloca el contenido estático, como instrucciones y ejemplos, al inicio de tu prompt, y coloca el contenido variable, como información específica del usuario, al final. Esto también se aplica a las imágenes y herramientas, que deben ser idénticas entre las solicitudes.

Con esto en mente, consideremos qué tipos de operaciones podrían causar un “fallo de caché” en Codex:

  • Cambiar las tools disponibles para el modelo en medio de la conversación.
  • Cambiar el modelo que es el objetivo de la solicitud de la API de Responses (en la práctica, esto cambia el tercer elemento del prompt original, ya que contiene instrucciones específicas del modelo).
  • Cambiar la configuración del entorno de pruebas, el modo de aprobación o el directorio de trabajo actual.

El equipo de Codex debe ser diligente al introducir nuevas funciones en el Codex CLI que podrían comprometer el almacenamiento en caché de los prompts. Por ejemplo, nuestro soporte inicial para las herramientas MCP introdujo un error en el que no enumeramos las herramientas en un orden consistente⁠(se abre en una nueva ventana), lo que causó fallos de caché. Ten en cuenta que las herramientas de MCP pueden ser especialmente complicadas porque los servidores MCP pueden cambiar la lista de herramientas que ofrecen al instante mediante una notificación notifications/tools/list_changed⁠(se abre en una nueva ventana). Atender esta notificación en medio de una conversación larga puede provocar un costoso fallo de caché.

Cuando es posible, gestionamos los cambios de configuración que ocurren a mitad de la conversación añadiendo un mensaje nuevo a input para reflejar el cambio, en lugar de modificar un mensaje anterior:

Hacemos todo lo posible para asegurar aciertos de caché para mejorar el rendimiento. Hay otro recurso clave que tenemos que gestionar: la ventana de contexto.

Nuestra estrategia general para evitar quedarnos sin ventana de contexto es compactar la conversación una vez que el número de tokens supere cierto umbral. Específicamente, sustituimos el input por una lista nueva y más reducida de elementos que represente la conversación, permitiendo al agente continuar con una comprensión de lo que ha ocurrido hasta el momento. Una implementación temprana de la compactación⁠(se abre en una nueva ventana) requería que el usuario invocara manualmente el comando /compact, que consultaría la API de Responses usando la conversación existente más instrucciones personalizadas para resumir⁠(se abre en una nueva ventana). Codex utilizó el mensaje del asistente resultante que contenía el resumen como el nuevo input⁠(se abre en una nueva ventana) para los turnos posteriores de la conversación.

Desde entonces, la API de Responses ha evolucionado para admitir un /responses/compact punto de acceso especial⁠(se abre en una nueva ventana) que realiza la compactación de manera más eficiente. Devuelve una lista de elementos⁠(se abre en una nueva ventana) que se puede usar en lugar del input anterior para continuar la conversación mientras se libera la ventana de contexto. Esta lista incluye un elemento especial type=compaction con un elemento opaco encrypted_content que preserva la comprensión latente del modelo sobre la conversación original. Ahora, Codex usa automáticamente este punto de acceso para compactar la conversación cuando se supera el auto_compact_limit⁠(se abre en una nueva ventana).

Próximamente

Hemos introducido el bucle de agentes de Codex y hemos recorrido cómo Codex crea y gestiona su contexto al consultar un modelo. A lo largo del camino, destacamos consideraciones prácticas y mejores prácticas que se aplican a cualquiera que esté construyendo un bucle de agente sobre la API de Responses.

Aunque el bucle del agente sienta las bases para Codex, es solo el principio. En próximas publicaciones, profundizaremos en la arquitectura de la CLI, exploraremos cómo se implementa el uso de herramientas y examinaremos más de cerca el modelo de sandboxing de Codex.

Autor

Michael Bolin

Agradecimientos

Agradecimientos especiales a todo el equipo que construyó el Codex CLI.

Sigue leyendo

Ver todos
Tax Agent > Art Card
Crear agentes fiscales auto-mejorables con Codex

Ingeniería

codex windows > art card
Crear un sandbox seguro y eficaz para habilitar Codex en Windows

Ingeniería

MRC 1_1
De dónde vinieron los goblins

Ingeniería