A fundo no loop do agente Codex: lições dos 28 dias de lançamento do Sora para Android e do Datadog

O Codex entregou o aplicativo Android do Sora com quatro engenheiros em 28 dias. No Datadog, hoje mais de mil engenheiros dependem dele para capturar defeitos de nível de sistema que os revisores humanos costumavam deixar passar. Ambas as histórias vêm da mesma arquitetura: um loop de controle aparentemente simples, envolvendo um modelo de linguagem, um conjunto de ferramentas e um ambiente de sandbox.

Se você está construindo um assistente de programação com IA, um pipeline de geração de mídia ou qualquer agente que precise agir sobre o mundo, o loop do agente Codex é a referência mais limpa que você pode estudar hoje. Este artigo percorre por completo como ele funciona, o que as equipes de produção realmente fazem com ele, e como o mesmo padrão arquitetural pode migrar para agentes de geração de mídia que você pode construir sobre o hiapi.

Este artigo se baseia nos artigos públicos de engenharia da OpenAI: "Desdobrando o loop do agente Codex" (janeiro de 2026), o estudo de caso do Datadog e a retrospectiva de entrega do Sora para Android. Os preços da plataforma Hiapi citados abaixo são de 2026-06.

O que é afinal o loop do agente

O loop do agente é o fluxo de controle entre você, o modelo de linguagem e as ferramentas que o modelo tem permissão de chamar. Da perspectiva do usuário, um "turno" parece apenas uma mensagem de chat entrando e uma mensagem de chat saindo. Mas, nos bastidores, um único turno pode conter várias idas e voltas entre o modelo e ferramentas externas.

A forma de um turno:

1. Preparar o prompt. O agente monta o prompt de sistema, as instruções de nível de projeto (no Codex, arquivos AGENTS.md), o histórico da conversa e a nova mensagem do usuário.
2. Inferência. O modelo retorna a mensagem final do assistente ou uma chamada de ferramenta.
3. Se for uma chamada de ferramenta, o agente executa essa chamada no sandbox, captura o resultado, o acrescenta à conversa e volta ao passo 2.
4. Se for a mensagem final do assistente — algo como "já adicionei o architecture.md que você pediu" — o turno termina e o controle volta ao usuário.

A característica fundamental é que a "saída" não é apenas a mensagem do assistente que você vê no terminal. A maior parte da saída real são os efeitos colaterais das chamadas de ferramenta: arquivos escritos, testes executados, pacotes instalados. A mensagem do assistente é apenas o sinal de término.

É por isso que o loop do agente não é apenas "um chat com alguns passos a mais". O chat faz apenas uma ida e volta por turno. O loop do agente pode completar dezenas de ciclos de "inferência → ferramenta → inferência" dentro de um único turno, e o usuário só vê a mensagem final.

Três características que tornam o loop rápido

A implementação ingênua do loop acima funciona, mas depois de alguns turnos fica lenta e cara. O design do Codex resolve esse problema com três ideias que vale a pena tomar emprestado.

1. Cache de prefixo na Responses API. Toda vez que o agente conversa com o modelo, o prompt começa com o mesmo prefixo longo: primeiro o prompt de sistema, depois o AGENTS.md, depois a conversa inicial. A primeira requisição calcula e armazena em cache o estado interno de chave-valor do modelo correspondente a esse prefixo. Requisições subsequentes na mesma sessão pulam o recálculo de qualquer prefixo compartilhado.

Uma consequência prática: não edite o AGENTS.md no meio da sessão. O prompt de sistema costuma ser o maior bloco único de cache, e alterá-lo invalida o cache do restante da sessão. Os próprios engenheiros do Codex listam isso como a causa mais comum de lentidão "procurada a dedo".

2. Os resultados das chamadas de ferramenta ficam dentro do loop, não sobrepostos a ele. Cada saída de ferramenta é acrescentada à mesma conversa. Parece óbvio, mas significa que o modelo tem memória completa de cada comando que executou, cada erro que viu, cada arquivo que inspecionou — sem que você precise fazer qualquer resumo manual. O custo é que a janela de contexto cresce rápido; o Codex lida com isso por compactação automática quando a conversa fica longa demais.

3. A terminação é detectada pela forma da saída do modelo, não por contagem de turnos. O agente não tem uma rede de segurança de número máximo de iterações. Enquanto o modelo continuar emitindo chamadas de ferramenta, ele continua em loop; assim que o modelo emite uma mensagem normal do assistente, ele para imediatamente. Essa decisão é entregue ao modelo, o que mantém o código de orquestração enxuto.

Caso um: o Datadog usa o loop para revisão de código em nível de sistema

O caso de divulgação do Datadog é mais útil porque mostra em que o loop do agente se destaca em produção e em que não se destaca.

A equipe de experiência de desenvolvimento com IA do Datadog queria um agente de revisão de código capaz de encontrar o tipo de defeito que os revisores humanos deixam passar — não lint, não estilo, mas regressões entre serviços, quedas de desempenho e mudanças que reproduziriam falhas reais. Eles observaram que a maioria das ferramentas anteriores se comportava como um "linter avançado". Elas só marcavam padrões superficiais dentro de um único diff. Não tinham modelo do sistema ao redor.

Para validar o agente antes da divulgação, a equipe construiu um arcabouço de testes de reprodução de falhas: reconstruíram os pull requests que haviam causado falhas passadas, alimentaram cada um deles no Codex como se fossem revisões recém-chegadas, e então perguntaram aos engenheiros de plantão se o comentário do Codex teria mudado o resultado.

O resultado divulgado foi: o Codex forneceu feedback novo útil em cerca de 22% das falhas históricas — mais do que qualquer outra ferramenta que a equipe havia avaliado. Como cada pull request já havia passado por revisão humana na época, esse teste essencialmente mede "o que os revisores deixaram passar naquele momento".

Hoje, mais de 1.000 engenheiros do Datadog o usam em cada PR. Os engenheiros respondem aos comentários com 👍/👎 e ou alteram o código, ou anexam uma justificativa para ignorar a sugestão. A escolha de design interessante é que o Datadog mede o impacto por canais laterais — engenheiros que publicam no Slack mencionando descobertas úteis — e não por métricas formais dentro da ferramenta. A equipe trata o agente como meio de amplificação, não como porteiro; ele apresenta sinais, e o humano continua decidindo.

O padrão a tomar emprestado: o loop do agente se destaca em raciocinar em todo o escopo do sistema (dependências, testes, serviços relacionados), e não apenas sobre o diff imediato. Isso exige dar a ele as ferramentas certas e as permissões de leitura certas. O loop do agente é o chassi; a superfície de ferramentas e o contexto do projeto é que determinam se ele consegue apresentar risco real.

Caso dois: entregar o Sora para Android em 28 dias

A história do Sora para Android é uma prova ainda mais radical. Entre 8 de outubro e 5 de novembro de 2025, uma equipe de quatro engenheiros usou o Codex para levar o Sora de "apenas iOS" a um lançamento público para Android — ciclo de 28 dias, com uma versão interna para funcionários no 18º dia e lançamento público dez dias depois. O aplicativo chegou ao topo da Google Play Store; os usuários criaram mais de um milhão de vídeos nas primeiras 24 horas. Taxa livre de crashes no lançamento: 99,9%.

A equipe falou francamente sobre o que funcionou e — mais útil ainda — sobre o que não funcionou.

O que não funcionou foi o prompt óbvio: "Construa o aplicativo Sora para Android com base no código iOS. Comece." Eles tentaram e abortaram rapidamente. O artefato era tecnicamente utilizável, mas a experiência do produto era fraca. Nas palavras deles, o Codex "ainda não é bom em inferir aquilo que não lhe foi dito" e tem dificuldade em fazer "julgamento arquitetural profundo" sem orientação.

O que funcionou foi tratar o Codex como um tradutor semântico entre plataformas e montar um andaime forte ao redor dele:

• Primeiro estabeleceram os padrões arquiteturais do projeto — navegação, injeção de dependência, rede — e escreveram à mão alguns recursos de exemplo. Esses definiram o padrão para o restante da base de código.
• Usaram arquivos AGENTS.md para codificar as convenções da equipe, mantendo a saída do Codex consistente.
• Frequentemente pediam ao Codex que consultasse o código iOS em Swift e o backend existente, exigindo que gerasse Kotlin semanticamente equivalente. O resumo deles foi: "o futuro do cross-platform é o Codex".
• Trataram o Codex como um "engenheiro sênior recém-contratado" — humanos responsáveis pela arquitetura, design de sistema e experiência do usuário; o Codex assumindo o trabalho pesado dentro de escopos bem definidos.

Segundo relatos, o código gerado pelo Codex representou cerca de 85%, e o projeto consumiu um orçamento de aproximadamente 5 bilhões de tokens em quatro semanas.

Há duas lições aqui que são fáceis de subestimar. Primeira, a qualidade do agente é limitada pela qualidade do andaime que você monta: exemplos, AGENTS.md, escopo claro. Segunda, para projetos greenfield, "equipe pequena mais agente competente" supera "aumentar o número de engenheiros" — a observação de Fred Brooks finalmente encontrou um contra-exemplo nas mãos certas.

Os padrões transferíveis

Despidos dos detalhes específicos de revisão de código e entrega para Android, restam quatro padrões que qualquer equipe construindo agentes deveria copiar.

Estabeleça os padrões antes de escalar. Seja o padrão de navegação (Sora), seja o que conta como "mudança arriscada" (Datadog), o trabalho humano acontece no início. Recursos de exemplo e um AGENTS.md estável são como você transmite esses padrões para cada turno seguinte — e eles são exatamente o que o cache de prefixo recompensa.

Dê ao agente a superfície de ferramentas certa, não a maior superfície de ferramentas. O revisor do Datadog precisa ler entre serviços. O tradutor do Sora precisa ler o código-fonte iOS e o backend. Ambas as equipes curaram cuidadosamente a superfície de leitura. Uma lista de ferramentas maior não é melhor.

Deixe os humanos responsáveis pela arquitetura e o agente pela implementação. Ambos os estudos de caso convergem para essa divisão. Os humanos definem as decisões estruturais; o agente preenche dentro de escopos bem definidos. Inverter essa divisão é onde as equipes desperdiçam tempo.

Meça por resultados, não por métricas de ferramenta. O Datadog observa deliberadamente as reações no Slack e os resultados de falhas, e não a taxa de saída do próprio agente. Isso mantém o objetivo de otimização honesto. Uma ferramenta de revisão de código que faz muitos comentários mas não muda o comportamento de falhas não é uma ferramenta útil.

Aplicando o loop a agentes de geração de mídia

A arquitetura do loop do agente não é exclusiva de código. Em qualquer lugar onde você precisa que o modelo aja, observe e itere, o mesmo fluxo de controle se aplica.

A plataforma hiapi expõe todos os modelos de geração de mídia por meio de um endpoint assíncrono unificado — POST /v1/tasks cria uma tarefa de geração, GET /v1/tasks/:id coleta o resultado — então o passo de "ação" no loop é uma função de duas chamadas que você escreve uma vez e reutiliza entre todos os modelos. Concretamente, você pode construir um agente de produção de vídeo cujo loop seja assim:

1. O agente recebe um briefing: "Crie uma tomada de produto de 6 segundos, um relógio sobre mármore."
2. Ele monta o prompt e cria uma tarefa seedance-2-0 via POST /v1/tasks, depois consulta o ID da tarefa até a conclusão (em 2026-06, na plataforma hiapi, 480P custa US$ 0,15 por segundo de vídeo, e 720P tem fator de 2,2x — o clipe de 6 segundos acima custa US$ 0,90 em 480P).
3. Ele baixa o vídeo gerado, executa um passo rápido de avaliação — "o mostrador está realmente visível? A iluminação está de acordo com o briefing?" — e então aceita a saída ou modifica o prompt.
4. Se a avaliação falhar N vezes seguidas, o agente escala para o usuário, anexando o melhor resultado até então e uma descrição do problema.

A mesma forma se aplica a agentes de geração de imagem: briefing → chamada de texto para imagem (por exemplo, gpt-image-2 a US$ 0,03 por imagem em 1K, ou Nano-Banana-2 a US$ 0,085 em 1K) → inspeção visual → modificação → nova tentativa. O padrão do Codex de "prompt de sistema estável para cache de prefixo e saídas de chamadas de ferramenta acumulando na conversa" se aplica diretamente: coloque a definição de papel e as diretrizes de marca no prompt de sistema, e deixe o loop acumular cada tentativa de geração e avaliação como turnos na mesma thread.

Algumas conversões práticas ao migrar a experiência do Codex para agentes de mídia:

• O AGENTS.md vira o arquivo de diretrizes de marca. Estável, carregado uma única vez, nunca editado no meio da sessão. Isso é exatamente o que o cache de prefixo recompensa.
• Os recursos de exemplo viram saídas de referência. Imagens curadas à mão mostrando "com o que se parece um bom resultado", para o passo de avaliação comparar.
• O sandbox vira limites de taxa e de gastos. Um agente de mídia que não aprendeu quando parar pode acumular um monte de gerações. Defina um teto de gastos por turno, assim como o Codex limita por padrão as gravações no sistema de arquivos.
• O sinal de término é exatamente o mesmo. O loop termina quando o passo de avaliação retorna "aceitar" em vez de mais uma solicitação de geração.

Se você quiser testar primeiro os modelos fundamentais por trás desse tipo de loop, sem escrever a lógica de orquestração por enquanto, a página de preços do hiapi lista os preços atuais por imagem e por segundo de vídeo, e as páginas de detalhes de cada modelo têm um Playground, para você rodar um prompt antes de decidir o que conectar ao agente.

FAQ

O que é o loop do agente Codex?

É o fluxo de controle dentro do Codex CLI que orquestra a interação entre você, o modelo e as ferramentas que o modelo tem permissão de chamar. Cada "turno" pode conter internamente vários ciclos de inferência do modelo → chamada de ferramenta, terminando quando o modelo emite uma mensagem normal do assistente em vez de outra chamada de ferramenta.

Por que o cache de prefixo é tão importante para agentes?

Porque cada turno reenvia um prefixo longo — prompt de sistema, instruções de projeto, histórico da conversa. Sem cache, o modelo recodifica tudo isso a cada requisição, o que é lento e caro. Com cache, o prefixo compartilhado é calculado uma vez e reutilizado nos turnos seguintes da mesma sessão. A implicação prática: não edite as instruções de projeto (como o AGENTS.md) no meio da sessão, porque isso invalida o cache do restante da sessão.

Quantos engenheiros são necessários para entregar algo como o Sora para Android?

Os números divulgados pela OpenAI são quatro engenheiros, 28 dias, com o Codex gerando, segundo relatos, cerca de 85% da base de código e o projeto inteiro consumindo cerca de 5 bilhões de tokens. A equipe escolheu explicitamente se manter pequena — citando a lei de Brooks de que "adicionar pessoas a um projeto já atrasado o atrasa ainda mais" — e apoiou-se no agente para a implementação.

O que o Codex realmente capturou na avaliação do Datadog?

No método de "reprodução de falhas" da equipe, eles reexecutaram pelo Codex PRs que historicamente causaram falhas e perguntaram aos engenheiros de plantão se o feedback teria mudado o resultado. O Codex forneceu feedback acionável em cerca de 22% das falhas — por exemplo, questões como regressões entre serviços e mudanças de desempenho, que os revisores humanos deixaram passar quando o PR foi originalmente mergeado.

Posso usar o mesmo padrão de loop de agente para geração de imagem ou vídeo?

Sim. O padrão arquitetural — preparar o prompt, chamar o modelo, executar ferramentas, acrescentar resultados, repetir até a terminação — é independente do modelo. Você pode conectá-lo aos endpoints de geração de mídia do hiapi (modelos de imagem como gpt-image-2 ou nano-banana-2, modelos de vídeo como seedance-2-0) e seguir as mesmas lições: prompt de sistema estável para o cache de prefixo, exemplos para garantir qualidade, limites de gastos no sandbox para garantir segurança, e um passo de avaliação para determinar a terminação.

O que devo colocar no AGENTS.md?

Especificamente para o Codex: convenções do projeto, comandos de build/teste/lint, regras de estilo de código e quaisquer fronteiras de "não mexa". As equipes divulgadas do Sora e do Datadog o trataram como o documento de onboarding do agente — as coisas que você contaria a um engenheiro sênior no primeiro dia. Mantenha-o estável durante a sessão, para que ele permaneça no cache de prefixo.

Principais conclusões

• O loop do agente Codex é um fluxo de controle simples: preparar o prompt → inferência do modelo → chamada de ferramenta opcional → acrescentar resultado → repetir, até o modelo emitir uma mensagem normal do assistente.
• Três detalhes de implementação o levam ao nível de produção: cache de prefixo, resultados de chamadas de ferramenta mantidos dentro da conversa, e detecção de terminação guiada pela forma da saída do modelo.
• O Datadog usa esse loop para revisão de código em nível de sistema para mais de 1.000 engenheiros; seu arcabouço de testes de reprodução de falhas mostra que o Codex capturou cerca de 22% das questões relacionadas a falhas históricas que os revisores humanos haviam deixado passar.
• A OpenAI entregou o aplicativo Sora para Android com quatro engenheiros em 28 dias, com cerca de 85% do código gerado pelo Codex e taxa livre de crashes no lançamento de 99,9% — contando com um andaime pesado de exemplos e AGENTS.md, e não com o prompt "vá construir"
• Essa mesma arquitetura de loop de agente pode migrar de forma limpa para os pipelines de geração de mídia que você pode construir no hiapi: cada modelo de texto para imagem e texto para vídeo usa a mesma forma assíncrona /v1/tasks, e as jogadas do Codex em cache de prefixo, sandbox e exemplos podem ser mapeadas uma a uma para agentes de imagem e vídeo.