autosearch-hitl: um agente que otimiza sozinho, mas só decide por número

Ajustar tempero de comida segue um loop simples: prova, muda um pouco, prova de novo, decide se ficou melhor ou pior. É repetitivo, mas depende do seu paladar, porque só você consegue dizer o que conta como “melhor”.

Boa parte do trabalho de engenharia de software segue esse mesmo ciclo: muda uma coisa, roda o teste, olha o número, decide manter ou desfazer, repete. Reduzir o tempo de resposta de uma API. Fazer uma busca achar a resposta certa com mais frequência. Cortar o tempo que a suíte de testes leva pra rodar. É tedioso e repetitivo. Exatamente o tipo de trabalho que um agente faz bem, desde que “melhorou” vire um número em vez de palpite.

É esse o problema que a autosearch-hitl resolve. HITL é sigla pra human-in-the-loop, humano no loop. O nome carrega a decisão de design inteira: o agente faz a parte chata (testar, medir, repetir) e você mantém a parte que importa (o que pode ser mudado, o que conta como sucesso, quando parar de vez).

Antes de deixar o agente mexer em qualquer coisa

A skill se recusa a começar se faltar uma de quatro coisas, e explica o porquê em vez de tentar otimizar no escuro:

1. Algo concreto pra mudar. A instrução dada ao modelo (o prompt), um parâmetro, um trecho de código ou uma configuração.
2. Um número que diz melhor ou pior. Latência em milissegundos, nota de um teste, percentual de acerto: precisa ter direção clara.
3. Um jeito repetível de medir esse número. Rodar o mesmo teste duas vezes tem que dar o mesmo tipo de resultado.
4. Um jeito de desfazer. Se a mudança piorou, precisa dar pra voltar exatamente pro estado anterior.

Sem essas quatro coisas, “otimizar” vira só mexer sem saber se ajudou. A skill prefere parar e te ajudar a montar a métrica antes de gastar uma única tentativa.

O loop, por dentro

Com as quatro condições garantidas, o ciclo é sempre o mesmo, e sempre isolado do seu trabalho:

Ponto a ponto do desenho:

1. Separa uma cópia isolada. Em código, isso é uma pasta de trabalho paralela (tecnicamente chamada de git worktree) que nunca encosta na sua versão principal do projeto. Você pode continuar trabalhando normalmente enquanto o agente testa ideias do lado.
2. Mede o ponto de partida. Roda a métrica uma vez, sem mudar nada, pra ter um número de referência. Se a métrica não produzir um número válido aqui, o processo já para: sinal de que a pré-condição 3 não tava tão garantida quanto parecia.
3. Tenta uma ideia, mede de novo. Melhorou? Fica, vira um commit (um checkpoint salvo daquela versão). Piorou? Desfaz, tenta a próxima.
4. Para quando estagna. Depois de várias tentativas seguidas sem ganho, encerra sozinho, em vez de continuar gastando tempo e custo atrás de melhoria que não vem.
5. Te entrega a decisão final. Um relatório do que funcionou e do que não funcionou, e uma versão separada das mudanças pronta pra você revisar e decidir se quer incorporar ao projeto principal. O agente nunca decide sozinho que a mudança vai pra produção.

A ideia central (mudar, medir, manter ou descartar) vem do Andrej Karpathy, do projeto autoresearch, pensado pra otimizar treino de modelo. O que fiz foi generalizar o loop pra qualquer coisa que tenha uma métrica. A maior parte do trabalho de engenharia tem.

Onde já rodou de verdade

A wiki que escreve sozinha

A mesma do post anterior tinha um problema: o prompt que instrui o agente-escritor produzia páginas ok, mas nem sempre boas. Às vezes sem os links cruzados certos, às vezes resumindo mal. Montamos uma métrica objetiva o bastante pra comparar versões: outro modelo lê a página gerada e dá uma nota de 0 a 100, olhando fidelidade ao conteúdo, links cruzados e qualidade da síntese. A autosearch-hitl testou variações do prompt contra essa nota:

• Ponto de partida: 66,5
• Depois de 7 tentativas, só as mudanças que valiam a pena ficaram: 79,75
• Uma tentativa seguinte foi longe demais: um prompt mais agressivo melhorou a nota do juiz, mas por baixo dos panos passou a inventar links pra páginas que não existiam, travando a publicação. A nota sozinha não pegava isso. A correção veio na tentativa seguinte (pedir pra tentar de novo com o erro explicado, mais uma regra contra links inventados, mais limpeza automática de qualquer link inválido que escapasse) e levou a nota final pra 81,5.

Isso importa porque mostra o processo funcionando nos dois sentidos: quando uma ideia piora as coisas, mesmo de um jeito sutil como inventar links, a métrica pega e o loop corrige, em vez de empacar numa versão quebrada.

A busca que errava a resposta

Num serviço de busca em documentação, o problema era mais direto: a resposta certa nem sempre aparecia em primeiro lugar nos resultados. A métrica usada foi MRR (Mean Reciprocal Rank): mede se a resposta certa aparece logo no primeiro resultado ou se a pessoa precisa rolar a página pra achar. Testamos 8 ideias diferentes de ajuste na busca; a métrica descartou 4 delas na hora: pareciam boas, mas pioravam o número. Das 4 que sobraram, o resultado final foi +162% de MRR. A resposta certa passou a aparecer em primeiro lugar na maioria das buscas.

Em outros dois casos o mesmo processo rodou até estagnar, sem supervisão: numa API de pagamento, testou variações de cache (guardar resposta pronta pra não recalcular) e paralelização (rodar passos ao mesmo tempo) até cortar 46% do tempo de resposta sem piorar o comportamento esperado nos testes; numa suíte de testes, reordenou e paralelizou casos até cortar 57% do tempo de execução sem perder cobertura (a parte do código que os testes exercitam).

Onde ele para de propósito

O ponto não é deixar o agente livre pra otimizar qualquer coisa. É o oposto: ele só entra em ação depois que você define exatamente o que pode mudar e exatamente o que conta como sucesso. Ele nunca decide sozinho que uma mudança está pronta pra valer. Se você pedir “deixa esse código melhor” sem dizer o que “melhor” significa, a resposta é montar a métrica com você antes, em vez de adivinhar.

Essa é a diferença entre automação que rouba controle e automação que devolve tempo: o agente absorve a parte repetitiva do trabalho, e a decisão de valor continua sendo sua.

A skill é pública, dá pra instalar com npx skills add iagogfe/autosearch-hitl, e o código está no GitHub. A ideia vale mesmo pra quem nunca vai instalar: se “melhor” puder virar um número confiável, dá pra automatizar a tentativa e erro sem automatizar a decisão de valor.