🔄 O ciclo do agente

O modelo de IA, sozinho, só sabe uma coisa: ler texto e escrever texto. Ele não abre arquivo, não roda programa, não navega em site. Alguém precisa dar mãos a ele.

Esse "alguém" é o harness, palavra inglesa para arreio. É o programa que prende o modelo a um conjunto de ferramentas e o faz trabalhar em ciclo. O Codex é um harness: o modelo é o cérebro, o Codex é o corpo com as mãos.

Como ler o desenho: o círculo verde é o modelo, que só pensa. O anel tracejado azul é o Codex, que liga o modelo às quatro ferramentas dos cantos. Sem o anel, o modelo seria só um chat.

Quando você manda um pedido, o Codex não sai escrevendo a resposta. Primeiro ele pensa no que precisa. Depois escolhe uma ferramenta e a usa. Olha o resultado. Pensa de novo.

Esse vaivém se repete até ele ter o que precisa. Só então ele responde. Um pedido simples pode levar uma volta; um pedido grande pode levar dezenas.

Como ler o desenho: o triângulo azul gira enquanto falta informação. Quando, ao pensar, ele conclui que já tem tudo, sai pela seta verde e escreve a resposta. A resposta é o último passo, nunca o primeiro.

O ciclo não é escondido. No aplicativo, perto da resposta, aparece uma linha curta com algo como "trabalhou por 25 s". Clicando nela, o registro se abre.

Ali você vê o raciocínio resumido e cada ação, na ordem: que arquivo ele leu, que comando rodou, que conversa anterior consultou. O texto exato e o lugar da linha podem mudar entre versões, mas o registro está sempre por perto da resposta.

Como ler o desenho: o quadro verde é o registro aberto. Leia de cima para baixo: é a ordem real em que ele pensou e agiu. A resposta cinza embaixo é só o resultado final dessa sequência. O desenho é um esboço, não a tela exata.

O registro não serve só para conferir. Ele ensina. Veja que arquivos o agente abre e em que ordem. Isso mostra como ele "enxerga" a sua pasta.

Se ele abre cinco arquivos errados antes do certo, falta uma linha no mapa de rotas. Se ele procura algo que não existe, falta um arquivo na pasta. O Rui descobriu assim que nunca tinha salvo a tabela de preços de fornecedor.

Como ler o desenho: cada ponto é uma leitura, na ordem em que aconteceu. Vermelho é desvio, verde é acerto, amarelo é busca por algo que não está lá. Os quadros embaixo dizem o que corrigir em cada caso.

No registro, às vezes aparece uma leitura de "memória". Não confunda com o AGENTS.md. São duas coisas diferentes, e cada uma tem o seu lugar.

Regras dizem como trabalhar: "propostas em uma página". Memórias são fatos lembrados: "a Paula prefere reuniões às terças" ou "a cliente Acme pediu desconto em setembro". Regra é manual; memória é caderno de anotações.

Como ler o desenho: o quadro verde guarda o jeito de trabalhar e quase não muda. O caderno azul guarda fatos e cresce com o uso. Os dois alimentam o mesmo pensamento, mas você edita cada um por um motivo diferente.

O que olhar na tabela: se a frase diz "faça" ou "nunca faça", é regra. Se conta algo que aconteceu ou que é verdade sobre alguém, é memória ou dado de cliente. Dados importantes de cliente merecem arquivo próprio na pasta.

Hora de ver o ciclo com os próprios olhos. O melhor pedido para isso é um que obrigue o Codex a buscar dados, porque cada busca vira uma volta visível no registro.

O Rui usou a planilha de estoque da loja. Ele não quer só a lista: quer ver como o agente chegou nela. Faça igual com um arquivo seu.

Leia o arquivo estoque.csv e liste os 5 itens com menos de 10 unidades, do menor para o maior. Para cada item, mostre nome, quantidade e fornecedor. No fim, diga em uma frase quais arquivos você abriu para chegar nessa lista. Não altere nenhum arquivo.

Como ler o desenho: cada degrau é uma volta do ciclo que aparece no registro. A resposta só chega no topo, depois da última conferência. No seu teste, o número de degraus pode ser outro: o importante é ver a leitura do arquivo antes da resposta.