Descubrir el potencial de Codex: cómo desarrollamos el App Server

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

En esta publicación, presentaremos el App Server de Codex, compartiremos lo que hemos aprendido 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. Vamos a cubrir la arquitectura y el protocolo del App Server y cómo se integra con diferentes superficies de Codex, y ofreceremos consejos sobre cómo aprovechar Codex, tanto si quieres aprovechar Codex como revisor de código, agente de SRE o asistente de programación.

Antes de sumergirte en la arquitectura, conviene que conozcas la historia del App Server. Inicialmente, el App Server fue una forma práctica de reutilizar el potencial de Codex en productos, que gradualmente evolucionó hasta convertirse en nuestro protocolo estándar.

Codex CLI comenzó como una interfaz de usuario de terminal (TUI), lo que significa que se accede a Codex a través del terminal. Cuando desarrollamos la extensión de VS Code (una forma más intuitiva con IDE para interactuar con los agentes de Codex), necesitábamos una manera para utilizar el mismo sistema con el fin de poder ejecutar el mismo ciclo de agente desde una interfaz de usuario de IDE sin tener que reimplementarlo. Eso significaba admitir patrones de interacción enriquecidos más allá de la solicitud/respuesta, como explorar el área de trabajo, transmitir el progreso a medida que el agente razona y emitir diffs. Primero experimentamos para exponer Codex como un servidor MCP⁠(se abre en una ventana nueva), pero resulto difícil mantener la semántica de MCP de una manera que tuviera sentido para VS Code. En su lugar, introdujimos un protocolo JSON-RPC que reflejaba el ciclo de la TUI, lo cual pasó a convertirse en la primera versión no oficial⁠(se abre en una ventana nueva) del App Server. En aquel momento, no esperábamos que otros clientes dependieran del App Server, así que no lo diseñamos como una API estable.

A medida que la adopción de Codex crecía durante los meses siguientes, los equipos internos y los socios externos querían poder integrar el mismo sistema en sus propios productos para acelerar 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 coordinar 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 confiar de manera segura a lo largo del tiempo. Tenía que ser fácil de integrar y compatible con versiones anteriores, de manera que pudiéramos avanzar el protocolo sin afectar a los clientes existentes.

A continuación, veremos cómo diseñamos la arquitectura y el protocolo para que distintos clientes puedan usar el mismo sistema.

Primero, vamos a profundizar en el marco de Codex para ver cómo el App Server de Codex 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 del marco de Codex, pero la experiencia completa del agente incluye todavía más:

1. Ciclo de vida y conservación del hilo. Un hilo es una conversación de Codex entre un usuario y un agente. Codex crea, reanuda, bifurca y archiva hilos, y guarda el historial de eventos para que los clientes puedan volver a conectarse y mostrar una cronología 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», incluido el estado de las credenciales.

3. Ejecución de herramientas y extensiones. Codex ejecuta herramientas de comandos/archivos 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 ciclo central del agente, se encuentra en una parte de la base de código de Codex CLI llamada «núcleo de Codex⁠(se abre en una ventana nueva)». El núcleo de Codex funciona tanto como una biblioteca donde reside todo el código del agente como un entorno de ejecución que se puede iniciar para ejecutar el ciclo del agente y gestionar la conservación de un hilo de Codex (conversación).

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

El 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 centrales 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 centrales. El gestor de hilos inicia una sesión principal para cada hilo, y el procesador de mensajes de Codex se comunica directamente con cada sesión principal para enviar solicitudes de 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 interfaz de usuario rica sobre el App Server. Además, el lector de stdio y el procesador de mensajes de Codex actúan como la capa de conversión entre el cliente y los hilos centrales de Codex. Convierten las solicitudes JSON-RPC del cliente en operaciones centrales de Codex, escuchan el flujo de eventos interno 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 interfaz de usuario.

El protocolo JSON-RPC entre el cliente y el App Server es totalmente bidireccional. Un hilo típico tiene una solicitud de un cliente y muchas notificaciones de un 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, vamos a desglosar los elementos básicos de la conversación, que son los bloques que desarrollan el protocolo de App Server. Diseñar una API para un ciclo de agente es complicado porque la interacción usuario/agente no consiste en un simple proceso de solicitud/respuesta. Una solicitud de usuario puede convertirse en una secuencia estructurada de acciones que el cliente debe representar fielmente: la entrada del usuario, el progreso incremental del agente y los artefactos generados a lo largo del camino (p. ej., diffs). Para que ese flujo de interacción sea fácil de integrar y resistente en todas las interfaces de usuario, optamos por tres elementos básicos fundamentales con unos límites y ciclos de vida claros:

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

• elemento/iniciado cuando comienza el elemento
• eventos opcionales elemento/*/delta como flujos de contenido (para tipos de elementos de transmisión)
• elemento/completado cuando se completa el elemento con su carga útil final

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

2. Turno: Un turno es una unidad de trabajo del agente que se inicia 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 contiene una secuencia de elementos que representan los pasos intermedios y los resultados generados a lo largo del camino.

3. Hilo: Un hilo es el contenedor permanente de una sesión de Codex en curso entre un usuario y un agente. Contiene múltiples turnos. Los hilos pueden crearse, reanudarse, bifurcarse y archivarse. El historial del hilo se guarda para que los clientes puedan volver a conectarse y mostrar una cronología coherente.

Ahora, vamos a ver una conversación simplificada entre un cliente y un agente, donde la conversación se representa mediante elementos básicos:

Al inicio de la conversación, el cliente y el servidor deben establecer el saludo de inicialización. El cliente debe enviar una única solicitud de inicialización antes de cualquier otro método, que el servidor confirma mediante una respuesta. Esto permite al servidor anunciar sus capacidades y dejar que ambas partes acuerden el versionado del protocolo, las señales de características y los valores predeterminados antes de que comience el trabajo real. Este es un ejemplo de carga útil de la extensión de VS Code de OpenAI:

Esto es lo que devuelve el servidor:

Cuando un cliente hace una nueva solicitud, primero creará un hilo y luego un turno. El servidor enviará notificaciones de progreso (hilo/iniciado y turno/iniciado). También devolverá las entradas que registre como elementos para que constituya el mensaje del usuario aquí.

Las llamadas a herramientas también se envían al cliente como elementos. Además, el servidor puede solicitar la aprobación del cliente antes de poder ejecutar una acción enviando una solicitud al servidor. La aprobación pausará el turno hasta que el cliente responda con «permitir» o «denegar». Así es como se ve 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 turno/completado. Los eventos delta del agente transmiten fragmentos del mensaje hasta que el mensaje se finaliza con elemento/completado.

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:

A continuación, veremos cómo diferentes superficies de cliente integran Codex a través del App Server. Cubriremos tres patrones: aplicaciones locales e IDE, el entorno de ejecución de Codex web y la TUI.

En los tres casos, el transporte es JSON-RPC sobre stdio (JSONL). JSON-RPC facilita la creación de enlaces de cliente en el idioma que prefieras. Las interfaces de Codex y las integraciones con 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 ejecutando:

Para otros idiomas, puedes generar un paquete de esquema JSON e integrarlo a tu generador de código preferido ejecutando:

Los clientes locales suelen agrupar o recuperar un binario específico de la plataforma del App Server, iniciarlo como un proceso hijo de larga duración y mantener abierto un canal bidireccional de stdio para JSON-RPC. En nuestra extensión de VS Code y aplicación de escritorio, por ejemplo, el artefacto creado incluye el binario específico de la plataforma de Codex y está anclado a una versión probada para que el cliente siempre ejecute exactamente los mismos bits que validamos.

No todas las integraciones pueden enviar con frecuencia actualizaciones de cliente. Algunos socios como Xcode desacoplan los ciclos de lanzamiento manteniendo el cliente estable y permitiendo que apunte a un binario más reciente del App Server cuando sea necesario. Así, pueden adoptar mejoras del lado del servidor (por ejemplo, una mejor autocompactación en el núcleo de Codex o nuevas claves de configuración compatibles) y desplegar correcciones de errores sin esperar a una nueva versión del cliente. La superficie JSON-RPC del App Server está diseñada para ser compatible con versiones anteriores, de modo que los clientes antiguos puedan comunicarse con servidores más nuevos de forma segura.

Codex web utiliza el marco Codex, pero lo ejecuta en un entorno de contenedores. Un trabajador aprovisiona un contenedor con el área de trabajo verificada, inicia el binario del App Server 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 producidos por el trabajador. Esto hace que la interfaz de usuario del lado del navegador sea ligera, a la vez que nos ofrece un entorno de ejecución coherente en el escritorio y la web.

Dado 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 verdad para tareas de larga duración. Al mantenerse el estado y el progreso en el servidor, el trabajo sigue incluso aun cuando la pestaña desaparezca. El protocolo de transmisión y las sesiones de hilo guardadas facilitan que una nueva sesión vuelva a conectarse, continúe donde se quedó y se ponga al día sin tener que reconstruir el estado en el cliente.

Históricamente, la TUI era un cliente «nativo» que se ejecutaba en el mismo proceso que el ciclo del agente y se comunicaba directamente con los tipos principales de Rust en lugar de con el protocolo del servidor de aplicaciones. Eso hizo que la iteración temprana fuera rápida, pero también convirtió la TUI en una superficie de caso especial.

Ahora que el App Server es una realidad, prevemos refactorizar la TUI⁠(se abre en una ventana nueva) para que pueda usarlo y comportarse como cualquier otro cliente: lanzar un proceso hijo del App Server, comunicarse mediante JSON-RPC a través de stdio y renderizar los mismos eventos y aprobaciones en streaming. Esto hará desbloquear los flujos de trabajo cuando la TUI pueda conectarse a un servidor Codex que se ejecuta en una máquina remota, manteniendo el agente cerca del cálculo y continuando el trabajo aun cuando el portátil suspenda la sesión o se desconecte, mientras sigue ofreciendo actualizaciones y controles en vivo a nivel local.

App Server de Codex será el método de integración excepcional que mantendremos de ahora en adelante, aunque también hay otros métodos con una funcionalidad más limitada. Por defecto, recomendamos que nuestros clientes usen App Server de Codex para integrarse con Codex; sin embargo, vale la pena considerar diferentes métodos de integración y entender sus pros y contras. A continuación, mostramos las formas más comunes de usar Codex y en qué casos conviene recurrir a cada una de ellas.

Ejecuta codex mcp-server⁠(se abre en una ventana nueva) y conecta desde cualquier cliente MCP que sea compatible con servidores stdio (por ejemplo, OpenAI Agents SDK⁠(se abre en una ventana nueva)). Esto es una buena opción si ya tienes un flujo de trabajo basado en MCP y quieres invocar Codex como una herramienta a la que se pueda llamar. La desventaja es que solo obtienes lo que expone MCP, por lo que es posible que las interacciones específicas de Codex que dependen de una semántica de sesión más rica (p. ej., actualizaciones de diff) no se asignen de forma limpia a través de los puntos de acceso de MCP.

Algunos ecosistemas ofrecen una interfaz portátil que puede dirigirse a varios proveedores de modelos y tiempos de ejecución. Esto puede ser una buena opción si quieres una abstracción que coordine a múltiples agentes. La desventaja 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 es importante la semántica de herramientas y sesiones específicas del proveedor. Este espacio está evolucionando rápidamente, y esperamos que surjan estándares más comunes a medida que descubrimos los mejores elementos básicos para representar flujos de trabajo de agentes del mundo real (skills⁠(se abre en una ventana nueva) es un buen ejemplo de esto).

Elige el App Server cuando quieras que el marco completo de Codex se exponga como un flujo de eventos estable y sea fácil de usar para la interfaz de usuario. Obtienes tanto la funcionalidad completa del ciclo del agente como otras funciones de soporte, como iniciar sesión con ChatGPT, descubrimiento de modelos y gestión de configuración. El coste principal es el trabajo de integración, ya que necesitas construir la vinculación JSON-RPC del lado del cliente en tu idioma. En la práctica, sin embargo, Codex puede hacer gran parte del trabajo pesado si le das el esquema JSON y la documentación. Muchos equipos con los que trabajamos lograron rápidamente una integración funcional usando Codex.

Un modo CLI ligero y programable para tareas puntuales y ejecuciones de CI. Es una buena opción para la automatización y los flujos cuando quieres que un único comando se ejecute hasta completarse sin interacciones, transmita resultados estructurados para los registros y finalice 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 construir un cliente JSON-RPC independiente. Como se lanzó antes que el App Server, actualmente admite menos idiomas y una superficie más reducida. Si los desarrolladores demuestran interés, podríamos añadir SDK adicionales que envuelvan el protocolo del App Server para que los equipos puedan cubrir más superficie 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 el marco de Codex en un protocolo estable e intuitivo para los clientes. Hablamos de cómo el App Server expone el núcleo de Codex, permite a los clientes manejar el ciclo completo del agente y da soporte a una amplia gama de interfaces, incluidas la TUI, las integraciones locales de IDE y el entorno de ejecución web.

Si este contenido te ha inspirado ideas para integrar Codex en tus propios flujos de trabajo, merece la pena probar el App Server. Todo el código fuente se encuentra está en el repositorio⁠(se abre en una ventana nueva) de código abierto de Codex CLI . No dudes en compartir tus comentarios y solicitudes de funciones. Siempre nos alegra tener noticias y saber que el acceso a los agentes es cada vez extenso.