Testes de regressão para agentes de IA verificam se uma mudança de prompt, modelo ou ferramenta preserva comportamentos que já funcionavam. A implementação precisa comparar versões sobre cenários controlados, registrar as ações executadas e bloquear mudanças que violem regras essenciais, mesmo quando a resposta final parece boa.
Essa rotina vai além da primeira homologação. Depois que um agente entra em operação, cada ajuste cria uma nova possibilidade de falha. O objetivo é transformar incidentes e contratos do negócio em uma suíte repetível, executada durante o desenvolvimento e complementada pela observação da produção.
Resumo rápido
- Versione prompts, ferramentas, dados de teste e critérios de avaliação juntos.
- Separe verificações determinísticas da avaliação de linguagem.
- Compare a versão candidata com uma referência aprovada.
- Use ambientes de teste para ações que alteram sistemas externos.
- Transforme falhas reais em novos casos, com dados tratados.
Regressão contínua começa com um contrato de comportamento
O guia de como testar um agente de IA ajuda a organizar a avaliação inicial. A regressão contínua acrescenta uma pergunta diferente: depois da alteração, quais garantias anteriores continuam verdadeiras? Isso exige preservar casos e comparar resultados, em vez de recomeçar uma demonstração manual a cada entrega.
Escreva primeiro as invariantes, ou regras que não podem mudar sem uma decisão explícita. Um agente de atendimento pode consultar um pedido autenticado, mas não deve divulgar pedidos de outra conta. Uma ferramenta de cancelamento precisa receber o identificador certo e a confirmação exigida pelo fluxo. O texto pode variar; esses requisitos permanecem.
Registre também comportamentos aceitáveis quando faltam dados. Pedir esclarecimento pode ser o resultado correto. Uma suíte que recompensa apenas respostas completas tende a punir a prudência e favorecer suposições. Para cada cenário, indique o que o agente pode fazer, o que deve fazer e o que está proibido.
Escolha uma versão de referência aprovada e mantenha seu pacote reproduzível. Inclua o prompt completo, configurações, contratos das ferramentas e conjunto de dados. Se o fornecedor não permitir fixar todos os componentes, registre essa limitação. Ela muda a interpretação de diferenças encontradas, mas não elimina o valor de comparar versões sob as mesmas condições disponíveis.
Monte um conjunto de casos que evolui sem perder comparabilidade
Organize o conjunto de avaliação por famílias: consulta simples, ausência de informação, ambiguidade, erro de ferramenta, tentativa de acesso indevido e tarefa com vários passos. Use exemplos positivos e negativos. Uma ferramenta que nunca é chamada pode parecer segura, mas falhar em todas as tarefas legítimas.
Cada caso deve ter um identificador estável, entrada, estado inicial, respostas simuladas das dependências e expectativas. Guarde a origem do caso sem copiar desnecessariamente dados pessoais. Para reproduzir um incidente de produção, substitua informações identificáveis preservando a estrutura que causou a falha.
A documentação de avaliação do LangSmith descreve conjuntos de dados, avaliadores e experimentos, além da distinção entre avaliação offline e online. Ela também apresenta o uso de falhas observadas em produção como novos exemplos de avaliação. Esse ciclo pode orientar a organização da suíte mesmo quando sua equipe usa outra ferramenta.
Mantenha um núcleo estável para comparação histórica e um conjunto adicional para cenários novos. Quando o contrato muda de propósito, atualize a expectativa com justificativa e revisão. Não altere o resultado esperado apenas porque a versão candidata falhou: isso apaga a evidência da regressão.
Evite que todas as perguntas tenham a mesma redação. Inclua formas curtas, mensagens com contexto anterior e pedidos que exigem esclarecimento. O conjunto deve representar os caminhos do produto. Um volume enorme de paráfrases fáceis não compensa a ausência de um único caso crítico de autorização.
Combine testes de contrato, trajetória e qualidade da resposta
| Camada | O que observar | Exemplo de falha |
|---|---|---|
| Contrato da ferramenta | Nome, esquema e argumentos válidos | Enviar texto onde a API exige número |
| Trajetória | Ações, ordem e condições necessárias | Cancelar antes de obter confirmação |
| Resposta | Fidelidade aos dados e clareza | Dizer que cancelou após uma recusa da API |
| Operação | Tempo, consumo e tratamento de erro | Repetir chamadas sem encerrar a tarefa |
Prefira verificações em código quando a regra é objetiva. Compare identificadores, valide o esquema e confira se houve uma chamada proibida. Avaliar apenas se uma frase contém “confirmado” é frágil: a palavra pode aparecer em uma negativa ou em uma explicação sem que a ação tenha ocorrido.
O Promptfoo documenta assertions e métricas para verificar condições como igualdade, estrutura JSON e funções personalizadas. Essas verificações permitem separar critérios explícitos de julgamentos sobre linguagem. A escolha das regras continua sendo responsabilidade de quem conhece o processo.
Para qualidade textual, escreva uma rubrica curta: informa o estado real, não inventa dados ausentes e explica o próximo passo. Se usar um modelo avaliador, calibre-o com exemplos revisados por pessoas. Uma nota automática não deve anular uma violação comprovada de permissão ou uma chamada errada.
Inspecione a trajetória completa sem exigir uma sequência rígida quando várias sequências são válidas. Algumas consultas podem ocorrer em ordem diferente sem alterar o resultado. Restrinja a ordem somente onde existe uma dependência real, como verificar autorização antes de executar uma alteração. Essa distinção reduz falhas falsas na suíte.
Execute a suíte no desenvolvimento e antes da liberação
Divida as execuções por custo e finalidade. As verificações de contratos e regras locais podem rodar a cada mudança. Os testes que chamam modelos e serviços externos precisam de orçamento, limites de duração e um ambiente próprio. Rode a comparação completa quando houver alteração que afete o comportamento do agente.
A documentação do pytest sobre monkeypatch mostra como substituir atributos e variáveis de ambiente durante testes. Essa técnica ajuda a controlar dependências. Para uma ferramenta de pedidos, uma resposta simulada pode representar sucesso, indisponibilidade ou acesso negado sem alterar um cadastro real.
Não confunda simulação com teste de integração. A simulação verifica como seu código reage a uma resposta conhecida. Um teste separado precisa conferir se o conector continua conversando corretamente com o ambiente de homologação do fornecedor. Se o contrato externo mudar e a simulação permanecer antiga, os testes locais podem continuar verdes.
O GitHub Actions permite configurar gatilhos de workflows. Use os eventos adequados ao seu processo para executar a suíte e guardar os resultados associados à revisão de código. Não coloque credenciais em arquivos de casos nem em artefatos de execução.
Compare referência e candidata com o mesmo conjunto de entradas e condições. Como saídas podem variar, repita os cenários relevantes e registre a frequência das falhas, não apenas uma aprovação isolada. Defina antes da execução quais violações bloqueiam a entrega e quais diferenças exigem revisão humana.
Um relatório útil mostra casos novos que falharam, falhas que desapareceram e situações em que ambas as versões erraram. Inclua versões, configurações e evidências de chamadas. Se o avaliador ou a infraestrutura falhar, marque o caso como inconclusivo. Uma execução incompleta não equivale a sucesso.
Depois da liberação, acompanhe os mesmos tipos de comportamento em amostras autorizadas de produção. O artigo sobre observabilidade de agentes ajuda a conectar erros, tempo e consumo. Preserve um caminho de reversão da mudança e um responsável por decidir quando acioná-lo.
Exemplo: distribuidora de materiais de construção em Campinas
Imagine uma distribuidora fictícia em Campinas cujo agente consulta pedidos e abre solicitações de troca. A equipe altera o prompt para tornar as respostas mais curtas. Na demonstração, tudo parece melhor. Entretanto, a nova redação pode levar o agente a omitir uma pergunta necessária antes de enviar a solicitação.
A suíte inclui um cliente autenticado, um pedido de outra conta, uma entrega ainda não concluída e uma resposta de indisponibilidade do sistema. São cenários ilustrativos, sem resultados de uma empresa real. As ferramentas operam sobre dados de teste e registram as chamadas feitas pelo agente.
No caso de troca, a expectativa não exige uma frase idêntica à versão anterior. Exige que o agente confira o pedido autorizado, obtenha as informações necessárias e só então abra a solicitação. A resposta final precisa distinguir “solicitação registrada” de “troca aprovada”, porque são estados diferentes do processo desenhado para o exemplo.
O teste de indisponibilidade devolve um erro controlado do sistema. O agente deve informar que não conseguiu concluir a operação e oferecer o próximo passo previsto. Se disser que a solicitação foi aberta, a verificação falha mesmo que o texto seja educado e conciso.
A equipe compara as duas versões e examina os casos afetados. Se a candidata omitir a confirmação exigida, a entrega fica bloqueada até a correção. Se apenas reduzir frases sem alterar os requisitos, a mudança pode avançar após a revisão prevista. O valor da regressão é preservar esse contrato ao longo das próximas alterações, inclusive mudanças pequenas.
Erros comuns
- Usar igualdade literal para toda resposta. Variações legítimas de redação não são regressões. Compare fatos e ações quando o formato não for fixo.
- Avaliar apenas a média. Um resultado agregado pode esconder uma falha grave em um grupo pequeno de casos.
- Executar ações reais sem isolamento. Uma suíte pode criar pedidos ou enviar mensagens involuntariamente. Controle as dependências e o ambiente.
- Atualizar o gabarito automaticamente. A expectativa precisa de revisão quando representa uma regra do produto.
- Deixar o avaliador mudar junto com o agente. Isso dificulta saber de onde veio a diferença. Versione a rubrica e compare mudanças separadamente.
- Ignorar erros de infraestrutura. Timeout, credencial inválida e falha do avaliador precisam aparecer no relatório.
Também evite remover um cenário porque ele falha de modo intermitente. Primeiro descubra se a variação vem do agente, de uma dependência ou do próprio teste. Quando for necessário separar o caso temporariamente, registre motivo, responsável e critério de retorno. Esconder a instabilidade transforma um alerta conhecido em risco invisível.
Perguntas frequentes
É preciso testar toda mudança de prompt?
Qualquer mudança que possa alterar o comportamento merece avaliação proporcional. Ajustes aparentemente pequenos podem modificar a escolha de ferramentas. Mantenha uma suíte rápida para o cotidiano e amplie a avaliação conforme o alcance e o risco da alteração.
Temperatura baixa torna o teste determinístico?
Não trate uma configuração de geração como garantia suficiente de repetição. Registre os parâmetros disponíveis, controle as dependências e observe variações em execuções repetidas. O teste deve avaliar requisitos mesmo quando a redação muda.
Quantos exemplos são necessários?
Não há um número universal para esse processo. Comece cobrindo as famílias de comportamento e os riscos concretos do produto. Acrescente incidentes reais e acompanhe quais requisitos ainda não têm cenários. Cobertura útil depende de diversidade e relevância.
Posso usar somente um modelo como avaliador?
Para critérios objetivos, verificações em código são mais diretas e auditáveis. O avaliador de linguagem pode complementar a análise de clareza e fidelidade, desde que seja calibrado. Decisões críticas precisam considerar as evidências das ações executadas.
Quando um teste deve bloquear a publicação?
Quando viola um requisito previamente definido como obrigatório, como isolamento entre contas ou confirmação antes de uma ação. Defina esses critérios antes de olhar o resultado da candidata. Diferenças ambíguas devem ir para revisão, sem serem convertidas automaticamente em aprovação.
