Evals para agent skills: como testar agentes de forma sistemática

TL;DR

Evals para agent skills tratam uma habilidade do agente como uma suíte de teste de ponta a ponta: você executa a skill, coleta trace e artefatos, e aplica checks para gerar um score comparável entre versões. Isso importa porque agentes erram no processo, não só no resultado final; então vale medir sucesso, trajetória e calibrar os avaliadores para reduzir falso positivo e falso negativo.

O que muda quando o alvo é uma skill, e não só uma resposta

Em prompts clássicos, muita gente avalia apenas a saída final. Em agentes, isso costuma ser insuficiente, porque a execução envolve memória, ferramentas, recuperação de contexto e decisões em sequência. O artigo da OpenAI sobre evals para agent skills propõe um recorte mais operacional: a skill vira uma unidade testável, com entradas conhecidas, execução observável e critérios de aceitação definidos antes da rodada.

Na prática, isso aproxima a avaliação de um teste de integração bem instrumentado. Você não quer apenas saber se o texto final ficou aceitável; precisa saber se o agente acionou a ferramenta certa, no momento certo, sem violar restrições do fluxo.

Três coisas que precisam estar claras

• Critério de sucesso: o que conta como “passou” para aquela skill.
• Estado observável: quais traces, mensagens, chamadas de tool e artefatos serão registrados.
• Checks objetivos: quais regras, heurísticas ou julgamentos modelados serão aplicados sobre a execução.

Pipeline de eval: da execução ao score

O encadeamento sugerido pelos materiais analisados é simples de entender e fácil de automatizar: skill → run capturado → checks → score. O ganho está em tornar essa rotina reproduzível para comparar versões do agente, do prompt ou do modelo ao longo do tempo.

O ponto central é usar evidências, não só texto final. Uma execução pode ser considerada correta porque passou por uma sequência adequada de passos, preservou um estado intermediário esperado e produziu artefatos consistentes. Isso abre espaço para score contínuo, em vez de depender apenas de um binário “passou/falhou”.

Quando o score depende de critérios compostos, vale registrar o que foi checado em cada dimensão. Sem isso, regressões pequenas somem no agregado e ficam invisíveis até chegar em produção.

Exemplo de estrutura de check

Uma suíte mínima para uma skill de agente pode separar os checks em camadas:

• corretude do resultado final;
• aderência ao fluxo esperado;
• ausência de violações;
• cobertura dos requisitos da tarefa;
• consistência entre passos e artefatos.

Esse tipo de decomposição ajuda a encontrar qual dimensão piorou depois de uma mudança. Em vez de “o agente ficou ruim”, você passa a enxergar se o problema está no planejamento, no uso da ferramenta, na validação final ou na recuperação do contexto.

Por que trajetória importa mais do que só o resultado

A Anthropic enfatiza um ponto importante para agentes: avaliar apenas o resultado final esconde o mecanismo do erro. Dois runs podem terminar com a mesma resposta, mas um deles pode ter feito dez chamadas inúteis, consultado a ferramenta errada ou quebrado uma restrição de estado no meio do caminho.

Isso é especialmente relevante quando o agente executa etapas encadeadas. Se o diagnóstico ignora a trajetória, fica difícil entender onde a skill falhou e mais ainda difícil criar uma correção que não degrade outra parte do fluxo.

Por isso, evals úteis para agentes costumam olhar para a sequência de ações. Ordem de tool calls, consistência de estados transitórios, validações intermediárias e evidências de decisão são sinais valiosos para separar um agente que “acertou por acaso” de um agente que realmente executou bem a skill.

Onde os traces entram

Traces não são detalhe de observabilidade; eles são insumo da avaliação. Em agentes, o score passa a depender do rastro deixado pela execução, como chamadas de tool, documentos lidos, estados atualizados e regras satisfeitas ao longo do caminho.

Para times que já usam logging ou tracing distribuído, essa é uma evolução natural. A diferença é que agora o trace deixa de servir só para operação e passa a alimentar uma suíte de validação contínua.

Como transformar isso em rotina de CI

O repositório openai/evals aparece como base para registrar e customizar evals, enquanto promptfoo ajuda a executar avaliações em pipeline e comparar runs. Juntos, eles sugerem uma prática importante: testar agentes com datasets de cenários versionados, em vez de depender de checagens ad hoc.

Isso é útil para PRs, releases e execuções noturnas. Cada mudança no prompt, no modelo, na ferramenta ou no orquestrador pode ser cruzada contra um conjunto fixo de casos, que cobre o comportamento esperado da skill.

undefined

Como qualquer fluxo que dependa de versões de SDK, CLI ou APIs de IA, vale tratar a suíte como algo volátil e revisável. APIs mudam rápido, schemas também, e um harness que funcionava na semana passada pode precisar de ajuste após uma atualização de endpoint ou de modelo.

Esta seção descreve um fluxo baseado em ferramentas e versões que mudam com frequência. Antes de adotar em produção, confira o changelog oficial do framework, do modelo e da API usada no seu harness.

Meta-avaliação: calibrar o avaliador também faz parte do trabalho

Um ponto frequentemente esquecido é que o avaliador também precisa ser testado. Se você usa julgamentos de modelo, heurísticas ou classificadores para medir a skill, precisa verificar se o avaliador está consistente, sensível e calibrado.

Sem essa camada, o score pode virar ruído sofisticado. Você acha que está medindo progresso, mas na prática está medindo variação do juiz, mudança de prompt do julgador ou drift na interpretação dos checks.

Na prática, meta-avaliação significa criar amostras rotuladas, comparar o comportamento do avaliador com um conjunto de referência e monitorar onde ele erra. Isso é especialmente importante quando a avaliação mistura regras determinísticas e julgamentos mais subjetivos.

O que monitorar no avaliador

• consistência entre execuções repetidas;
• desvio entre avaliadores diferentes;
• tendência a aprovar ou reprovar demais;
• capacidade de explicar por que uma execução passou ou falhou.

Por que isso importa pro dev brasileiro

No Brasil, a pressão por eficiência costuma ser maior porque muito time opera com orçamento em BRL e paga infraestrutura, APIs e observabilidade em dólar. Uma mudança pequena no comportamento do agente pode aumentar chamadas de ferramenta, elevar consumo de tokens e estourar custo mensal antes que a equipe perceba, então medir regressão com um harness barato vira uma decisão prática, não acadêmica.

Há também um componente regulatório concreto: em fluxos que manipulam dados pessoais, a LGPD exige mais cuidado com tratamento, retenção e justificativa de uso. Se o agente consulta informações sensíveis, os evals precisam incluir checks de vazamento, de uso indevido de contexto e de descarte correto de artefatos, porque falhas aqui não são só técnicas; podem virar incidente de conformidade.

Além disso, muitos times brasileiros trabalham com latência internacional e dependem de fornecedores externos em regiões como us-east-1. Em agentes que fazem múltiplas chamadas, um harness ajuda a separar problema de rede, problema de ferramenta e problema de lógica, algo valioso quando o ambiente de produção já é naturalmente mais instável do que um laboratório local.

Como começar sem montar uma plataforma gigante

Você não precisa começar com uma estrutura complexa. Uma primeira versão pode ter um conjunto pequeno de cenários representativos, um formato fixo de trace e checks simples por dimensão. O objetivo inicial não é cobrir tudo; é criar repetibilidade suficiente para enxergar regressão entre commits.

Uma boa regra é começar pela skill mais cara ou mais crítica para o negócio. Se o agente ajuda no suporte, no atendimento interno ou em automação de processos, foque primeiro nos fluxos que geram maior custo de erro ou maior volume de uso.

Depois, documente os critérios em linguagem operacional. Em vez de dizer apenas que a skill deve “ser boa”, explicite o que deve acontecer: quais ferramentas podem ser chamadas, quais estados precisam ser preservados e quais artefatos devem existir ao final.

Para times com pouco tempo, uma suíte pequena e estável vale mais do que uma bateria ampla e pouco confiável. O ganho vem de comparar a mesma skill ao longo do tempo com critérios constantes.

Fechando a ideia

O valor de evals para agent skills está em tornar o comportamento do agente observável, comparável e acionável. Quando você mede trajetória, usa traces como evidência e calibra o avaliador, passa a detectar regressões cedo e com muito mais contexto.

Se a sua equipe já sente que o agente “faz coisas estranhas” de vez em quando, esse é o sinal de que a avaliação precisa sair do PDF mental e virar suíte executável. Em até uma hora, abra o framework que você já usa, selecione uma skill crítica e escreva o primeiro caso com entrada fixa, trace registrado e um critério objetivo de aprovação.

Conteúdos da DIO para quem quer aprofundar

• Aceleração Microsoft AI Agents — traz uma imersão prática em agentes e ferramentas de IA, útil para quem quer conectar o tema de evals ao ciclo completo de construção de agentes.
• Aceleração Automação de Testes #TQI — aborda automação de testes e qualidade com foco em prática, ajudando a pensar em harness e rotina de validação contínua.
• Trilha de Conhecimento - Analista de Teste — oferece base de testes e qualidade para estruturar critérios, casos e diagnósticos de falhas.
• Trilha de Conhecimento - Coordenador de Teste — ajuda a pensar em estratégia, cobertura e gestão de qualidade em escala.
• TestComplete e banco de dados ágil — mostra um exemplo prático de automação e integração com dados, útil para quem quer sistematizar validações.