O Que o Agent Loop do Codex Revela Sobre Construir Agentes de IA em Produção

A OpenAI publicou recentemente o primeiro de uma série de artigos de engenharia que dissecam os internos do Codex CLI, o agente de desenvolvimento de software open-source deles. Escrito por Michael Bolin, o artigo cobre o agent loop — a lógica central de orquestração que conecta usuários, modelos e ferramentas. O código-fonte está disponível em github.com/openai/codex, escrito em Rust.

Não é um anúncio de produto. É um dos raros casos em que um laboratório de IA de fronteira publica detalhes reais de engenharia sobre como o agente funciona em produção. Para times construindo sistemas agênticos, as lições aqui vão além do stack específico da OpenAI.

O Loop em Si É Simples. A Engenharia ao Redor Não É.

Todo agente de IA segue o mesmo padrão básico: receber entrada do usuário, consultar um modelo, executar chamadas de ferramentas se solicitado, alimentar os resultados de volta ao modelo, repetir até o modelo retornar uma mensagem final. O Codex não é diferente.

O que importa é o que o Codex faz ao redor desse loop para torná-lo performático e confiável em escala.

Composição do Prompt: Quatro Camadas de Contexto

Cada chamada de inferência à Responses API inclui três campos de alto nível: instructions, tools e input. O input é montado a partir de múltiplas fontes:

1. Instruções de permissão (role developer) — descrição do sandbox, pastas graváveis, políticas de aprovação
2. Instruções do desenvolvedor (role developer) — instruções customizadas do config.toml
3. Instruções do usuário (role user) — agregadas de arquivos AGENTS.md encontrados entre a raiz do git e o diretório atual, mais metadados de skills
4. Contexto do ambiente (role user) — diretório de trabalho atual, tipo de shell
5. Mensagem do usuário — a solicitação em si

Os roles seguem uma hierarquia de prioridade: system > developer > user > assistant. Essa estrutura permite governança em camadas, onde regras de segurança da plataforma não podem ser sobrescritas por instruções de projeto do usuário.

O Problema Quadrático e o Cache de Prompt

Aqui está o insight não óbvio. Sem otimização, o agent loop é quadrático no total de JSON enviado à API ao longo de uma conversa. Cada chamada de inferência inclui o histórico completo, e cada chamada adiciona mais conteúdo a esse histórico.

O cache de prompt converte isso para custo linear. A restrição-chave: cache hits só funcionam com correspondência exata de prefixo. Isso significa que o início do prompt deve permanecer idêntico entre chamadas. Conteúdo estático (instruções, ferramentas, ambiente) vai primeiro. Conteúdo dinâmico (chamadas e resultados de ferramentas) é anexado no final.

Isso tem consequências reais de engenharia:

• Enumeração de ferramentas MCP deve ser determinística. O Codex descobriu um bug (PR #2611) onde ferramentas MCP eram listadas em ordem inconsistente, causando cache misses em cada chamada de inferência.
• Mudanças de configuração no meio da conversa são anexadas, não substituídas. Se o sandbox ou diretório de trabalho muda, o Codex adiciona uma nova mensagem em vez de modificar uma anterior, preservando o prefixo de cache.
• Mudanças na lista de ferramentas MCP durante a conversa são caras. A notificação notifications/tools/list_changed do MCP pode invalidar o cache inteiro.

Compactação de Contexto: Não É Apenas Resumo

Quando a conversa excede um limite de tokens, o Codex usa um endpoint dedicado /responses/compact. Isso não resume simplesmente a conversa em linguagem natural. Retorna uma lista de itens incluindo um encrypted_content opaco que preserva o entendimento latente do modelo — o que significa que a representação compactada retém informação que um resumo textual perderia.

O trade-off: a compactação introduz um atraso de processamento e o agente perde acesso explícito a detalhes de chamadas de ferramentas anteriores. Mas mantém sessões longas funcionais em vez de estourar limites de contexto.

Stateless por Design

O Codex não usa o parâmetro previous_response_id que a Responses API oferece para gerenciamento de estado no servidor. Cada requisição é completamente stateless. Isso simplifica a arquitetura e habilita configurações Zero Data Retention (ZDR), mas ao custo de enviar o JSON completo da conversa em cada chamada.

Os tokens de raciocínio de turnos anteriores são preservados via encrypted_content — o servidor armazena a chave de descriptografia, mas não os dados em si. É uma solução pragmática para clientes enterprise que precisam tanto de continuidade de conversa quanto de compliance de dados.

O Que Isso Significa para Times de Engenharia

1. Arquitetura de Prompt com Consciência de Cache É Obrigatória

Se você está construindo um agent loop, cache de prompt não é otimização — é requisito. Sem isso, custos e latência crescem quadraticamente. Isso significa:

• Mantenha system prompt, ferramentas e instruções estáveis entre chamadas
• Enumere ferramentas em ordem determinística
• Anexe em vez de modificar quando o contexto muda

2. MCP É Poderoso mas Introduz Fragilidade de Cache

O Model Context Protocol permite extensibilidade poderosa de ferramentas, mas introduz um modo de falha sutil: se um servidor MCP muda sua lista de ferramentas no meio da conversa, você perde o cache de prompt inteiro. Times adotando MCP devem agrupar mudanças de ferramentas e evitar registro dinâmico durante conversas ativas.

3. Agnosticismo de LLM Tem Limites

O Codex CLI é projetado para funcionar com qualquer provedor que implemente a Responses API — incluindo modelos locais via Ollama ou LM Studio. Porém, os system prompts específicos por modelo (ex: gpt-5.2-codex_prompt.md) e o encrypted_content opaco para tokens de raciocínio sugerem que performance completa requer modelos da OpenAI. Modelos locais executarão o loop, mas podem não ter o treinamento especializado que torna o agente eficaz em tarefas de software.

4. O Agent Loop É a Parte Fácil

O padrão do loop (input -> inferência -> chamada de ferramenta -> repetir) é bem compreendido. A engenharia difícil está no gerenciamento de contexto: decidir o que vai no prompt, manter eficiência de cache, lidar com compactação de forma elegante e garantir operação stateless. Essas são preocupações de infraestrutura, não de IA.

5. Transparência Open Source Define um Novo Padrão

Publicar o harness completo do agente com links para linhas de código específicas, PRs e decisões de design é valioso. Permite que a comunidade aprenda com engenharia de produção real, não abstrações de marketing. Outros construtores de agentes — Anthropic com Claude Code, Cursor, Windsurf — enfrentam pressão para equiparar esse nível de transparência.

Perspectiva Crítica

Aspectos que o artigo não aborda:

• Recuperação de erros. O que acontece quando uma chamada de ferramenta falha? Quando o modelo produz JSON malformado? Quando uma compactação perde contexto crítico? O artigo descreve o caminho feliz.
• Métricas de confiabilidade. Nenhum dado sobre taxas de sucesso, taxas de erro ou estratégias de recuperação.
• Custo. O design stateless significa enviar a conversa completa em cada chamada. Para sessões longas com muitas chamadas de ferramentas, isso acumula.
• Dependência de modelo. Apesar do enquadramento LLM-agnóstico, a arquitetura está profundamente acoplada à spec da Responses API da OpenAI. Trocar para um formato de API diferente requer adaptação significativa.

Essas não são críticas ao artigo — ele se posiciona explicitamente como primeiro de uma série, com sandboxing e implementação de ferramentas vindo depois. Mas engenheiros não devem tratá-lo como guia completo para construir agentes em produção.

Conclusão

O artigo sobre o agent loop do Codex é mais valioso como estudo de caso de engenharia em gerenciamento de contexto em escala. As lições centrais — design de prompt com consciência de cache, enumeração determinística de ferramentas, atualizações de contexto append-only, compactação em espaço latente — são aplicáveis a qualquer time construindo sistemas de IA agêntica, independente de qual provedor de LLM usem.

O padrão do agent loop é conhecimento commodity. A engenharia que o faz funcionar em produção não é.

---

Fonte: Unrolling the Codex Agent Loop por Michael Bolin, OpenAI Engineering, 23 de janeiro de 2026.