Guia prático de harness para testar prompts, modelos e fluxos de IA

Um harness ajuda a transformar testes soltos com IA em uma execução repetível. Ele não garante qualidade sozinho, mas permite rodar os mesmos casos, comparar versões, registrar resultados e perceber regressões antes de confiar só na sensação de que "ficou melhor".

Contexto

Nos últimos guias da série, a ideia foi avançar aos poucos pela estrutura de uma funcionalidade com IA.

Primeiro, RAG: quando a aplicação precisa buscar contexto externo antes de responder. Depois, chunking, embeddings e retrieval: como preparar e recuperar esse contexto com mais critério.

Em seguida, respostas estruturadas: quando a saída do modelo precisa virar dado validável para o sistema. Depois, evals: como definir casos, critérios e formas de comparar se uma mudança realmente melhorou.

Mas ainda fica uma pergunta prática: como rodar esses testes de forma repetível? É aqui que entra o harness.

O nome parece mais sofisticado do que precisa ser. No contexto deste guia, harness é só uma forma organizada de executar testes: pegar um conjunto de casos, rodar uma versão do prompt, modelo ou fluxo, guardar as respostas e comparar os resultados.

O problema

Testar IA manualmente é útil. Quando você está explorando um prompt novo, faz sentido abrir o chat, tentar exemplos, observar respostas e ajustar a instrução.

O problema aparece quando esse teste solto vira o único critério: mudei o prompt, testei uma entrada, a resposta ficou bonita, pareceu melhor, então aprovei a mudança.

Isso é frágil. Talvez aquele caso tenha melhorado, mas outro tenha piorado. Talvez a resposta esteja mais polida, mas menos fiel ao contexto. Talvez o modelo novo respeite o formato e ignore uma regra importante.

• O que exatamente mudou?
• Quais casos foram testados?
• A comparação usou as mesmas entradas?
• A versão anterior também passava nesse caso?
• Houve regressão?
• Alguém conseguiria repetir esse teste depois?

Modelo mental

Um jeito simples de pensar em harness é separar eval de execução. O eval responde o que será avaliado. O harness responde como essa avaliação será rodada de forma repetível.

1casos de teste2  -> runner3  -> respostas registradas4  -> comparação de versões5  -> decisão

Os casos representam situações importantes para a funcionalidade. O runner executa os casos, chamando o prompt, modelo, função ou fluxo que você quer avaliar. As respostas registradas permitem comparar o que aconteceu em cada versão.

Em vez de "testei no chat e gostei", a pergunta passa a ser: rodei os mesmos casos na versão nova e na versão anterior. O que mudou?

Harness não é garantia de qualidade

Um harness não deixa a IA confiável por mágica. Ele não substitui bons critérios, revisão humana, observabilidade ou validação com uso real.

O que ele faz é mais modesto e mais útil: cria uma forma repetível de observar comportamento. Isso já muda bastante a conversa.

• qual entrada foi usada;
• qual versão do prompt rodou;
• qual modelo respondeu;
• quais parâmetros estavam ativos;
• qual contexto foi enviado;
• qual resposta voltou;
• qual critério passou ou falhou;
• qual decisão foi tomada.

Quando usar um harness

Nem todo experimento precisa de harness. Se você está só estudando uma ideia, explorando possibilidades ou fazendo uma prova de conceito muito inicial, testar manualmente pode ser suficiente.

Um harness começa a fazer mais sentido quando a mudança precisa ser comparada com algum cuidado.

• Mudar um prompt usado em uma funcionalidade importante.
• Comparar dois modelos para a mesma tarefa.
• Ajustar chunking, retrieval ou contexto enviado ao modelo.
• Testar uma resposta estruturada com schema.
• Adicionar ou modificar fallback.
• Avaliar uma classificação automática.
• Investigar uma regressão percebida por usuários.
• Evitar que uma correção quebre casos que já funcionavam.

Como começar pequeno

Um harness inicial pode ser bem simples. Imagine uma funcionalidade fictícia que recebe mensagens de suporte e retorna intenção, prioridade, resumo, próxima ação sugerida e indicação de revisão humana.

1Para cada caso:2  1. enviar a entrada para a versão atual do prompt3  2. salvar a resposta4  3. enviar a mesma entrada para a nova versão5  4. salvar a resposta6  5. comparar com os critérios definidos

Na primeira versão, a comparação pode ser manual. Isso não é um problema. O ganho inicial está em rodar os mesmos casos e registrar as respostas.

O que registrar

Logs são uma parte importante de um harness. Não precisa começar com observabilidade completa, mas alguns campos ajudam muito quando algo muda.

• Caso: identifica qual entrada foi testada.
• Versão: separa prompt, modelo ou fluxo testado.
• Modelo e parâmetros: registram a configuração usada.
• Contexto: indica se houve RAG ou dados externos.
• Resposta: permite comparação posterior.
• Erro: registra falha de schema, timeout ou exceção.
• Avaliação: marca passou, falhou ou precisa revisar.
• Observação: guarda o raciocínio da decisão.

Isso evita um problema comum: perceber que uma resposta mudou e não saber por quê. Talvez tenha sido o prompt, o modelo, o retrieval, a temperatura ou um fallback acionado.

Exemplo prático

Vamos imaginar dois prompts para uma funcionalidade fictícia de triagem de suporte. O objetivo é melhorar a identificação de urgência sem marcar tudo como urgente.

1Não consigo acessar minha conta desde ontem.2Tentei redefinir a senha, mas o e-mail não chega.3Preciso entrar hoje porque tenho uma reunião importante.

Os critérios esperados são: intenção de login, prioridade alta, menção à falha no e-mail de redefinição, encaminhamento rápido e nenhuma causa técnica inventada.

1{2  "intencao": "login",3  "prioridade": "media",4  "resumo": "Usuário está com problema de acesso à conta.",5  "proxima_acao": "Enviar instruções para redefinir senha.",6  "precisa_revisao_humana": false7}

1{2  "intencao": "login",3  "prioridade": "alta",4  "resumo": "Usuário não consegue acessar a conta e não recebe o e-mail de redefinição de senha. Há urgência por causa de uma reunião no mesmo dia.",5  "proxima_acao": "Verificar envio do e-mail de redefinição e encaminhar para atendimento humano se o acesso for necessário no mesmo dia.",6  "precisa_revisao_humana": true7}

Para esse caso, a prompt-v2 parece melhor. Mas o harness não para aqui. Ele roda outros casos para ver se a nova versão começou a marcar cobrança simples como urgente, ficou longa demais ou passou a pedir revisão humana em situações desnecessárias.

Uma resposta isolada mostra um exemplo. Um harness mostra comportamento ao longo de vários exemplos.

Comparação entre versões

Um harness fica mais útil quando você controla o que está comparando. Se possível, mude uma coisa por vez: prompt A contra prompt B, modelo atual contra modelo novo, retrieval antigo contra retrieval ajustado.

1Data: 2026-07-142Objetivo: comparar prompt-v1 e prompt-v2 para triagem de suporte3Casos: 124Modelo: modelo atual da aplicação5Parâmetros: temperatura 0.26Mudança principal: instrução mais clara para urgência e revisão humana7Resultado: prompt-v2 melhorou 5 casos, manteve 4, piorou 38Decisão: ajustar prompt-v2 antes de aprovar9Observação: nova versão tende a marcar cobrança como urgente com facilidade demais

Esse tipo de anotação preserva o raciocínio. Quando alguém revisar a mudança depois, não precisa adivinhar por que ela foi aprovada ou rejeitada.

Regressão é o motivo principal

Uma das maiores utilidades de um harness é encontrar regressão. Em funcionalidades com IA, regressão nem sempre parece bug óbvio.

• O JSON continua válido, mas o conteúdo ficou pior.
• O resumo ficou mais curto, mas perdeu uma informação importante.
• A resposta está mais educada, mas menos objetiva.
• O modelo segue melhor o formato, mas inventa uma justificativa.
• O retrieval recupera menos ruído, mas também perde contexto útil.
• O fallback aparece com mais frequência do que deveria.

Harness manual também conta

Existe uma tentação de achar que harness só vale se tudo for automatizado. Não precisa ser assim.

11. Uma planilha tem os casos de teste.22. Um script gera respostas para cada caso.33. As respostas ficam salvas por versão.44. Uma pessoa revisa os critérios e marca passou, falhou ou precisa revisar.55. A decisão final fica registrada.

Isso já é muito melhor do que testar três exemplos na memória. Com o tempo, algumas partes podem ser automatizadas: validar JSON, conferir campos obrigatórios, checar valores permitidos, medir custo e latência ou detectar erro de parsing.

O que evitar

• Criar apenas casos fáceis demais.
• Medir só o que é simples de automatizar.
• Comparar versões com entradas diferentes.
• Esquecer modelo, parâmetros, contexto e instruções de sistema.
• Tratar score como verdade absoluta.

Validar schema é importante, mas uma resposta pode passar no schema e ainda ser ruim. O formato é parte da qualidade, não a qualidade inteira.

Relação com observabilidade

Harness e observabilidade não são a mesma coisa. O harness ajuda antes ou durante mudanças controladas. Observabilidade ajuda a entender o que acontece quando a funcionalidade está em uso real.

O harness ajuda a não aprovar mudanças no escuro. A observabilidade ajuda a não operar a funcionalidade no escuro. Essa é uma ponte natural para os próximos guias da série.

Limites e ressalvas

Harness ajuda, mas tem limites. Ele depende da qualidade dos casos, da clareza dos critérios e de revisão humana quando o julgamento é subjetivo.

Ele pode passar confiança demais se o conjunto de teste for pequeno, enviesado ou fácil. Também pode virar burocracia se for aplicado em qualquer experimento pequeno.

O primeiro harness não precisa impressionar. Precisa ajudar a decidir.

Aprendizados

• Testar no chat ajuda, mas não é o mesmo que testar um fluxo com IA.
• Evals definem critérios; harness executa casos de forma repetível.
• Um harness inicial pode ser simples: casos, runner, logs, comparação e decisão.
• Usar as mesmas entradas é essencial para comparar versões.
• Logs mínimos ajudam a entender por que uma resposta mudou.
• Revisão humana continua importante, principalmente em critérios subjetivos.
• Automatizar partes repetitivas faz sentido, mas só depois de entender o que precisa ser avaliado.

Conclusão

Um harness não precisa ser uma grande infraestrutura. Na prática, ele começa quando você para de testar uma mudança com exemplos soltos e passa a rodar os mesmos casos com algum registro.

Quando prompt, modelo, retrieval ou fallback mudam, a pergunta deixa de ser "essa resposta pareceu melhor?" e passa a ser "rodando os mesmos casos, o que melhorou, o que piorou e o que ainda precisa de revisão?".

Não é certeza absoluta. É repetição, comparação e critério. Para funcionalidades com IA, isso já é um avanço enorme.