Cómo usar el harness de Codex: cómo OpenAI construyó App Server

• OpenAI creó y ofrece una arquitectura estandarizada de App Server y un protocolo JSON-RPC para poder integrar Codex en sus propios productos
• Al principio partió de un harness TUI centrado en la CLI, pero con la adopción del protocolo JSON-RPC varios clientes como IDE, web y apps locales pudieron compartir el mismo bucle de agente
• App Server es un proceso de larga ejecución que hospeda la librería central de Codex y expone a los clientes toda la experiencia del agente, incluyendo gestión del ciclo de vida de hilos, configuración/autenticación y ejecución de herramientas
• A través de tres primitivas de conversación —ítems, turnos e hilos— se estructuran las interacciones complejas del bucle de agente y se pueden construir interfaces ricas
• El mismo harness se reutiliza en distintas superficies como VS Code, JetBrains, Xcode, apps de escritorio y runtimes web, con soporte de bindings de cliente multilenguaje para Go, Python, TypeScript, Swift y Kotlin
• También se ofrecen métodos alternativos de integración como servidores MCP, modo CLI y SDK de TypeScript, pero App Server se consolidó como el estándar principal de integración
• OpenAI mantendrá App Server como la ruta predeterminada para integrar Codex y, mediante el repositorio open source de la CLI, permite que cualquiera integre Codex en sus propios flujos de trabajo

---

Contexto básico de App Server

• Al inicio era una forma práctica de reutilizar el harness de Codex en varios productos, pero con el tiempo evolucionó hacia un protocolo estándar
• Codex CLI comenzó como una TUI (interfaz de usuario de terminal), y al crear la extensión de VS Code hizo falta una forma de ejecutar ese mismo harness dentro de la UI del IDE
  • Era necesario soportar patrones de interacción que van más allá de solicitud/respuesta, como exploración del workspace, streaming del progreso de razonamiento y salida de diffs
• Al principio se intentó exponer Codex como un servidor MCP, pero era difícil conservar la semántica de MCP de una manera adecuada para VS Code
• Como alternativa, se adoptó un protocolo JSON-RPC que reflejaba el bucle de la TUI, y eso se convirtió en la primera versión no oficial de App Server
  • En ese momento no se esperaba que otros clientes dependieran de él, así que no fue diseñado como una API estable
• A medida que creció la adopción de Codex, equipos internos y socios externos (JetBrains, Xcode, etc.) pidieron la capacidad de embeber el harness en sus propios productos
  • Se volvió necesario diseñar una superficie de plataforma que permitiera evolucionar el protocolo manteniendo la compatibilidad con versiones anteriores

Estructura interna del harness de Codex

• El núcleo de Codex es una librería que contiene todo el código del agente y también el runtime que ejecuta el bucle de agente y gestiona la persistencia de un hilo de Codex (conversación)
• Además del bucle principal del agente, existen tres grandes áreas funcionales:
  • Ciclo de vida y persistencia de hilos: creación, reanudación, bifurcación y archivado de hilos, manteniendo un registro de eventos para que los clientes puedan reconectarse y renderizar una línea de tiempo consistente
  • Configuración y autenticación: carga de configuración, gestión de valores por defecto, estado de credenciales y ejecución de flujos de autenticación como “Iniciar sesión con ChatGPT”
  • Ejecución y extensión de herramientas: ejecución de herramientas de shell/archivos en sandbox, además de conectar integraciones como servidores MCP y skills para que participen en el bucle de agente bajo un modelo de políticas consistente

Arquitectura de App Server

• App Server es un protocolo JSON-RPC entre cliente y servidor, y también un proceso de larga ejecución que hospeda hilos del núcleo de Codex
• Tiene cuatro componentes principales:
  • Lector de stdio: se encarga de leer la entrada del cliente
  • Procesador de mensajes de Codex: se comunica directamente con cada sesión del núcleo para enviar solicitudes del cliente y recibir actualizaciones
  • Administrador de hilos: inicia una sesión del núcleo por cada hilo
  • Hilo del núcleo: ejecuta el bucle real del agente
• Una sola solicitud del cliente puede generar muchas actualizaciones de eventos, y estos eventos detallados permiten construir interfaces ricas
• El lector de stdio y el procesador de mensajes de Codex funcionan como una capa de transformación que convierte solicitudes JSON-RPC del cliente en tareas del núcleo de Codex, y transforma el flujo de eventos internos en notificaciones JSON-RPC estables y utilizables por la UI
• El protocolo JSON-RPC entre cliente y App Server es completamente bidireccional
  • Cuando el agente necesita una entrada como una aprobación, el servidor puede iniciar la solicitud y pausar el turno hasta que el cliente responda

Primitivas de conversación

• La clave al diseñar una API para el bucle de agente es que la interacción entre usuario y agente no se desarrolla como una simple solicitud/respuesta, sino como una secuencia estructurada de acciones
• Hay tres primitivas centrales:

• Ítem (Item)

  • La unidad básica de entrada/salida en Codex
  • Tiene tipo definido: mensaje del usuario, mensaje del agente, ejecución de herramienta, solicitud de aprobación, diff, etc.
  • Tiene un ciclo de vida explícito: item/started → item/*/delta opcional (streaming) → item/completed (payload final)
  • El cliente puede empezar a renderizar inmediatamente en started, recibir actualizaciones progresivas en delta y cerrar con completed

• Turno (Turn)

  • Una unidad de trabajo del agente que comienza con una entrada del usuario
  • Ejemplo: si el cliente envía “run tests and summarize failures”, el turno comienza; cuando el agente termina de generar la salida, el turno finaliza
  • Un turno contiene una serie de ítems que representan pasos intermedios y resultados

• Hilo (Thread)

  • Un contenedor persistente para una sesión de Codex en curso entre usuario y agente
  • Contiene varios turnos y puede crearse, reanudarse, bifurcarse o archivarse
  • El historial del hilo se conserva de forma persistente para que los clientes puedan reconectarse y renderizar una línea de tiempo consistente

Flujo de conversación cliente-servidor

• Al iniciar una conversación, cliente y servidor deben establecer el handshake de initialize
  • El cliente envía una única solicitud initialize antes de cualquier otro método, y el servidor la confirma en su respuesta
  • Ambas partes acuerdan el versionado del protocolo, flags de capacidades y valores por defecto
• Ante una nueva solicitud, el servidor crea un hilo y luego un turno, y envía notificaciones thread/started y turn/started
• Las llamadas a herramientas también se envían al cliente como ítems, y el servidor puede pedir aprobación para ejecutar una tarea
  • Cuando se solicita aprobación, el turno queda en pausa hasta que el cliente responda “permitir” o “rechazar”
• El servidor envía el mensaje del agente y cierra el turno con turn/completed
  • Los eventos delta del mensaje del agente transmiten partes del mensaje por streaming, hasta cerrarse finalmente con item/completed
• Para ver el JSON completo de un turno, se puede ejecutar el comando codex debug app-server send-message-v2 "run tests and summarize failures"

Patrones de integración con clientes

• Apps locales e IDE

  • El transporte es JSON-RPC sobre stdio (JSONL)
  • Los clientes locales incluyen o descargan el binario de App Server por plataforma y lo ejecutan como un subproceso de larga duración
  • En la extensión de VS Code y en la app de escritorio, los artefactos de despliegue incluyen binarios de Codex por plataforma, fijados a versiones ya probadas
  • Ya existen implementaciones de cliente de App Server en varios lenguajes como Go, Python, TypeScript, Swift y Kotlin
    • TypeScript: las definiciones se pueden generar directamente con el comando codex app-server generate-ts
    • Otros lenguajes: se puede generar un bundle de esquemas JSON con codex app-server generate-json-schema y luego pasarlo a un generador de código
  • Socios como Xcode pueden separar los ciclos de lanzamiento manteniendo estable el cliente y apuntando al binario más reciente de App Server
    • Esto permite desplegar mejoras del lado del servidor (como una autocompactación mejorada o nuevas claves de configuración) y correcciones de bugs sin esperar el lanzamiento del cliente
    • La superficie JSON-RPC mantiene compatibilidad hacia atrás, por lo que clientes antiguos pueden comunicarse de forma segura con servidores nuevos

• Runtime web de Codex

  • Se ejecuta en un entorno de contenedores
  • Un worker aprovisiona un contenedor con el workspace ya descargado, ejecuta dentro de él el binario de App Server y mantiene JSON-RPC a través de un canal stdio
  • La app web (el navegador del usuario) se comunica con el backend de Codex mediante HTTP y SSE para transmitir eventos de trabajo
  • Esto permite mantener ligera la UI del navegador y, al mismo tiempo, ofrecer un runtime consistente entre escritorio y web
  • Como las sesiones web son de corta duración (pestaña cerrada, corte de red), el servidor conserva el estado y el progreso
    • Aunque la pestaña desaparezca, el trabajo continúa y una nueva sesión puede reconectarse fácilmente y reanudar donde se quedó

• Plan de refactorización de la TUI

  • La TUI existente es un cliente “nativo” que corre en el mismo proceso que el bucle de agente y se comunica directamente con tipos del núcleo en Rust, no con el protocolo App Server
  • Está previsto refactorizar la TUI para que use App Server y funcione como cualquier otro cliente
    • Podrá conectarse a un servidor Codex que se esté ejecutando en una máquina remota
    • El agente podrá integrarse estrechamente con la infraestructura de cómputo, de modo que el trabajo continúe incluso si la laptop entra en suspensión o se pierde la conexión
    • Seguirá ofreciendo actualizaciones en vivo y controles de forma local

Elegir el protocolo correcto

• App Server es la forma principal de integración, pero también existen alternativas con capacidades más limitadas

• Servidor MCP

  • Se ejecuta codex mcp-server y se conecta desde cualquier cliente MCP compatible con servidores stdio (por ejemplo, OpenAI Agents SDK)
  • Es adecuado si ya existe un flujo de trabajo basado en MCP y se quiere usar Codex como una herramienta invocable
  • Desventaja: solo se puede usar lo que MCP ofrece, y las interacciones específicas de Codex, como las actualizaciones de diffs, podrían no mapearse de forma fluida

• Interfaz portable

  • Adecuada cuando se necesita una sola abstracción para múltiples proveedores de modelos y runtimes
  • Desventaja: tiende a converger en el subconjunto común de capacidades, lo que puede dificultar expresar interacciones ricas
  • Este campo está avanzando rápido y se espera que aparezcan más estándares comunes (por ejemplo, agentskills.io)

• App Server

  • Expone el harness completo de Codex como un flujo de eventos estable y amigable para UI
  • Además de la funcionalidad completa del bucle de agente, también permite usar funciones de soporte como iniciar sesión con ChatGPT, exploración de modelos y gestión de configuración
  • Costo principal: hay que construir bindings JSON-RPC del lado cliente en el lenguaje que se esté usando
    • Si se proporcionan esquemas JSON y documentación, Codex puede encargarse de gran parte del trabajo complejo y muchos equipos pueden implementar la integración rápidamente

• Modo CLI

  • Un modo ligero orientado a scripts para tareas puntuales y ejecuciones de CI
  • Ejecuta un único comando de forma no interactiva, transmite salida estructurada y termina con una señal clara de éxito o fracaso
  • Es adecuado para automatización y pipelines

• SDK de TypeScript

  • Una librería de TypeScript para controlar programáticamente un agente local de Codex dentro de la propia aplicación
  • Es adecuada cuando se necesita una interfaz de librería nativa sin construir un cliente JSON-RPC por separado
  • Se lanzó antes que App Server, por lo que soporta menos lenguajes y cubre un alcance más reducido
  • Dependiendo del interés de desarrolladores, existe la posibilidad de ofrecer SDK adicionales que envuelvan el protocolo App Server

Próximos planes

• App Server expone el núcleo de Codex, permite que los clientes controlen el bucle completo del agente y brinda soporte para una amplia variedad de superficies como TUI, integraciones con IDE locales y runtime web
• Todo el código fuente está publicado en el repositorio open source de Codex CLI
• Se reciben con gusto solicitudes de funciones y comentarios, y se seguirá mejorando continuamente para facilitar aún más el uso de agentes

• Documentación oficial de Codex App Server