Desmontando o loop do agente do Codex

 (openai.com)
3 pontos por GN⁺ 2026-01-24 | 1 comentários | Compartilhar no WhatsApp
  • Codex CLI foi projetado como um agente que realiza alterações de software de alta qualidade com segurança e eficiência em ambientes locais
  • Sua estrutura central, o loop do agente (agent loop), conecta ciclicamente a entrada do usuário, a inferência do modelo e as chamadas de ferramentas para executar tarefas significativas
  • No processo do loop, a composição de prompts, a gestão da janela de contexto e o cache de prompts atuam como elementos centrais de desempenho e estabilidade
  • O Codex se comunica com o modelo por meio da Responses API, e cada requisição é composta por um payload JSON completo, mantendo um funcionamento sem estado (stateless)
  • Essa estrutura viabiliza recursos avançados como Zero Data Retention (ZDR), cache de prompts e compactação automática (compaction), formando a base para o projeto de agentes em larga escala

Visão geral do loop do agente do Codex

  • O Codex CLI funciona com foco em uma estrutura de loop que coordena a interação entre usuário, modelo e ferramentas
    • Recebe a entrada do usuário e monta o prompt a ser enviado ao modelo
    • Quando o modelo gera uma resposta ou solicita uma chamada de ferramenta (tool call), o agente executa essa ação e adiciona o resultado novamente ao prompt
    • Quando o modelo deixa de fazer chamadas de ferramenta e gera uma mensagem do assistant, um turno é encerrado
  • Cada turno faz parte de uma conversa (conversation), e tanto as mensagens anteriores quanto o histórico de chamadas de ferramentas são incluídos no prompt da próxima requisição
  • Como o tamanho do prompt é afetado pelo limite da janela de contexto (context window) do modelo, o Codex precisa gerenciá-la

Estrutura de comunicação entre a Responses API e o Codex

  • O Codex CLI envia requisições HTTP para a Responses API para realizar a inferência do modelo
    • O endpoint da API varia conforme a configuração, e pode ser usado em ambientes OpenAI, ChatGPT, Azure e locais (LM Studio, Ollama etc.)
  • A requisição da API é composta por um payload JSON, e os principais campos são os seguintes
    • mensagens system/developer: definem o contexto base do modelo
    • instructions: lista de ferramentas que o modelo pode chamar
    • tools: definições de ferramentas fornecidas pelo Codex CLI, pela Responses API e pelo usuário (como servidores MCP)
    • input: lista de mensagens que inclui o histórico da conversa e informações do ambiente
  • O Codex lê configurações em ~/.codex/config.toml e arquivos como AGENTS.md e skills dentro do projeto para inserir automaticamente instruções do usuário e informações do ambiente

Composição de prompts e tratamento de eventos

  • O Codex organiza cada mensagem como um objeto JSON (type, role, content) e o envia à Responses API
  • Com base nesse JSON, o servidor gera o prompt do modelo e retorna a resposta como um stream SSE (Server-Sent Events)
    • O evento response.output_text.delta é usado para saída em streaming
    • O evento response.output_item.added é adicionado ao input da próxima requisição para manter o loop em execução
  • O sistema é projetado para que o prompt anterior seja um prefixo exato do novo prompt, permitindo aproveitar o cache de prompts (prompt caching)

Otimização de desempenho: cache e arquitetura sem estado

  • O Codex não usa previous_response_id, mantendo uma estrutura de requisição totalmente sem estado (stateless)
    • Isso permite suporte a clientes com Zero Data Retention (ZDR) e minimiza a retenção de dados
  • O cache de prompts reutiliza o mesmo prefixo para linearizar o custo de amostragem
    • Um cache hit só ocorre quando há correspondência exata de prefixo no prompt
    • Mudanças na lista de ferramentas, no modelo, na configuração de sandbox ou no diretório de trabalho causam cache miss
  • Como mudanças dinâmicas nas ferramentas MCP podem causar perda de cache, o Codex reflete essas alterações inserindo novas mensagens

Gestão da janela de contexto e compactação automática (compaction)

  • Quando a conversa se alonga, o sistema executa compactação da conversa (compaction) para evitar ultrapassar a janela de contexto
    • No início, o resumo era feito manualmente com o comando /compact, mas agora usa automaticamente o endpoint /responses/compact da Responses API
    • Esse endpoint retorna itens do tipo type=compaction e encrypted_content criptografado para preservar a compreensão do modelo
  • O Codex executa a compactação automaticamente ao ultrapassar o auto_compact_limit, garantindo a continuidade da conversa

Conclusão e direção futura

  • O loop do agente do Codex é a estrutura central que integra inferência do modelo, chamadas de ferramentas, cache e gestão de contexto
  • Essa estrutura torna possível um projeto de agentes de alto desempenho, sem estado e com foco em segurança
  • Em posts futuros, a estrutura interna do Codex será abordada com mais detalhes, incluindo a arquitetura do CLI, a implementação do uso de ferramentas e o modelo de sandboxing

Leituras relacionadas

1 comentários

 
GN⁺ 2026-01-24
Comentários do Hacker News

  • O melhor deste post é que ele não tem nada de surpreendente. O Codex CLI é open source, então dá para olhar por dentro sem fazer engenharia reversa
    A comunicação do Eric Traut, um desenvolvedor conhecido pelo Pyright, também é excelente. Ele participa ativamente de issues e PRs
    Repositório no GitHub

    • Fiquei realmente surpreso quando o Codex CLI foi aberto como open source no ano passado. Ele também inclui o codex-rs, portado de TypeScript para Rust, então é muito útil para quem quer aprender como agentes de programação funcionam
      Eu também contribuí com algumas melhorias para o CLI e continuo acompanhando os releases e PRs para ampliar meu conhecimento
    • Muita gente parece não saber que o Claude Code é software proprietário
    • Sinceramente, acho que o motivo de o Claude Code não ser open source é que a qualidade do código é tão ruim que eles têm vergonha. Estou pagando uma assinatura de 200 dólares por mês, mas o CLI é lento e quebra com frequência, então devo cancelar em breve
    • Fico curioso se o Codex CLI é só um frontend que chama lógica remota, ou se consegue funcionar completamente offline. Também queria saber se eles fornecem os pesos sob licença FLOW e se documentaram o processo de build

  • O ponto interessante é que a compactação é feita como uma “mensagem criptografada que preserva o possível entendimento latente do modelo”
    Quando o Codex ultrapassa o auto_compact_limit, ele usa esse endpoint automaticamente para reduzir o contexto da conversa com eficiência

    • O endpoint de compactação do Codex é de nível líder de mercado. O do Claude chega perto de ser péssimo
    • Queria saber se dá para usar o endpoint compactor de forma independente. Temos um loop de agente específico para o nosso domínio, e o do Codex provavelmente teria desempenho melhor do que nosso próprio sistema de compactação
    • Também queria saber se isso funciona com modelos que não sejam da OpenAI

  • O que me surpreendeu ao olhar por dentro do Codex é que os tokens de reasoning são mantidos no loop de chamadas de ferramentas do agente, mas apagados sempre que o turno do usuário muda
    Então dá para manter contexto ao longo de vários turnos, mas algum contexto pode se perder entre pedidos relacionados do usuário
    Eu faço o modelo registrar progresso, plano e debug em um arquivo Markdown para funcionar como uma espécie de snapshot entre várias janelas de contexto

    • Isso depende da rota da API. Em chat completions funciona do jeito que você falou, mas na responses v1 API é o contrário. Os tokens de reasoning continuam quando você envia a próxima mensagem. Só que o modo xhigh consome contexto muito mais rápido
    • Não manter os tokens de reasoning pode até ser uma boa decisão. Caso contrário, contexto invisível para o usuário iria se acumulando e haveria risco de desalinhamento entre o entendimento do modelo e o do usuário
    • Eu criei uma Codex Reflect Skill para refletir conversas passadas e construir contexto em sessões paralelas
      Repositório no GitHub
    • Guardar registros junto com o código é prático, mas causa problemas em ambiente de equipe ou quando se trabalha em vários branches ao mesmo tempo. No próximo experimento, pretendo separar esses dados em um daemon com storage externo e acessá-los por um cliente CLI
    • Eu uso bastante o agent-shell do emacs, que salva todo o histórico da conversa. Assim fica fácil dizer “considere a conversa anterior”. Quem faz o log é o emacs, não o agente, então não preciso me preocupar com omissões

  • O que eu realmente quero no Codex é um recurso de checkpoints no estilo Copilot. Há algumas issues sobre isso no GitHub (#2788, #3585), mas parece que não é prioridade da equipe

    • O Gemini CLI já tem isso
    • A equipe do Codex diz que define prioridades pela quantidade de upvotes com emoji no GitHub. Se houver algum recurso que você queira, vale a pena dar upvote

  • Tenho curiosidade sobre como eles gerenciam a manutenção de contexto ao agregar instruções do usuário no loop do agente, especialmente em conversas de vários turnos. Também queria saber se já testaram técnicas de ajuste dinâmico quando as exigências do usuário mudam

  • Gosto do Codex, mas ele parece mais lento do que a interface web do ChatGPT. Quando quero trocar ideias rapidamente, ainda sou mais produtivo copiando e colando pela web
    O Codex frequentemente começa a mexer no código errado, então o loop de feedback fica lento e frustrante. Ainda assim, quando funciona bem, é excelente. Espero que um dia chegue ao ponto de ser tão rápido quanto a web, mas com trabalho local

    • Na interface web do ChatGPT Plus, o modo de xhigh reasoning effort do modelo 5.2 não está disponível

  • Não foi um texto particularmente novo, mas ainda assim foi valioso. Seria bom se CLIs de programação com agentes facilitassem mais refletir sobre loops ou histórico. Já tentei consultar histórico de chat via MCP, mas é incômodo porque precisa ser especificado explicitamente. Aprendizado contínuo talvez resolva esse tipo de problema

  • Esse comportamento também pode ser observado com telemetria OTEL. Eu uso bastante o codex exec em modo headless, mas a falta de suporte interno de telemetria dificulta o debug
    Por isso acabei criando o codex-plus para uso próprio. Ele espelha a interface do codex exec, foi implementado sobre o SDK em TypeScript e, após a execução, exporta logs de sessão para um coletor remoto de OpenTelemetry, permitindo análise com o codex-plus-log-viewer

  • A parte que descreve skills me pareceu estranha
    Link do código relacionado
    Fiquei me perguntando por que eles simplesmente não expõem o arquivo diretamente, em vez de fazer o modelo solicitá-lo como se fosse um arquivo comum

    • Esse é justamente o ponto principal das skills. A estrutura serve para abrir só os arquivos relevantes, reduzindo o uso da janela de contexto

  • Eu me perguntava se alguém realmente usava o Codex CLI de forma séria. Já usei a extensão Codex para VSCode, Gemini CLI e Claude Code CLI, e todos tinham desempenho horrível.
    Mas o novo Codex CLI refeito em Rust é absurdo de rápido. A UX também é impecável, até nos detalhes como atalhos. O Theo disse que eles deveriam ter focado em melhorar o modelo em vez de otimizar o CLI, mas depois de usar eu não consigo concordar nem um pouco

    • Acho o Codex CLI muito melhor do que o Claude Code. Ele segue instruções com precisão e não faz coisas que você não quer. Com a assinatura de 20 dólares por mês dá para usar bastante o modelo 5.2 codex high. Eu trabalho com modelos bioacústicos para SSL
    • O OpenCode também é mais rápido e estável do que outros CLIs. Tenho usado mais o Codex ultimamente e devo cancelar o Claude Pro. O fato de a OpenAI dar suporte oficial ao OpenCode é atraente. É bom ver várias opções competitivas agora
    • O Codex entrega resultados consistentes em mais de 95% das tarefas de programação. Mas em tarefas não estruturadas — como conversa ou escrita de histórias — às vezes gera saídas esquisitas. Já fiquei preso em loop durante um git rebase. Testei o Aider, mas achei quase inútil
    • A eficiência de memória e CPU do Codex CLI é muito boa. Além disso, por ser open source, dá para verificar diretamente como ele funciona. Ainda assim continuo incomodado com a fala do Theo
    • O problema do Codex é que ainda não há suporte a hooks. Eu criei uma ferramenta usando hooks para reduzir em 30% o consumo de tokens do agente. Com hooks, dá para corrigir em tempo real comportamentos ineficientes do agente
      Artigo relacionado: Scribe Swebench Benchmark