Usando o harness do Codex: como a OpenAI construiu o App Server

• A OpenAI criou e oferece uma arquitetura padronizada de App Server e um protocolo JSON-RPC para permitir a integração do Codex em produtos próprios
• No início, partiu de um harness TUI centrado em CLI, mas com a adoção do protocolo JSON-RPC passou a permitir que vários clientes, como IDE, web e apps locais, compartilhassem o mesmo loop de agente
• O App Server é um processo de longa duração que hospeda a biblioteca principal do Codex e expõe aos clientes toda a experiência do agente, incluindo gerenciamento do ciclo de vida de threads, configuração/autenticação e execução de ferramentas
• Por meio de três primitivas de conversa — item, turno e thread — ele estrutura as interações complexas do loop do agente e permite construir UIs ricas
• O mesmo harness é reutilizado em diferentes superfícies, como VS Code, JetBrains, Xcode, app desktop e runtime web, com suporte a bindings de cliente multilíngues em Go, Python, TypeScript, Swift e Kotlin
• Também há formas alternativas de integração, como servidor MCP, modo CLI e SDK TypeScript, mas o App Server se consolidou como o padrão prioritário de integração
• A OpenAI manterá o App Server como a rota padrão para integração do Codex e, por meio do repositório open source do CLI, dá suporte para que qualquer pessoa integre o Codex ao próprio fluxo de trabalho

---

Contexto básico do App Server

• No começo, era uma forma prática de reaproveitar o harness do Codex em vários produtos, mas aos poucos evoluiu para um protocolo padrão
• O Codex CLI começou como uma TUI (interface de usuário de terminal) e, ao criar a extensão para VS Code, surgiu a necessidade de rodar o mesmo harness dentro da UI da IDE
  • Era necessário dar suporte a vários padrões de interação além de simples requisição/resposta, como navegação no workspace, streaming do progresso de raciocínio e exibição de diff
• Num primeiro momento, houve a tentativa de expor o Codex como um servidor MCP, mas era difícil preservar a semântica do MCP de forma adequada ao VS Code
• Como alternativa, foi adotado um protocolo JSON-RPC que refletia o loop da TUI, tornando-se a primeira versão informal do App Server
  • Como na época não se imaginava que outros clientes dependeriam disso, ele não foi projetado como uma API estável
• À medida que a adoção do Codex cresceu, equipes internas e parceiros externos, como JetBrains e Xcode, passaram a pedir recursos para embutir o harness em seus próprios produtos
  • Tornou-se necessário projetar uma superfície de plataforma que permitisse evoluir o protocolo mantendo compatibilidade com versões anteriores

Estrutura interna do harness do Codex

• O núcleo do Codex é tanto uma biblioteca que contém todo o código do agente quanto o runtime que executa o loop do agente e gerencia a persistência de uma thread do Codex (conversa)
• Além do loop principal do agente, há três grandes áreas de funcionalidade:
  • Ciclo de vida e persistência de threads: criação, retomada, fork e arquivamento de threads, além da manutenção do registro de eventos para que os clientes possam se reconectar e renderizar uma linha do tempo consistente
  • Configuração e autenticação: carregamento de configuração, gerenciamento de padrões, controle do estado das credenciais e execução de fluxos de autenticação como "Entrar com ChatGPT"
  • Execução e extensão de ferramentas: execução de ferramentas de shell/arquivo em sandbox e conexão com integrações como servidores MCP e skills para participar do loop do agente sob um modelo de política consistente

Arquitetura do App Server

• O App Server é um protocolo JSON-RPC entre cliente e servidor e um processo de longa duração que hospeda threads do núcleo do Codex
• Quatro componentes principais:
  • Leitor de stdio: responsável por ler a entrada do cliente
  • Processador de mensagens do Codex: se comunica diretamente com cada sessão do núcleo para enviar requisições do cliente e receber atualizações
  • Gerenciador de threads: inicia uma sessão do núcleo para cada thread
  • Thread do núcleo: executa o loop de agente de fato
• Uma única requisição do cliente pode gerar muitas atualizações de eventos, e esses eventos detalhados permitem construir UIs ricas
• O leitor de stdio e o processador de mensagens do Codex atuam como uma camada de tradução que converte requisições JSON-RPC do cliente em operações do núcleo do Codex, e converte o fluxo interno de eventos em notificações JSON-RPC estáveis e utilizáveis pela UI
• O protocolo JSON-RPC entre cliente e App Server é totalmente bidirecional
  • Quando o agente precisa de uma entrada, como uma aprovação, o servidor pode iniciar a requisição e pausar o turno até que o cliente responda

Primitivas de conversa

• O ponto central do design de API para o loop do agente é que a interação entre usuário e agente não se desenrola como uma simples requisição/resposta, mas como uma sequência estruturada de tarefas
• Três primitivas principais:

• Item

  • A unidade básica de entrada/saída no Codex
  • É tipado: mensagem do usuário, mensagem do agente, execução de ferramenta, solicitação de aprovação, diff etc.
  • Tem um ciclo de vida explícito: item/started → item/*/delta opcional (streaming) → item/completed (payload final)
  • O cliente pode começar a renderizar imediatamente em started, transmitir atualizações progressivas em delta e concluir em completed

• Turno

  • Uma unidade de trabalho do agente iniciada por uma entrada do usuário
  • Exemplo: quando o cliente envia "run tests and summarize failures", o turno começa; quando o agente termina de gerar a saída, o turno termina
  • Um turno contém uma sequência de itens que representam etapas intermediárias e resultados

• Thread

  • Um contêiner persistente para uma sessão Codex em andamento entre usuário e agente
  • Contém vários turnos e pode ser criada, retomada, bifurcada ou arquivada
  • O histórico da thread é mantido continuamente para que o cliente possa se reconectar e renderizar uma linha do tempo consistente

Fluxo de conversa cliente-servidor

• No início da conversa, cliente e servidor precisam estabelecer um handshake initialize
  • O cliente envia uma única requisição initialize antes de qualquer outro método, e o servidor confirma na resposta
  • Os dois lados concordam sobre versionamento do protocolo, flags de recurso e padrões
• Em uma nova requisição, o servidor cria a thread, depois cria o turno e envia notificações thread/started e turn/started
• Chamadas de ferramenta também são enviadas ao cliente como itens, e o servidor pode solicitar aprovação para executar a tarefa
  • Quando há um pedido de aprovação, o turno fica pausado até que o cliente responda com "permitir" ou "negar"
• O servidor envia a mensagem do agente e encerra o turno com turn/completed
  • Eventos delta da mensagem do agente fazem streaming de partes da mensagem até a conclusão final com item/completed
• Para ver o JSON de um turno completo, é possível executar o comando codex debug app-server send-message-v2 "run tests and summarize failures"

Padrões de integração com clientes

• Apps locais e IDEs

  • O transporte é JSON-RPC via stdio (JSONL)
  • Clientes locais incluem ou baixam o binário do App Server específico da plataforma e o executam como um subprocesso de longa duração
  • Na extensão do VS Code e no app desktop, os artefatos de distribuição incluem binários do Codex específicos por plataforma, fixados em versões já testadas
  • Implementações de cliente do App Server já foram concluídas em várias linguagens, como Go, Python, TypeScript, Swift e Kotlin
    • TypeScript: geração direta das definições com o comando codex app-server generate-ts
    • Outras linguagens: geração de um bundle de JSON Schema com o comando codex app-server generate-json-schema, depois usado como entrada para geradores de código
  • Parceiros como o Xcode separam os ciclos de release mantendo o cliente estável e apontando para o binário mais recente do App Server
    • Isso permite distribuir melhorias do lado do servidor, como compactação automática aprimorada e novas chaves de configuração, além de correções de bugs, sem esperar por um release do cliente
    • Como a superfície JSON-RPC mantém compatibilidade com versões anteriores, clientes antigos podem se comunicar com segurança com servidores novos

• Runtime web do Codex

  • É executado em um ambiente de contêiner
  • O worker provisiona um contêiner com o workspace já em checkout, executa dentro dele o binário do App Server e mantém o JSON-RPC pelo canal stdio
  • O app web (navegador do usuário) se comunica com o backend do Codex por HTTP e SSE, fazendo streaming dos eventos de trabalho
  • Isso mantém a UI do navegador leve e fornece um runtime consistente entre desktop e web
  • Como as sessões web são curtas, por exemplo quando a aba é fechada ou a rede cai, o estado e o progresso são mantidos no servidor
    • Mesmo que a aba desapareça, o trabalho continua, e uma nova sessão pode se reconectar facilmente e retomar de onde parou

• Plano de refatoração da TUI

  • A TUI existente é um cliente "nativo" executado no mesmo processo que o loop do agente e se comunica diretamente com tipos do núcleo em Rust, e não pelo protocolo App Server
  • Há planos para refatorar a TUI para que ela funcione como os demais clientes usando o App Server
    • Ela poderá se conectar a um servidor Codex em execução em uma máquina remota
    • O agente ficará mais integrado à infraestrutura de computação, e o trabalho continuará mesmo com o notebook em suspensão ou com a conexão interrompida
    • Ao mesmo tempo, continuará oferecendo atualizações e controles ao vivo localmente

Escolhendo o protocolo certo

• O App Server é o método de integração prioritário, mas também existem alternativas com funcionalidade mais limitada

• Servidor MCP

  • Execute codex mcp-server e conecte-se a partir de qualquer cliente MCP com suporte a servidor stdio, como o OpenAI Agents SDK
  • É adequado quando já existe um fluxo de trabalho baseado em MCP e se deseja usar o Codex como uma ferramenta chamável
  • Desvantagem: fica limitado ao que o MCP oferece, e interações específicas do Codex, como atualizações de diff, podem não se mapear de forma fluida

• Interface portável

  • Adequada quando é necessária uma única abstração voltada a vários fornecedores de modelo e runtimes
  • Desvantagem: tende a convergir para o subconjunto comum de funcionalidades, o que pode dificultar a expressão de interações ricas
  • Essa área está evoluindo rapidamente, e espera-se o surgimento de mais padrões comuns, como agentskills.io

• App Server

  • Expõe o harness completo do Codex como um fluxo de eventos estável e amigável para UI
  • Além dos recursos completos do loop do agente, também disponibiliza funções de suporte como Entrar com ChatGPT, exploração de modelos e gerenciamento de configuração
  • O principal custo é a necessidade de criar bindings JSON-RPC no lado do cliente, na linguagem em uso
    • Com JSON Schema e documentação, o Codex consegue lidar com grande parte do trabalho complexo, e muitas equipes implementam a integração rapidamente

• Modo CLI

  • Um modo leve e orientado a scripts para tarefas pontuais e execuções de CI
  • Executa um único comando de forma não interativa, faz streaming de saída estruturada e encerra com sinalização clara de sucesso ou falha
  • É adequado para automação e pipelines

• SDK TypeScript

  • Uma biblioteca TypeScript para controlar programaticamente um agente Codex local dentro da própria aplicação
  • Adequada quando é necessária uma interface de biblioteca nativa sem construir um cliente JSON-RPC separado
  • Foi lançada antes do App Server, por isso tem menos linguagens suportadas e um escopo de aplicação mais restrito
  • Dependendo do interesse dos desenvolvedores, pode haver no futuro SDKs adicionais que encapsulem o protocolo do App Server

Planos futuros

• O App Server expõe o núcleo do Codex, permite que clientes operem o loop completo do agente e oferece suporte a uma ampla gama de superfícies, incluindo TUI, integrações com IDE local e runtime web
• Todo o código-fonte está disponível publicamente no repositório open source do Codex CLI
• Pedidos de recursos e feedback são bem-vindos, e estão previstas melhorias contínuas para tornar os agentes mais fáceis de usar

• Documentação oficial do Codex App Server