O que é engenharia de loops em agentes de IA?

O que significa engenharia de loops

Engenharia de loops é a prática de projetar o ciclo repetitivo executado por um agente de IA: o que o desperta, quais recursos ele pode acessar, como sua saída é verificada e o que o interrompe. Engenharia de prompts molda uma mensagem enviada a um modelo. Engenharia de loops molda o processo que envia milhares de mensagens enquanto você dorme. A unidade de trabalho deixa de ser o prompt e passa a ser o loop.

Em resumo: você deixa de escrever instruções e passa a escrever um sistema de controle. O agente ainda precisa de boas instruções, mas elas se tornam um componente de um ciclo executado conforme um cronograma, que trabalha em uma cópia isolada do seu código, comprova o próprio resultado com um teste e desiste quando o orçamento se esgota.

Por que o termo surgiu em 2026

O nome está sendo consolidado publicamente agora. O repositório do GitHub cobusgreyling/loop-engineering ultrapassou 9,600 estrelas em dois meses após seu surgimento (em julho de 2026), com a frase "Pare de criar prompts. Projete o loop. Obtenha uma pontuação." Ele reúne essa mudança em seis blocos de construção: agendamento, worktrees, skills, plugins e conectores, subagentes e memória persistente mantida fora da conversa.

O texto cita Boris Cherny, que lidera o Claude Code na Anthropic:

Não crio mais prompts para o Claude. Tenho loops em execução que criam prompts para o Claude.

Um segundo repositório, AI-Builder-Club/skills, está próximo de 1,100 estrelas (em julho de 2026) e nomeia diretamente as duas funções: um "harness de código" que torna um repositório seguro para que um agente execute testes e deploys nele, e um "engenheiro de loops" que cria workflows que são ativados por um gatilho, executam o trabalho e gravam o que aprenderam em um arquivo compartilhado para que o próximo loop possa lê-lo.

Nenhum dos dois repositórios inventou essa prática. Quem já executou um build noturno, um linter em integração contínua ou um cron job que abre um ticket já conhece esse formato. A novidade é que o worker dentro do loop agora é não determinístico. Isso muda o que a infraestrutura ao redor precisa fazer.

As quatro partes de um loop

Todo loop funcional tem estas quatro partes. Um loop que ignora uma delas é o loop que acorda você às 3am.

• Gatilho. O evento que inicia uma execução: um timer, um webhook, um novo pull request, um alerta.
• Limite. Os arquivos, as credenciais e a rede que o agente pode acessar durante essa execução.
• Verificação. Uma checagem com um código de saída que decide se a saída da execução será mantida ou descartada.
• Orçamento. O limite de tokens, tempo e dinheiro que encerra uma execução, tenha ela sido bem-sucedida ou não.

Transforme essas quatro partes em perguntas, e você terá uma revisão de projeto para qualquer agente que esteja prestes a deixar em execução.

Gatilho: o que desperta o agente

Um timer é o gatilho mais simples. Em um servidor Linux, um timer do systemd é melhor que o cron nesse caso porque registra eventos, tenta novamente conforme as suas regras e não inicia uma segunda cópia de uma unit que ainda está em execução. Essa última propriedade elimina o problema de sobreposição mais comum nos loops de agentes: duas execuções editando a mesma branch.

Grave a unit em /etc/systemd/system/agent-loop.service:

[Unit]
Description=Agent loop: triage open issues
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=agent
WorkingDirectory=/srv/agent/repo
ExecStart=/srv/agent/bin/loop.sh
TimeoutStartSec=1800

E o timer em /etc/systemd/system/agent-loop.timer:

[Unit]
Description=Run the triage loop every 30 minutes

[Timer]
OnBootSec=5min
OnUnitActiveSec=30min
Unit=agent-loop.service

[Install]
WantedBy=timers.target

sudo systemctl daemon-reload
sudo systemctl enable --now agent-loop.timer
systemctl list-timers agent-loop.timer

systemctl list-timers deve mostrar uma coluna NEXT com um horário futuro e uma coluna LEFT com a contagem regressiva. Um resultado vazio significa que o timer não está habilitado, porque enable sem --now o agenda somente para a próxima inicialização. TimeoutStartSec=1800 é mais importante do que parece: sem ele, um agente que fique bloqueado aguardando entrada manterá a unit ativa indefinidamente, e o timer nunca será executado novamente. Leia uma execução com journalctl -u agent-loop.service -n 50.

Se você executar o loop pelo cron, adicione sua própria proteção contra sobreposição, porque o cron iniciará uma segunda cópia sem hesitar:

*/30 * * * * /usr/bin/flock -n /tmp/agent-loop.lock /srv/agent/bin/loop.sh

flock -n sai imediatamente com o status 1 quando o lock está mantido. Assim, a segunda execução termina silenciosamente em vez de disputar recursos com a primeira. A mesma configuração de serviço e timer do systemd se aplica a qualquer job de longa duração no servidor, seja um agente ou não.

Limite: dê a cada execução sua própria cópia

Um agente que edita sua árvore de trabalho pode perder seu trabalho não confirmado. As árvores de trabalho do Git resolvem isso de forma simples: cada execução recebe seu próprio diretório e sua própria branch, compartilhando o mesmo armazenamento de objetos.

cd /srv/agent/repo
git worktree add -b loop/triage-01 /srv/agent/work/triage-01 origin/main
git worktree list

git worktree list imprime uma linha por árvore, com seu caminho, commit e branch. Quando a execução termina, git worktree remove /srv/agent/work/triage-01 exclui o diretório, e git worktree prune limpa as entradas cujo diretório desapareceu. Os loops paralelos tornam-se seguros nesse ponto, porque dois agentes em duas branches e dois diretórios não podem sobrescrever o trabalho um do outro.

O limite também se aplica às credenciais. Um loop executado sem supervisão mantém tokens de longa duração, e cada execução pode vazá-los em um log, commit ou contexto do modelo. Restrinja o token ao único repositório que o loop acessa, mantenha-o fora do ambiente visível para o próprio shell do agente sempre que possível e leia como manter segredos fora dos agentes de IA antes de conceder acesso de produção a um loop. Para uma barreira mais forte, execute o loop inteiro em uma VM descartável que você possa destruir após cada execução.

Verificação: o controle que torna o loop seguro

Esta é a parte que diferencia um loop de um cron job que apenas digita. A saída do agente é uma proposta. O controle decide.

#!/usr/bin/env bash
set -euo pipefail

repo=/srv/agent/repo
branch="loop/$(date -u +%Y%m%dT%H%M%SZ)"
tree="/srv/agent/work/$(basename "$branch")"

cd "$repo"
git fetch --quiet origin
git worktree add -b "$branch" "$tree" origin/main
cd "$tree"

# the agent's own command runs here, in non-interactive mode

if ! npm test; then
  echo "gate failed: discarding $branch" >&2
  cd "$repo"
  git worktree remove --force "$tree"
  exit 1
fi

git push origin "$branch"
cd "$repo"
git worktree remove "$tree"

set -euo pipefail está executando uma função real nesse script. Sem -e, um git fetch com falha é ignorado e a execução continua usando um origin/main desatualizado. Sem -u, um erro de digitação no nome de uma variável é expandido para uma string vazia, e a limpeza é executada no caminho errado em vez de falhar de forma explícita.

O bloco if ! npm test contém toda a ideia. O código de saída de uma verificação em que você já confia, sua suíte de testes ou seu verificador de tipos, decide se a ramificação é enviada ou destruída. Um loop sem controle produz trabalho que ninguém tem tempo de revisar, o que é pior do que não produzir trabalho. Um loop com controle produz uma ramificação que já passou pelo mesmo padrão que a ramificação de um colaborador humano precisa passar.

Escolha um controle que falhe de forma confiável. Uma suíte de testes que passa com um diff vazio ensina ao loop que não fazer nada é um sucesso. Repositórios com testes fracos geram loops fracos. Por isso, os repositórios em destaque colocam "tornar a base de código pronta para agentes" antes de "escrever o loop".

Orçamento: o que interrompe uma execução

Um agente que tenta novamente para sempre é um agente com uma cobrança sem limite. Defina para cada loop um limite de tempo de relógio, imposto por TimeoutStartSec acima; uma contagem de tentativas dentro do seu script; e um limite de gastos imposto pela conta do provedor. Depois, registre quanto custou cada execução, para identificar o desvio de um loop antes que ele apareça na fatura. Controle de custos de um VPS com agente sempre ativo aborda o controle contábil, e gerenciamento do contexto mantido por um agente entre turnos aborda o maior fator individual do custo por execução, porque um loop que relê o mesmo repositório a cada 30 minutos paga por isso a cada 30 minutos.

O custo é o motivo pelo qual os loops geralmente são melhores do que uma sessão longa. Uma execução que começa do zero, realiza uma tarefa específica e termina mantém o contexto pequeno. Uma sessão deixada aberta por oito horas mantém todos os erros anteriores no histórico e cobra por toda a transcrição a cada turno.

Os padrões codificados pelos repositórios em destaque

O repositório loop-engineering lista sete padrões de produção, e vale a pena lê-los como um menu, não como um manifesto. Triagem diária. Um agente que acompanha pull requests, monitora comentários de revisão e responde a eles. Um agente de integração contínua que coleta builds com falha. Um agente de atualização de dependências. Um redator de changelogs. Limpeza pós-merge. Triagem de issues.

O que eles têm em comum é uma tarefa restrita com um critério de aprovação claro. "Corrigir o build com falha" tem uma condição de aprovação que a máquina consegue ler. "Melhorar a base de código" não tem, portanto nunca se transforma em um loop. Transforma-se em uma tarefa desorganizada com um cronograma.

Eles também têm em comum um registro escrito. Ambos os repositórios tiram o estado da conversa e o colocam em arquivos no repositório: o que foi executado, o que foi encontrado e o que foi decidido. Esse arquivo é a memória do loop e permite que um segundo loop continue o trabalho do primeiro em vez de redescobri-lo. Ele também é a forma de auditar um agente posteriormente, porque o contexto do modelo desaparece assim que a execução termina.

Onde os loops falham

As falhas são previsíveis e se repetem entre as equipes.

• Sem controle. A saída se acumula, ninguém a revisa, a confiança desaparece e o loop é desativado.
• Sobreposição. Duas execuções na mesma branch ou dois agentes na mesma working tree produzem conflitos que o agente então tenta resolver.
• Desvio silencioso. O loop continua passando porque a verificação é fraca demais para falhar.
• Escopo ilimitado. Um gatilho que é acionado a cada commit em um repositório movimentado se transforma em um problema de custos em um dia.

Todos têm a mesma correção: reduza o trabalho, torne a verificação mais rigorosa e registre a execução. Se você não consegue descrever a condição de aprovação em uma frase, o trabalho ainda não está pronto para ser automatizado.

Primeiros passos sem o vocabulário

Você não precisa de um framework. Um pequeno servidor Linux sempre ativo, um repositório git cuja suíte de testes falha quando deveria, um timer do systemd e um script de shell com um if formam um ciclo completo. Esse é realmente o ponto de partida recomendado para a maioria das pessoas, porque as questões de design são respondidas ao executar o sistema, e não ao escolher uma ferramenta. Depois que um ciclo estiver estável, executar um segundo consiste principalmente em usar outro timer e outro worktree. Consulte como executar um agente de IA para programação em um VPS para obter a configuração básica e as opções atuais de agentes de IA self-hosted se quiser executar o próprio agente em hardware sob seu controle.

FAQ

A engenharia de loop é diferente da engenharia de prompts?

A engenharia de prompts otimiza uma mensagem: redação, exemplos e formato da saída. A engenharia de loop otimiza o ciclo em torno da mensagem: o gatilho que inicia uma execução, o sandbox em que ela é executada, a verificação que aceita ou rejeita a saída e o orçamento que a encerra. Você ainda precisa de um bom prompt dentro do loop. O prompt deixa de ser o elemento ajustado diariamente, porque o gate e o gatilho têm mais efeito sobre o resultado.

Preciso de um framework para criar um loop de agente?

Não. Um timer do systemd, um git worktree por execução, um script de shell que termina com um comando de teste e um limite de gastos na conta do provedor cobrem todas as partes da definição. Os frameworks adicionam interfaces de agendamento, formatos de memória compartilhada e roteamento entre vários agentes, que são úteis quando você executa vários loops. Eles não são um requisito de entrada para o primeiro loop.

O que é um harness de codebase?

É o conjunto de recursos que permite a um agente trabalhar em um repositório sem a presença de uma pessoa: uma configuração executada com um comando, testes executados de forma não interativa e que falham claramente, um linter e uma forma de fazer deploy ou visualizar uma alteração. O termo surgiu na mesma onda de 2026 de repositórios que trouxe a engenharia de loop. O teste prático é simples: se um novo contribuidor humano não consegue passar do clone até os testes verdes com um comando, um agente também não consegue.

Como impeço um loop de agente de gerar uma conta alta?

Defina limites em três lugares. Configure TimeoutStartSec na unidade do systemd para que uma execução travada seja encerrada. Limite as tentativas dentro do script, em vez de repetir até obter sucesso. Defina um limite rígido de gastos na conta da API, pois esse é o único teto que o agente não pode contornar com argumentos. Depois, registre o custo por execução, porque um loop cujo custo dobra geralmente é um loop cujo escopo aumentou silenciosamente.

Quais tarefas vale a pena transformar primeiro em um loop?

Escolha uma tarefa com uma condição de aprovação legível por máquina e um raio de impacto pequeno. Corrigir um build com falha, atualizar uma dependência e gerar novamente um changelog atendem a esses critérios, porque uma suíte de testes ou um diff pode comprovar o resultado. Trabalhos abertos, como refatoração ou design, ainda não atendem a esses critérios, pois não há nada que o gate possa verificar, e um loop sem gate é uma forma cara de gerar dívida de revisão.