Desbloquear el entorno de Codex: cómo creamos App Server

El agente de programación de OpenAI, Codex, está disponible en varias plataformas: la aplicación web⁠(se abre en una nueva ventana), la CLI⁠(se abre en una nueva ventana), la extensión de Codex para el IDE⁠(se abre en una nueva ventana) y la nueva aplicación de Codex para macOS. En el fondo, todas funcionan con la misma estructura de Codex: el bucle de agentes y la lógica que subyace a todas las experiencias de Codex. ¿El vínculo crítico entre ellos? Codex App Server⁠(se abre en una nueva ventana), una API JSON-RPC¹ bidireccional y fácil de usar para el cliente.

En esta publicación, presentaremos Codex App Server; compartiremos lo que aprendimos hasta ahora sobre las mejores formas de incorporar las capacidades de Codex a tu producto para ayudar a tus usuarios a potenciar sus flujos de trabajo. Cubriremos la arquitectura y el protocolo de App Server y cómo se integra con diferentes superficies de Codex, así como consejos para aprovechar Codex, ya sea que quieras convertir a Codex en un revisor de código, un agente de SRE o un asistente de programación.

Antes de sumergirnos en la arquitectura, es útil conocer la historia de App Server. Inicialmente, App Server fue una manera práctica de reutilizar la estructura de Codex en los productos, que con el tiempo se convirtió en nuestro protocolo estándar.

La CLI de Codex comenzó como una TUI (interfaz de usuario de terminal), lo que significa que se accede a Codex a través de la terminal. Cuando creamos la extensión de VS Code (una forma más amigable para el IDE de interactuar con los agentes de Codex), necesitábamos una manera de usar el mismo marco para poder ejecutar el mismo bucle de agente desde una interfaz de usuario de IDE sin tener que reimplementarlo. Eso significó admitir patrones de interacción enriquecidos más allá de solicitud/respuesta, como explorar el espacio de trabajo, transmitir el progreso a medida que el agente razona y emitir diferencias. Primero probamos exponer Codex como servidor MCP⁠(se abre en una nueva ventana), pero mantener la semántica de MCP de una manera que tuviera sentido para VS Code resultó difícil. En su lugar, introdujimos un protocolo JSON-RPC que reflejaba el bucle de la TUI, lo que se convirtió en la primera versión no oficial⁠(se abre en una nueva ventana) de App Server. En ese momento, no esperábamos que otros clientes dependieran de App Server, por lo que no se diseñó como una API estable.

A medida que la adopción de Codex creció en los meses siguientes, los equipos internos y socios externos querían poder integrar el mismo sistema en sus productos para agilizar los flujos de trabajo de desarrollo de software de sus usuarios. Por ejemplo, JetBrains y Xcode querían una experiencia de agente de nivel IDE, mientras que la aplicación de escritorio de Codex necesitaba orquestar muchos agentes de Codex en paralelo. Esas demandas nos llevaron a diseñar una superficie de plataforma en la que tanto nuestros productos como las integraciones de socios pudieran depender de manera segura a lo largo del tiempo. Debía ser fácil de integrar y compatible con versiones anteriores, lo que significaba que podíamos evolucionar el protocolo sin afectar a los clientes existentes.

A continuación, te mostraremos cómo diseñamos la arquitectura y el protocolo para que diferentes clientes puedan utilizar la misma estructura.

Primero, vamos a examinar qué hay dentro de la estructura de Codex y cómo Codex App Server lo expone a los clientes. En nuestro último blog de Codex, desglosamos el ciclo central del agente que coordina la interacción entre el usuario, el modelo y las herramientas. Esta es la lógica central de la estructura de Codex, pero hay más en la experiencia completa del agente:

1. Ciclo de vida y persistencia del hilo. Un hilo es una conversación en Codex entre un usuario y un agente. Codex crea, reanuda, bifurca y archiva hilos, y conserva el historial de eventos para que los clientes puedan reconectarse y renderizar una línea de tiempo coherente.

2. Configuración y autenticación. Codex carga la configuración, gestiona los valores predeterminados y ejecuta flujos de autenticación como “Iniciar sesión con ChatGPT”, lo que incluye el estado de las credenciales.

3. Ejecución de herramientas y extensiones. Codex ejecuta herramientas de shell/archivo en un entorno aislado y conecta integraciones como servidores MCP y habilidades para que puedan participar en el ciclo del agente bajo un modelo de políticas coherente.

Toda la lógica del agente que mencionamos aquí, incluido el bucle principal del agente, reside en una parte del código base de la CLI de Codex llamada “Codex core⁠(se abre en una nueva ventana)”. Codex core es tanto una biblioteca donde reside todo el código del agente como un entorno de ejecución que se puede iniciar para ejecutar el bucle del agente y gestionar la persistencia de un hilo de Codex (conversación).

Para que sea útil, la estructura de Codex debe ser accesible para los clientes. Ahí es donde entra en juego App Server.

App Server es tanto el protocolo JSON-RPC entre el cliente y el servidor como un proceso de larga duración que aloja los hilos principales de Codex. Como podemos ver en el diagrama anterior, un proceso de App Server tiene cuatro componentes principales: el lector de stdio, el procesador de mensajes de Codex, el gestor de hilos y los hilos principales. El gestor de hilos inicia una sesión central para cada hilo, y el procesador de mensajes de Codex se comunica directamente con cada sesión central para enviar solicitudes de los clientes y recibir actualizaciones.

Una solicitud de cliente puede dar lugar a muchas actualizaciones de eventos, y estos eventos detallados son los que nos permiten crear una IU enriquecida sobre App Server. Además, el lector de stdio y el procesador de mensajes de Codex actúan como la capa de traducción entre el cliente y los hilos principales de Codex. Traducen las solicitudes JSON-RPC del cliente en operaciones del núcleo de Codex, escuchan el flujo de eventos internos del núcleo de Codex y luego transforman esos eventos de bajo nivel en un conjunto reducido de notificaciones JSON-RPC estables y listas para la IU.

El protocolo JSON-RPC entre el cliente y App Server es completamente bidireccional. Un hilo típico tiene una solicitud de cliente y muchas notificaciones de servidor. Además, el servidor puede iniciar solicitudes cuando el agente necesita una entrada, como una aprobación, y luego pausar el turno hasta que el cliente responda.

A continuación, analizaremos los elementos básicos de conversación, los componentes fundamentales del protocolo de App Server. Diseñar una API para un ciclo del agente es complicado porque la interacción entre el usuario y el agente no es una simple solicitud/respuesta. Una solicitud de usuario puede desarrollarse en una secuencia estructurada de acciones que el cliente necesita representar fielmente: la entrada del usuario, el progreso incremental del agente, los artefactos producidos en el camino (p. ej., diferencias). Para que ese flujo de interacción sea fácil de integrar y resistente en todas las IU, establecimos tres elementos básicos esenciales con límites y ciclos de vida claros:

1. Elemento: un elemento es la unidad atómica de entrada/salida en Codex. Los elementos se tipifican (p. ej., mensaje del usuario, mensaje del agente, ejecución de herramienta, solicitud de aprobación, diferencia) y cada uno tiene un ciclo de vida explícito:

• item/started cuando el elemento comienza
• eventos opcionales item/*/delta como flujos de contenido (para tipos de elementos de transmisión)
• item/completed cuando el elemento finaliza con su carga útil terminal

Este ciclo de vida permite a los clientes empezar a renderizar inmediatamente en started, transmitir actualizaciones incrementales en delta y finalizar en completed.

2. Turno: un turno es una unidad de trabajo del agente que comienza con la entrada del usuario. Comienza cuando el cliente envía una entrada (por ejemplo, “ejecutar pruebas y resumir fallos”) y termina cuando el agente finaliza la producción de salidas para esa entrada. Un turno incluye una secuencia de elementos que representan los pasos intermedios y los resultados generados a lo largo del proceso.

3. Hilo: un hilo es el contenedor duradero para una sesión de Codex en curso entre un usuario y un agente. Contiene múltiples giros. Los hilos se pueden crear, reanudar, bifurcar y archivar. El historial del hilo se guarda para que los clientes puedan reconectarse y mostrar una línea de tiempo coherente.

Ahora, vamos a observar una conversación simplificada entre un cliente y un agente, donde la conversación está representada por primitivas:

Al inicio de la conversación, el cliente y el servidor deben establecer el intercambio initialize. El cliente debe enviar una única solicitud initialize antes de cualquier otro método, y el servidor la confirma con una respuesta. Esto le da al servidor la oportunidad de anunciar sus capacidades y permite que ambas partes acuerden la versión del protocolo, los indicadores de funciones y los valores predeterminados antes de que comience el trabajo real. Aquí tienes un ejemplo de carga útil de la extensión de VS Code de OpenAI:

Esto es lo que devuelve el servidor:

Cuando un cliente crea una nueva solicitud, primero creará un hilo y luego un turno. El servidor enviará notificaciones de progreso (thread/started y turn/started). También enviará de vuelta las entradas que registre como elementos, como el mensaje del usuario aquí.

Las llamadas a herramientas también se devuelven al cliente como elementos. Además, el servidor puede solicitar la aprobación del cliente antes de poder ejecutar una acción al enviar una solicitud al servidor. La aprobación pausará el turno hasta que el cliente responda con “permitir” o “denegar”. Así es como luce el flujo de aprobación en la extensión de VS Code:

Al final, el servidor envía un mensaje de agente y luego finaliza el turno con turn/completed. Los eventos delta del mensaje del agente transmiten partes del mensaje hasta que se completa con item/completed.

Los mensajes en el diagrama están simplificados para facilitar la lectura. Si quieres ver el JSON de un turno completo, puedes ejecutar el cliente de prueba desde el repositorio de la CLI de Codex:

Ahora, veamos cómo diferentes interfaces de cliente integran Codex a través de App Server. Cubriremos tres patrones: aplicaciones locales e IDE, entorno de ejecución web de Codex y la TUI.

En los tres casos, el transporte es JSON-RPC sobre stdio (JSONL). JSON-RPC hace que sea sencillo crear enlaces de cliente en el idioma que prefieras. Las superficies de Codex y las integraciones de socios han implementado clientes de App Server en lenguajes como Go, Python, TypeScript, Swift y Kotlin. Para TypeScript, puedes generar definiciones directamente desde el protocolo de Rust al ejecutar:

Para otros lenguajes, puedes generar un paquete de esquema JSON e ingresarlo en tu generador de código preferido al ejecutar:

Los clientes locales suelen empaquetar o descargar un binario del App Server específico para la plataforma, ejecutarlo como un proceso secundario de larga duración y mantener abierto un canal bidireccional de entrada y salida estándar (stdio) para JSON-RPC En nuestra extensión de VS Code y aplicación de escritorio, por ejemplo, el artefacto entregado incluye el binario de Codex específico de la plataforma y está fijado a una versión probada para que el cliente siempre ejecute exactamente los mismos componentes que validamos.

No todas las integraciones pueden enviar actualizaciones para el cliente con frecuencia. Algunos socios, como Xcode, desacoplan los ciclos de lanzamiento al mantener el cliente estable y permitir que apunte a un binario más nuevo de App Server cuando sea necesario. De esa manera, pueden adoptar mejoras del lado del servidor (por ejemplo, mejor compactación automática en el núcleo de Codex o nuevas claves de configuración compatibles) e implementar correcciones de errores sin esperar a una versión del cliente. La interfaz JSON-RPC del App Server está diseñada para ser retrocompatible, de modo que los clientes de versiones anteriores puedan comunicarse con los servidores más recientes de forma segura.

Codex Web utiliza la estructura de Codex, pero la ejecuta en un entorno de contenedores. Un trabajador aprovisiona un contenedor con el espacio de trabajo extraído, inicia el binario del servidor de aplicaciones dentro de él y mantiene un canal JSON-RPC de larga duración sobre stdio². La aplicación web (que se ejecuta en la pestaña del navegador del usuario) se comunica con el backend de Codex a través de HTTP y SSE, que transmite eventos de tareas generados por el trabajador. Esto mantiene la interfaz de usuario del navegador ligera, mientras nos proporciona un entorno de ejecución coherente tanto en el escritorio como en la web.

Debido a que las sesiones web son efímeras (las pestañas se cierran, las redes se caen), la aplicación web no puede ser la fuente de referencia para tareas de larga duración. Mantener el estado y el progreso en el servidor significa que el trabajo sigue incluso si la pestaña desaparece. El protocolo de transmisión y las sesiones de hilo guardadas facilitan que una nueva sesión se reconecte, retome desde donde quedó y se ponga al día sin tener que recrear el estado en el cliente.

Históricamente, la TUI era un cliente “nativo” que se ejecutaba en el mismo proceso que el bucle del agente y se comunicaba directamente con los tipos principales de Rust en lugar de utilizar el protocolo app-server. Eso hizo que la primera iteración fuera rápida, pero también convirtió la TUI en una superficie especial.

Ahora que existe App Server, planeamos refactorizar la TUI⁠(se abre en una nueva ventana) para que lo utilice y se comporte como cualquier otro cliente: iniciar un proceso secundario de App Server, comunicarse mediante JSON-RPC a través de stdio y renderizar los mismos eventos de transmisión y aprobaciones. Esto desbloquea flujos de trabajo donde la TUI puede conectarse a un servidor Codex que se ejecuta en una máquina remota, lo que mantiene al agente cerca del cómputo y continúa el trabajo incluso si la computadora portátil se suspende o se desconecta, mientras sigue entregando actualizaciones en vivo y controles localmente.

Codex App Server será el método de integración de primer nivel que mantendremos en el futuro, pero también existen otros métodos con funcionalidad más limitada. Por defecto, recomendamos que los clientes usen Codex App Server para integrarse con Codex, pero es importante considerar diferentes métodos de integración y entender sus pros y contras. A continuación, se presentan las formas más comunes de utilizar Codex y cuándo cada una podría ser adecuada.

Ejecuta codex mcp-server⁠(se abre en una nueva ventana) y conéctate desde cualquier cliente MCP que soporte servidores stdio (por ejemplo, OpenAI Agents SDK⁠(se abre en una nueva ventana)). Esto es una buena opción si ya tienes un flujo de trabajo basado en MCP y deseas invocar Codex como una herramienta que se pueda llamar. La desventaja es que solo se obtiene lo que el MCP expone, por lo que las interacciones específicas de Codex que dependen de una semántica de sesión más enriquecida (por ejemplo, las actualizaciones de diferencias) podrían no mapearse de forma clara a través de los puntos de acceso del MCP.

Algunos ecosistemas ofrecen una interfaz portátil que puede dirigirse a múltiples proveedores de modelos y tiempos de ejecución. Esto puede ser una buena opción si deseas una abstracción que coordine múltiples agentes. El inconveniente es que estos protocolos a menudo convergen en el subconjunto común de capacidades, lo que puede dificultar la representación de interacciones más complejas, especialmente cuando las semánticas de herramientas y sesiones específicas del proveedor son importantes. Este espacio está evolucionando rápidamente, y esperamos que surjan estándares más comunes a medida que identificamos los mejores elementos básicos para representar flujos de trabajo de agentes del mundo real (las habilidades⁠(se abre en una nueva ventana) son un buen ejemplo de esto).

Elige App Server cuando desees que la estructura completa de Codex se presente como un flujo de eventos estable y fácil de usar en la IU. Obtienes tanto la funcionalidad completa del ciclo del agente como otras funciones de apoyo, como Iniciar sesión con ChatGPT, descubrimiento de modelos y gestión de la configuración. El costo principal es el trabajo de integración, ya que necesitas crear la vinculación JSON-RPC del lado del cliente en tu lenguaje. En la práctica, sin embargo, Codex puede realizar gran parte del trabajo pesado si le proporcionas el esquema JSON y la documentación. Muchos equipos con los que trabajamos lograron rápidamente una integración funcional usando Codex.

Un modo de CLI ligero y programable mediante scripts para tareas puntuales y ejecuciones de CI. Es una buena opción para la automatización y los pipelines donde deseas un solo comando que se ejecute hasta completarse de manera no interactiva, transmita resultados estructurados para los registros y termine con una señal clara de éxito o fracaso.

Una biblioteca de TypeScript para controlar programáticamente a los agentes Codex locales desde tu propia aplicación. Es lo mejor cuando quieres una interfaz de biblioteca nativa para herramientas y flujos de trabajo del lado del servidor sin tener que crear un cliente JSON-RPC por separado. Como se lanzó antes que App Server, actualmente admite menos idiomas y una superficie más reducida. Si hay interés de los desarrolladores, podríamos agregar SDK adicionales que envuelvan el protocolo App Server para que los equipos puedan cubrir más de la superficie de la estructura sin tener que escribir enlaces JSON-RPC.

En esta publicación, compartimos cómo abordamos el diseño de un nuevo estándar para interactuar con agentes y cómo convertir la estructura de Codex en un protocolo estable y fácil de usar para los clientes. Hablamos de cómo App Server expone el núcleo de Codex, permite a los clientes manejar el ciclo completo del agente y potencia una amplia gama de interfaces, lo que incluye la TUI, las integraciones locales con IDE y el entorno de ejecución web.

Si esto te inspiró a integrar Codex en tus propios flujos de trabajo, vale la pena probar App Server. Todo el código fuente se encuentra en el repositorio⁠(se abre en una nueva ventana) de código abierto de la CLI de Codex. No dudes en compartir tus comentarios y solicitudes de funciones. Nos entusiasma saber de ti y seguir haciendo que los agentes sean más accesibles para todos.