Como sistematizar evals para agent skills

TL;DR

Testar agentes exige olhar para a execução inteira, não só para a resposta final. Quando você trata uma skill como uma combinação de trajetória, chamadas a ferramentas e artefatos, os evals ficam mais repetíveis e úteis para comparar versões ao longo do tempo.

Na prática, isso muda o foco do time: em vez de perguntar se o texto final “parece bom”, você mede se o agente planejou bem, usou as ferramentas certas e preservou o estado esperado. Esse recorte é especialmente importante quando o agente executa fluxos com múltiplas etapas, em que um acerto aparente pode esconder um caminho incorreto.

Por que eval de agente é diferente de eval de chatbot

Em um chatbot tradicional, muitas vezes basta medir a qualidade da resposta final. Em agentes, isso não segura o problema inteiro: há múltiplas rodadas, chamadas a ferramentas, leitura de estado, escrita de artefatos e decisões intermediárias que podem falhar mesmo quando a resposta final parece aceitável.

O ponto central do brief é tratar a skill como um teste end-to-end: prompt → run capturado → checagens → score. Esse formato deixa a avaliação mais próxima do comportamento real do agente e reduz a dependência de julgamentos subjetivos em produção.

Esta abordagem depende da forma como o agente expõe trace, estado e artefatos. APIs e formatos de telemetria mudam rápido — confira a documentação oficial antes de fixar o harness em produção.

O que deve entrar no teste

Para sistematizar a avaliação, vale capturar pelo menos três camadas. A primeira é a trajetória: quais passos o agente executou e em que ordem. A segunda é a interação com ferramentas: quais chamadas foram feitas, com quais argumentos e em qual momento. A terceira são os artefatos finais: respostas geradas, arquivos produzidos, estado atualizado e evidências de que a tarefa foi concluída.

Esse recorte ajuda a diagnosticar falhas que passam batido em um score único. Por exemplo: o agente pode entregar uma resposta correta, mas ter feito uma chamada desnecessária, ignorado um passo do workflow ou alterado um estado interno de modo inconsistente.

Trace-first: avaliar sem reexecutar

Uma prática útil é separar captura e avaliação. Você executa o agente uma vez, armazena o trace e então roda vários checks sobre esse mesmo registro. Isso reduz custo, evita variância de nova execução e permite comparar versões do agente sobre a mesma evidência.

O material do brief cita frameworks que pontuam comportamento a partir de traces, inclusive com suporte a OpenTelemetry. Esse desenho é interessante porque transforma a avaliação em algo próximo de testes de integração: o sistema registra o que aconteceu, e os checks analisam o acontecimento sem obrigar uma nova corrida completa.

Exemplo de estrutura de dados de avaliação

Um harness simples costuma guardar eventos, artefatos e métricas. O formato exato varia, mas a ideia é manter informação suficiente para validar comportamento e investigar regressões.

undefined

Esse tipo de estrutura não é um padrão universal, mas ilustra a lógica: o que importa não é só o texto final, e sim o conjunto de evidências que mostra como o agente chegou até ele.

Checks: regras, rubricas e sinais intermediários

O brief destaca duas estratégias complementares. A primeira são checks por regra, úteis quando você conhece o comportamento esperado com precisão. A segunda são rubricas, que deixam uma camada de julgamento mais flexível para casos em que o caminho correto não é binário.

Em um cenário de agente, isso costuma significar validar tanto o outcome quanto a trajectory. O resultado final pode estar correto, mas o trajeto pode ter sido caro, instável ou inconsistente. Quando você mede os dois, ganha diagnóstico e não apenas aprovação ou reprovação.

Exemplos de checks úteis

• Verificar se o agente chamou a ferramenta esperada antes de responder.
• Conferir se o estado final bate com o artefato produzido.
• Validar se o fluxo seguiu a ordem mínima de etapas definida para a skill.
• Checar se o agente evitou tool calls desnecessárias ou redundantes.
• Comparar sinais intermediários entre versões para detectar regressão silenciosa.

Esse desenho é especialmente bom para times que precisam operar com previsibilidade. Em vez de depender de leitura manual de logs, você centraliza a avaliação em checks reproduzíveis e score comparável ao longo das versões.

Como organizar uma suíte de evals por skill

Uma forma prática de começar é pensar cada skill como um teste individual com entrada, evidência esperada e critério de aprovação. Isso aproxima o problema da disciplina de testes de software: casos pequenos, claros e repetíveis, em vez de um benchmark genérico que não conversa com o seu fluxo real.

Para deixar isso operacional, vale separar a suíte em camadas. Há skills críticas, como busca de informação, atualização de estado e execução de ferramentas sensíveis. Há skills auxiliares, como sumarização, priorização ou classificação. Cada grupo pode ter checks diferentes, com pesos diferentes no score final.

Um roteiro mínimo para montar a suíte

1. Defina a skill e o resultado esperado em termos observáveis.
2. Capture traces, artefatos e estado final em uma execução padrão.
3. Escreva checks pequenos para validar trajetória e outcome.
4. Rode a mesma suíte em versões diferentes do agente.
5. Compare os scores e investigue divergências com os traces.

O ganho aqui é rastreabilidade. Quando uma mudança de prompt, ferramenta ou política de planejamento quebra algo, você consegue apontar onde a regressão entrou. Isso é mais útil do que um número agregado sem contexto.

Por que isso importa pro dev brasileiro

Em times brasileiros, o budget costuma ser mais apertado e o custo em dólar pesa cedo. Esse detalhe não é cosmético: se você faz reexecuções completas a cada checksuite, o gasto sobe rápido com chamadas de modelo, ferramentas externas e telemetria. Por isso, avaliar via trace reaproveitado ajuda a controlar custo em BRL e a manter uma rotina de testes viável para squads menores.

Tem também o lado regulatório. Quando a skill lida com dados pessoais, a LGPD exige cuidado com tratamento, retenção e necessidade de base legal. Guardar traces sem política de minimização vira um risco real, porque o histórico do agente pode conter trechos de prompt, respostas de ferramentas e artefatos com informação sensível. Em contextos como fintechs, varejo ou saúde no Brasil, isso precisa entrar desde o desenho do eval.

Outro fator concreto é a operação. Muitos produtos brasileiros ainda têm infraestrutura concentrada em regiões como us-east-1, e isso afeta latência, custo e observabilidade. Se o agente depende de múltiplas chamadas remotas, cada execução completa pode ficar mais cara e mais lenta, então uma estratégia trace-first ajuda a manter o ciclo de testes curto sem sacrificar diagnóstico.

Erros comuns ao avaliar agentes

O erro mais comum é medir apenas a saída final e concluir que o sistema está estável. Em agentes, isso pode esconder problemas sérios no caminho percorrido. Outro erro é criar checks tão genéricos que eles não distinguem uma boa execução de uma execução apenas aceitável.

Também é comum não versionar os critérios. Se o prompt muda, a ferramenta muda ou o estado da aplicação muda, o score perde comparabilidade. Para evitar isso, sempre registre versão do agente, versão do harness e contexto do experimento junto com os resultados.

O que observar no dia a dia

• Diferença entre acerto aparente e execução correta.
• Regressões em chamadas a ferramentas mesmo com resposta final plausível.
• Score instável quando o mesmo caso é reexecutado sem controle de variância.
• Falta de evidência suficiente para explicar por que uma skill falhou.

Quando esses pontos aparecem, normalmente o problema não é o modelo sozinho. Em geral, é um sinal de que a suíte está pouco instrumentada ou que o eval está olhando para a coisa errada.

Fechando a estratégia

Sistematizar evals para agent skills é, no fundo, trocar impressão por evidência. Você passa a medir trajetória, ferramentas, estado e artefatos, em vez de confiar apenas na resposta final. Isso melhora a capacidade de comparar versões, localizar regressões e justificar mudanças de comportamento do agente com dados observáveis.

Se você quer aplicar isso em até uma hora, comece com uma skill pequena do seu sistema, escolha um caso real de execução, capture o trace e escreva três checks simples: fluxo seguido, ferramenta esperada chamada e estado final consistente. Depois rode o mesmo caso numa nova versão do agente e compare os resultados para ver onde a avaliação está falhando ou ficando superficial.