O que ver: oito ferramentas que, juntas, fazem um loop confiável. Não é uma de cada vez — é o kit montado. Cada seção abaixo é uma peça; um loop sólido tem todas encaixadas.
🎯 Objetivo checável
O ingrediente número um: defina "pronto" de um jeito que uma máquina consiga verificar — não "deixe bom". Se o próprio loop não tem como olhar o resultado e responder sim/não, ele nunca sabe quando parar.
Leia o diagrama: as oito peças não competem — elas se somam num loop só. Faltando uma das oito, o loop fica frágil exatamente naquele ponto.
✓ Checável por máquina
- ✓"Todo teste em /tests passa ao rodar
npm test." - ✓"Abaixo de 50 palavras E menciona o preço."
- ✓"O script roda sem erro e gera o CSV."
✗ Só você sabe avaliar
- ✗"Deixe bom."
- ✗"Melhore o texto."
- ✗"Limpe isso aqui."
🛑 Hard stop
Todo loop precisa de uma parada dura: máximo de tentativas, orçamento de tokens ou tempo. Sempre. É o que impede o agente de rodar para sempre quando não consegue atingir o objetivo.
# Três sabores de hard stop — escolha o que cabe na sua tarefa
Pare quando todos os testes passarem, OU após 10 tentativas. # máx. tentativas
Pare quando o objetivo for atingido, OU após gastar 50k tokens. # orçamento
Pare quando terminar, OU após 15 minutos de execução. # tempoComo verificar: leia seu prompt e ache a palavra "ou". Se não houver um teto além do objetivo, o loop não tem freio — adicione um antes de rodar.
🧠 Por que "sempre"
Um loop sem parada é a fonte número um de surpresas: ou ele fica preso repetindo a mesma correção, ou queima uma conta de tokens enquanto você dorme. O hard stop é barato de escrever e caro de esquecer.
🔧 Boas ferramentas
As ações que o agente pode tomar precisam ser confiáveis e claramente descritas. Uma ferramenta que falha silenciosamente, ou cujo nome não diz o que ela faz, vira ruído que confunde o loop.
💡 O artesanato está nas ferramentas
A Anthropic é direta: "é crucial projetar conjuntos de ferramentas e sua documentação com clareza". O loop em si é trivial — o trabalho de verdade está em quais ferramentas o agente tem e quão bem descritas elas estão.
✓ Ferramenta boa
- ✓Nome diz o que faz:
rodar_testes. - ✓Devolve o resultado real (saída, código de erro).
- ✓Falha de um jeito que o agente entende.
✗ Ferramenta ruim
- ✗Nome vago:
processar. - ✗Sucesso e falha parecem iguais.
- ✗Faz coisas demais de uma vez só.
🧠 Memória
Guarde o histórico do que já foi tentado — mas resuma, não acumule tudo. Um arquivo de notas curto que o agente relê é melhor que despejar cada passo de volta no contexto, que incha e fica caro.
🧩 Resumir > acumular
Um bom padrão: o agente mantém um PROGRESS.md com 3–5 linhas — o que já funciona, o que ainda falta, o que NÃO repetir. A cada volta ele relê esse resumo em vez do log inteiro. Memória que cabe num parágrafo sobrevive entre sessões; um histórico gigante não.
✅ Um checker separado
Separe quem faz de quem julga: gerar → julgar → consertar → repetir. O agente que produz o trabalho nunca deve dar a própria nota — um avaliador independente é muito mais honesto.
Leia o diagrama: o maker gera, o checker julga. Reprovou, volta para consertar; passou, está pronto. Como são papéis separados, o "passou" significa algo de verdade.
Por que o maker não deve dar a própria nota?
🗺️ Planejar primeiro?
Nem todo loop precisa de plano. Para um job grande e multi-passo, peça um plano antes de agir — assim o agente não se perde no meio. Para um job pequeno, pule o plano: ele só atrasa.
✓ Planeje primeiro quando…
- ✓A tarefa tem muitos passos dependentes.
- ✓Errar no começo custa caro lá na frente.
- ✓Você quer revisar o caminho antes do agente agir.
↩ Pule o plano quando…
- ·É uma correção pequena e direta.
- ·O caminho é óbvio: rodar → ler → consertar.
- ·Planejar gastaria mais que só fazer.
🧾 Logging
Salve cada pensamento, ação e resultado do loop. Quando algo der errado — e vai dar — o log é o que te deixa entender o que aconteceu, mesmo às 3 da manhã, sem ter assistido tudo ao vivo.
🔍 O log é sua câmera de segurança
Sem log, um loop que falhou é uma caixa-preta: você só vê o resultado quebrado, não o caminho até ele. Com log, você lê a sequência de decisões, acha onde virou errado e conserta a instrução — não a saída.
o que pensou
o que fez
o que deu
💸 Cost sense
Loops queimam tokens rápido — cada volta é uma chamada nova ao modelo. Comece pequeno e limitado: tarefa curta, poucas tentativas. Só depois que funciona, escale o escopo e o teto.
🧩 Pequeno primeiro, sempre
A intuição de custo importa porque o preço sobe de forma invisível: 10 voltas × contexto grande × modelo caro vira uma conta surpresa. Rode primeiro com max_turns baixo e tarefa pequena; veja quanto custou uma volta; e aí decida se vale escalar.
🚦 Faça isto / Pule isto (por enquanto)
✓ Faça
- ✓Comece com 1 tarefa pequena e repetível.
- ✓Faça "pronto" checável por máquina.
- ✓Sempre ponha um máximo de tentativas.
- ✓Use um 2º agente para avaliar trabalho importante.
✗ Pule por enquanto
- ✗Swarms 24/7 de 10 agentes promptando 10.
- ✗Rodar sem condição de parada.
- ✗Confiar em "parece pronto" sem check real.
- ✗Pôr em loop uma tarefa de uma vez só.
🧾 Resumo do Módulo
Próximo:
3.4 — Os 8 erros comuns