Análise do funcionamento interno do OpenAI Codex CLI: loop do agente e estratégia de cache de prompt

Resumo:

• Estrutura do loop do agente (Agent Loop): explica em detalhes o processo cíclico pelo qual o Codex CLI coordena entrada do usuário, inferência do modelo e execução de ferramentas (Tool) para realizar tarefas reais.
• Composição de prompt e Responses API: analisa o processo e o fluxo de dados pelos quais instruções de sistema, definições de ferramentas e contexto do ambiente local são convertidos em payloads JSON da Responses API.
• Otimização de desempenho e gerenciamento de estado: aborda estratégias para maximizar o cache de prompt (Prompt Caching), técnicas de compactação de conversa (Compaction) para superar limitações da janela de contexto e princípios de design sem estado (Stateless) para ZDR (Zero Data Retention).

Resumo detalhado:
A equipe de engenharia da OpenAI publicou um artigo técnico que analisa em profundidade o princípio de funcionamento do "loop do agente (Agent Loop)", a lógica central do Codex CLI, um agente de software local. O texto descreve, de uma perspectiva técnica, todo o ciclo de vida de receber o comando do usuário, interagir com o modelo, executar ferramentas e retornar os resultados.

1. Loop do agente (The Agent Loop)

O loop do agente é uma estrutura cíclica que recebe a entrada do usuário e interage com o modelo até concluir a tarefa.

• Processo: entrada do usuário -> geração do prompt -> inferência do modelo (Inference) -> repetição de (solicitação de chamada de ferramenta -> execução da ferramenta -> anexação do resultado -> nova inferência) -> resposta final.
• Turno (Turn): o processo que vai da entrada do usuário até o momento em que o modelo finalmente envia uma mensagem ao usuário (Assistant Message) é chamado de um "turno". Nesse processo, o agente pode realizar centenas de chamadas de ferramenta, como executar ls ou editar arquivos.

2. Inferência do modelo e Responses API

O Codex CLI se comunica com o modelo por meio da Responses API. Essa API pode ser configurada como https://chatgpt.com/backend-api/codex/responses, https://api.openai.com/v1/responses ou um host local, como o Ollama.

Construção do prompt inicial (Building the Initial Prompt)

O prompt não é um texto simples, mas um dado estruturado composto por instructions, tools, input etc.

• Instructions: mensagens de sistema ou de desenvolvedor que definem as diretrizes de comportamento do modelo. (Ex.: referência ao arquivo de configuração ~/.codex/config.toml)
• Tools: lista de definições de ferramentas que o modelo pode usar. Inclui execução de shell, atualização de plano (update_plan), busca na web e ferramentas de servidores MCP (Model Context Protocol) personalizados.
• Input: lista de dados reais enviados ao modelo. Inclui configurações de permissões do sandbox, instruções específicas do projeto e o contexto do ambiente (Environment Context), como diretório de trabalho atual (cwd) e tipo de shell.

Exemplo de payload JSON:

{  
  "type": "message",  
  "role": "user",  
  "content": [  
    {  
      "type": "input_text",  
      "text": "README.md에 아키텍처 다이어그램을 추가해줘"  
    }  
  ]  
  // ... contexto do ambiente, configurações de permissão etc. definidos anteriormente também são enviados juntos  
}  
  

3. Execução de ferramentas e fluxo de dados

Quando o modelo solicita uma chamada de ferramenta (Function Call), o agente a executa, adiciona o resultado ao histórico da conversa e chama o modelo novamente.

Exemplo de JSON de nova solicitação após a execução da ferramenta:

[  
  /* ... itens de entrada anteriores ... */  
  {  
    "type": "reasoning", // processo de raciocínio do modelo (CoT)  
    "summary": [...],  
    "encrypted_content": "gAAAAABpaDW..." // conteúdo de raciocínio criptografado  
  },  
  {  
    "type": "function_call",  
    "name": "shell",  
    "arguments": "{\"command\":\"cat README.md\",\"workdir\":\"/Users/mbolin/code/codex5\"}",  
    "call_id": "call_8675309..."  
  },  
  {  
    "type": "function_call_output", // resultado da execução da ferramenta  
    "call_id": "call_8675309...",  
    "output": "<p align=\"center\"><code>npm i -g @openai/codex</code>..."  
  }  
]  
  

É importante estruturá-lo para que o prompt anterior seja um prefixo exato (Prefix) do novo prompt. Isso determina a eficiência do cache de prompt, discutida a seguir.

4. Considerações de desempenho: cache e ZDR

À medida que a conversa se alonga, o tamanho do prompt cresce linearmente, aumentando custo e latência.

• Cache de prompt (Prompt Caching): os modelos da OpenAI reutilizam resultados de computação anteriores para acelerar o processo quando a parte inicial do prompt coincide (Prefix Match).

• Prevenção de cache miss: se mudanças na lista de ferramentas ou nas configurações do sandbox ocorrerem no meio da conversa, o cache pode ser invalidado. Para evitar isso, o Codex trata mudanças de configuração não editando mensagens existentes, mas por meio da abordagem de adicionar novas mensagens (Append).

• Sem estado (Stateless) e ZDR: em vez de usar parâmetros como previous_response_id, o contexto completo é enviado todas as vezes. Isso é para cumprir a política de Zero Data Retention (ZDR), que não armazena dados no servidor. Ao receber o conteúdo de raciocínio criptografado (encrypted_content) no cliente e enviá-lo novamente ao servidor, o servidor consegue restaurar o contexto de raciocínio anterior sem armazenar estado.

5. Gerenciamento da janela de contexto (Compaction)

Para não ultrapassar o limite de tokens, o Codex usa o endpoint /responses/compact para compactar o histórico da conversa. Em vez de um simples resumo, ele recebe uma lista de itens compactados que inclui encrypted_content, preservando a compreensão latente do modelo (Latent understanding), e substitui as entradas existentes por essa lista.

[iolothebard]

O Claude Code já estava na documentação oficial desde o começo…

[iolothebard]

https://code.claude.com/docs/en/how-claude-code-works