Desvendando os segredos do Codex: como construímos o App Server

O agente de codificação Codex da OpenAI está presente em diversas plataformas: o aplicativo web⁠(abre em uma nova janela), a interface de linha de comando (CLI)⁠(abre em uma nova janela), a extensão para IDE⁠(abre em uma nova janela) e o novo aplicativo Codex para macOS. Por baixo dos panos, todos são alimentados pela mesma estrutura Codex — o circuito de agentes e a lógica que sustenta todas as experiências Codex. Qual é o elo crucial entre eles? O Codex App Server⁠(abre em uma nova janela), uma API JSON-RPC¹ bidirecional e fácil de usar para o cliente.

Neste post, apresentaremos o Codex App Server e compartilharemos o que aprendemos até agora sobre as melhores maneiras de integrar os recursos do Codex ao seu produto para ajudar seus usuários a otimizar seus fluxos de trabalho. Vamos abordar a arquitetura e o protocolo do Servidor de Aplicativos e como ele se integra com diferentes superfícies do Codex, além de dicas sobre como aproveitar o Codex, seja para transformá-lo em um revisor de código, um agente SRE ou um assistente de codificação.

Antes de mergulhar na arquitetura, é útil conhecer o histórico do servidor de aplicativos. Inicialmente, o Servidor de Aplicativos era uma maneira prática de reutilizar a estrutura do Codex em diversos produtos, evoluindo gradualmente para o nosso protocolo padrão.

O Codex CLI começou como uma TUI (interface de usuário de terminal), o que significa que o Codex é acessado através do terminal. Ao criarmos a extensão para VS Code (uma forma mais amigável para IDEs de interagir com os agentes do Codex), precisávamos de uma maneira de usar a mesma estrutura para controlar o mesmo loop do agente a partir da interface do usuário da IDE, sem precisar reimplementá-lo. Isso significava dar suporte a padrões de interação complexos que iam além de solicitação/resposta, como explorar o espaço de trabalho, transmitir o progresso à medida que o agente raciocina e emitir diferenças. Inicialmente, experimentamos expor o Codex como um servidor MCP⁠(abre em uma nova janela), mas manter a semântica do MCP de uma forma que fizesse sentido para o VS Code provou ser difícil. Em vez disso, introduzimos um protocolo JSON-RPC que espelhava o loop da TUI, o qual se tornou a primeira versão não oficial⁠(abre em uma nova janela) do Servidor de Aplicativos. Na época, não prevíamos que outros clientes dependeriam do Servidor de Aplicativos, portanto, ele não foi projetado como uma API estável.

Com o crescimento da adoção do Codex nos meses seguintes, equipes internas e parceiros externos passaram a desejar a capacidade de incorporar a mesma estrutura em seus próprios produtos, a fim de acelerar os fluxos de trabalho de desenvolvimento de software de seus usuários. Por exemplo, a JetBrains e o Xcode queriam uma experiência de agente semelhante à de um IDE, enquanto o aplicativo de desktop do Codex precisava orquestrar vários agentes do Codex em paralelo. Essas demandas nos impulsionaram a projetar uma plataforma na qual tanto nossos produtos quanto as integrações com parceiros pudessem confiar com segurança ao longo do tempo. Precisava ser fácil de integrar e compatível com versões anteriores, o que significa que poderíamos evoluir o protocolo sem afetar os clientes existentes.

A seguir, vamos explicar como projetamos a arquitetura e o protocolo para que diferentes clientes possam usar a mesma plataforma.

Primeiro, vamos analisar em detalhes o que está dentro da estrutura do Codex e como o servidor de aplicativos do Codex a expõe aos clientes. Em nosso último blog do Codex, detalhamos o loop do agente central que orquestra a interação entre o usuário, o modelo e as ferramentas. Essa é a lógica central da estrutura Codex, mas a experiência completa do agente vai muito além disso:

1. Ciclo de vida e persistência do thread. Uma thread é uma conversa do Codex entre um usuário e um agente. O Codex cria, retoma, faz fork e arquiva tópicos, e persiste o histórico de eventos para que os clientes possam se reconectar e renderizar uma linha do tempo consistente.

2. Configuração e autenticação. O Codex carrega a configuração, gerencia os valores padrão e executa fluxos de autenticação como "Entrar com ChatGPT", incluindo o estado das credenciais.

3. Execução e extensões da ferramenta. O Codex executa ferramentas de shell/arquivo em um ambiente isolado (sandbox) e integra recursos como servidores e habilidades do MCP para que possam participar do ciclo do agente sob um modelo de política consistente.

Toda a lógica do agente que mencionamos aqui, incluindo o loop principal do agente, reside em uma parte do código-fonte da CLI do Codex chamada "Codex core⁠(abre em uma nova janela) ". O núcleo do Codex é simultaneamente uma biblioteca onde reside todo o código do agente e um ambiente de execução que pode ser iniciado para executar o loop do agente e gerenciar a persistência de uma thread (conversa) do Codex.

Para ser útil, o dispositivo Codex precisa ser acessível aos clientes. É aí que entra o Servidor de Aplicativos.

O servidor de aplicativos funciona tanto como protocolo JSON-RPC entre o cliente e o servidor, quanto como um processo de longa duração que hospeda os threads principais do Codex. Como podemos ver no diagrama acima, um processo de servidor de aplicativos possui quatro componentes principais: o leitor de stdio, o processador de mensagens Codex, o gerenciador de threads e as threads principais. O gerenciador de threads inicia uma sessão principal para cada thread, e o processador de mensagens Codex se comunica diretamente com cada sessão principal para enviar solicitações do cliente e receber atualizações.

Uma única solicitação do cliente pode resultar em várias atualizações de eventos, e esses eventos detalhados são o que nos permitem construir uma interface de usuário rica sobre o servidor de aplicativos. Além disso, o leitor stdio e o processador de mensagens Codex servem como camada de tradução entre o cliente e os threads principais do Codex. Eles traduzem as solicitações JSON-RPC do cliente em operações do núcleo do Codex, monitoram o fluxo de eventos interno do núcleo do Codex e, em seguida, transformam esses eventos de baixo nível em um pequeno conjunto de notificações JSON-RPC estáveis e prontas para a interface do usuário.

O protocolo JSON-RPC entre o cliente e o servidor de aplicativos é totalmente bidirecional. Uma thread típica possui uma solicitação do cliente e várias notificações do servidor. Além disso, o servidor pode iniciar solicitações quando o agente precisa de informações, como uma aprovação, e então pausar a operação até que o cliente responda.

A seguir, vamos analisar os elementos básicos da conversação, os componentes fundamentais do protocolo do servidor de aplicativos. Projetar uma API para um ciclo de agentes é complicado porque a interação usuário/agente não é uma simples solicitação/resposta. Uma solicitação do usuário pode se desdobrar em uma sequência estruturada de ações que o cliente precisa representar fielmente: a entrada do usuário, o progresso incremental do agente e os artefatos produzidos ao longo do processo (por exemplo, diferenças). Para facilitar a integração e garantir a resiliência desse fluxo de interação em diferentes interfaces de usuário, definimos três elementos básicos com limites e ciclos de vida bem definidos:

1. Item: Um item é a unidade atômica de entrada/saída no Codex. Os itens são tipificados (por exemplo, mensagem do usuário, mensagem do agente, execução da ferramenta, solicitação de aprovação, diff) e cada um possui um ciclo de vida explícito:

• item/started quando o item começa
• Eventos opcionais item/*/delta como fluxos de conteúdo (para tipos de itens de streaming)
• item/completed quando o item finaliza com sua carga útil terminal

Esse ciclo de vida permite que os clientes comecem a renderizar imediatamente ao started, transmitam atualizações incrementais ao serem atualizados delta e finalizem ao completed.

2. Turno: Um turno é uma unidade de trabalho de agente iniciada pela entrada do usuário. Começa quando o cliente envia uma entrada (por exemplo, "executar testes e resumir falhas") e termina quando o agente termina de produzir as saídas para essa entrada. Uma rodada contém uma sequência de itens que representam as etapas intermediárias e as saídas produzidas ao longo do caminho.

3. Thread: Uma thread é o contêiner persistente para uma sessão Codex em andamento entre um usuário e um agente. Ela contém vários turnos. É possível criar, retomar, bifurcar e arquivar tópicos. O histórico da thread é persistido para que os clientes possam se reconectar e renderizar uma linha do tempo consistente.

Agora, vamos analisar uma conversa simplificada entre um cliente e um agente, onde a conversa é representada por tipos primitivos:

No início da conversa, o cliente e o servidor precisam estabelecer o handshake initialize . O cliente deve enviar uma única initialize requisição antes de qualquer outro método, e o servidor confirma com uma resposta. Isso dá ao servidor a oportunidade de anunciar suas capacidades e permite que ambos os lados concordem com o versionamento do protocolo, os sinalizadores de recursos e os valores padrão antes que o trabalho real comece. Aqui está um exemplo de payload da extensão VS Code da OpenAI:

Isto é o que o servidor retorna:

Quando um cliente faz uma nova solicitação, primeiro ele cria uma thread e depois uma instância. O servidor enviará notificações de retorno do progresso (thread/started e turn/started). Também enviará de volta as entradas que registrar como itens, como a mensagem do usuário neste caso.

As chamadas de ferramentas também são enviadas de volta ao cliente como itens. Além disso, o servidor pode solicitar a aprovação do cliente antes de executar uma ação, enviando uma solicitação ao servidor. A aprovação interromperá o processamento até que o cliente responda com "permitir" ou "negar". Este é o aspecto do fluxo de aprovação na extensão do VS Code:

No final, o servidor envia uma mensagem ao agente e então encerra o turno com turn/completed. Os eventos delta da mensagem do agente transmitem partes da mensagem de volta até que a mensagem seja finalizada com item/completed.

As mensagens no diagrama foram simplificadas para facilitar a leitura. Se você quiser ver o JSON de uma rodada completa, pode executar o cliente de teste do repositório Codex CLI:

Agora, vamos analisar como diferentes interfaces de cliente incorporam o Codex por meio do Servidor de Aplicativos. Vamos abordar três padrões: aplicativos e IDEs locais, o ambiente de execução web Codex e a interface de usuário orientada a texto (TUI).

Nos três casos, o transporte é JSON-RPC sobre stdio (JSONL). JSON-RPC facilita a criação de interfaces de cliente na linguagem de sua escolha. As plataformas Codex e as integrações com parceiros implementaram clientes de servidor de aplicativos em linguagens como Go, Python, TypeScript, Swift e Kotlin. Para TypeScript, você pode gerar definições diretamente do protocolo Rust executando o seguinte comando:

Para outras linguagens, você pode gerar um pacote JSON Schema e inseri-lo no seu gerador de código preferido executando o seguinte comando:

Normalmente, os clientes locais agrupam ou obtêm um binário do servidor de aplicativos específico da plataforma, executam-no como um processo filho de longa duração e mantêm um canal stdio bidirecional aberto para JSON-RPC. Em nossa extensão para VS Code e aplicativo para desktop, por exemplo, o artefato fornecido inclui o binário Codex específico da plataforma e está fixado em uma versão testada, para que o cliente sempre execute exatamente os mesmos componentes que validamos.

Nem todas as integrações conseguem enviar atualizações para o cliente com frequência. Alguns parceiros, como o Xcode, desacoplam os ciclos de lançamento mantendo o cliente estável e permitindo que ele aponte para um binário de servidor de aplicativos mais recente quando necessário. Dessa forma, eles podem adotar melhorias no servidor (por exemplo, melhor compactação automática no núcleo do Codex ou novas chaves de configuração suportadas) e implementar correções de bugs sem esperar pelo lançamento de uma versão do cliente. A interface JSON-RPC do servidor de aplicativos foi projetada para ser compatível com versões anteriores, permitindo que clientes mais antigos se comuniquem com servidores mais recentes sem problemas.

O Codex Web utiliza a estrutura do Codex, mas a executa em um ambiente de contêiner. Um trabalhador provisiona um contêiner com o espaço de trabalho extraído, inicia o binário do Servidor de Aplicativos dentro dele e mantém um JSON-RPC de longa duração sobre o canal stdio². O aplicativo web (executado na aba do navegador do usuário) se comunica com o backend do Codex via HTTP e SSE, que transmite os eventos de tarefas produzidos pelo worker. Isso mantém a interface do usuário do lado do navegador leve, ao mesmo tempo que nos proporciona um desempenho consistente em desktops e na web.

Como as sessões da web são efêmeras (as abas fecham, as conexões de rede caem), o aplicativo web não pode ser a fonte de verdade para tarefas de longa duração. Manter o estado e o progresso no servidor significa que o trabalho continua mesmo que a guia desapareça. O protocolo de streaming e as sessões de threads salvas facilitam a reconexão de uma nova sessão, permitindo que ela retome de onde parou e recupere o atraso sem precisar reconstruir o estado no cliente.

Historicamente, a TUI era um cliente "nativo" que rodava no mesmo processo que o loop do agente e se comunicava diretamente com os tipos principais do Rust, em vez de usar o protocolo do servidor de aplicativos. Isso tornou as primeiras iterações rápidas, mas também fez da TUI uma superfície de caso especial.

Agora que o Servidor de Aplicativos existe, planejamos refatorar a TUI⁠(abre em uma nova janela) para usá-lo de forma que se comporte como qualquer outro cliente: iniciar um processo filho do Servidor de Aplicativos, comunicar-se via JSON-RPC sobre stdio e renderizar os mesmos eventos e aprovações de streaming. Isso possibilita fluxos de trabalho em que a TUI pode se conectar a um servidor Codex em execução em uma máquina remota, mantendo o agente próximo ao computador e permitindo a continuidade do trabalho mesmo se o laptop entrar em modo de suspensão ou se desconectar, enquanto ainda fornece atualizações e controles em tempo real localmente.

O Codex App Server continuará sendo o método de integração principal que manteremos daqui para frente, mas também existem outros métodos com funcionalidades mais limitadas. Por padrão, recomendamos que você use o Codex App Server para integrar com o Codex, mas vale a penCodexa analisar diferentes métodos de integração e entender seus prós e contras. A seguir, apresentamos as maneiras mais comuns de usar o Codex e quando cada uma delas pode ser uma boa opção.

Execute codex mcp-server⁠(abre em uma nova janela) e conecte-se a partir de qualquer cliente MCP que suporte servidores stdio (por exemplo, OpenAI Agents SDK⁠(abre em uma nova janela)). Essa é uma boa opção se você já possui um fluxo de trabalho baseado em MCP e deseja invocar o Codex como uma ferramenta chamável. A desvantagem é que você só obtém o que o MCP expõe, portanto, interações específicas do Codex que dependem de uma semântica de sessão mais rica (por exemplo, atualizações de diferenças) podem não ser mapeadas corretamente por meio dos endpoints do MCP.

Alguns ecossistemas oferecem uma interface portátil que pode ser direcionada a múltiplos provedores de modelos e ambientes de execução. Essa pode ser uma boa opção se você deseja uma abstração que coordene vários agentes. A desvantagem é que esses protocolos frequentemente convergem para um subconjunto comum de funcionalidades, o que pode dificultar a representação de interações mais complexas, especialmente quando a semântica específica da ferramenta e da sessão do provedor é importante. Este setor está evoluindo rapidamente e esperamos que padrões mais comuns surjam à medida que descobrirmos as melhores primitivas para representar fluxos de trabalho de agentes no mundo real (as habilidades⁠(abre em uma nova janela) são um bom exemplo disso).

Escolha o Servidor de Aplicativos quando desejar que toda a estrutura do Codex seja exposta como um fluxo de eventos estável e com interface amigável. Você obtém todas as funcionalidades do loop do agente, além de outros recursos de suporte, como login com ChatGPT, descoberta de modelos e gerenciamento de configuração. O principal custo é o trabalho de integração, já que você precisa criar a ligação JSON-RPC do lado do cliente na sua linguagem. Na prática, porém, o Codex consegue realizar grande parte do trabalho pesado se você fornecer a ele o esquema JSON e a documentação. Muitas equipes com as quais trabalhamos conseguiram implementar uma integração funcional rapidamente usando o Codex.

Um modo CLI leve e programável para tarefas pontuais e execuções de CI. É uma boa opção para automação e pipelines onde você deseja que um único comando seja executado até a conclusão de forma não interativa, transmita uma saída estruturada para logs e termine com um sinal claro de sucesso ou falha.

Uma biblioteca TypeScript para controlar programaticamente agentes Codex locais a partir de sua própria aplicação. É a melhor opção quando você deseja uma interface de biblioteca nativa para ferramentas e fluxos de trabalho do lado do servidor, sem precisar criar um cliente JSON-RPC separado. Como foi lançado antes do Servidor de Aplicativos, atualmente oferece suporte a menos idiomas e possui uma área de cobertura menor. Caso haja interesse por parte dos desenvolvedores, poderemos adicionar SDKs adicionais que encapsulem o protocolo do Servidor de Aplicativos, permitindo que as equipes explorem uma área maior da infraestrutura sem precisar escrever vinculações JSON-RPC.

Nesta postagem, compartilhamos como abordamos o design de um novo padrão para interagir com agentes e como transformar o framework do Codex em um protocolo estável e amigável para o cliente. Abordamos como o Servidor de Aplicativos expõe o núcleo do Codex, permite que os clientes controlem todo o ciclo do agente e oferece suporte a uma ampla gama de interfaces, incluindo a TUI (Interface de Usuário Texturizada), integrações com IDEs locais e o ambiente de execução web.

Se isso lhe deu ideias para integrar o Codex aos seus fluxos de trabalho, vale a pena experimentar o App Server. Todo o código-fonte está localizado no repositório⁠(abre em uma nova janela) de código aberto Codex CLI. Fique à vontade para compartilhar seus comentários e sugestões de novos recursos. Estamos ansiosos para ouvir sua opinião e continuar a tornar os agentes mais acessíveis a todos.