Avalie agentes de IA de forma sistemática com o Agent-EvalKit

O problema com a avaliação tradicional de agentes

Equipes que desenvolvem agentes de Inteligência Artificial (IA) costumam avaliá-los da mesma forma que avaliam qualquer outro software: verificando se a saída corresponde ao que era esperado. O problema é que agentes autônomos, que escolhem ferramentas e encadeiam operações por conta própria, produzem comportamentos que testes baseados apenas na saída final não conseguem capturar completamente.

Um agente pode entregar uma resposta bem estruturada e aparentemente útil enquanto alucina — inventando fatos porque suas ferramentas retornaram resultados vazios. Ele também pode chegar à conclusão correta pulando etapas de verificação que um processo confiável exigiria. Como essas falhas ficam abaixo da superfície da resposta final, detectá-las exige uma avaliação que rastreie o caminho completo de execução: quais ferramentas foram chamadas, o que elas retornaram e se a resposta reflete fielmente esses dados.

Fechar essa lacuna requer uma infraestrutura que a maioria das equipes não tem capacidade de construir do zero. São necessários casos de teste com resultados esperados, instrumentação de observabilidade para capturar chamadas de ferramentas e estado intermediário, além de métricas que avaliem fidelidade e uso de ferramentas junto com a precisão da saída.

O que é o Agent-EvalKit

O Agent-EvalKit é um toolkit open-source (licença Apache 2.0) que disponibiliza essa infraestrutura de avaliação ao se integrar com assistentes de codificação de IA, incluindo Claude Code, Kiro CLI e Kilo Code. Em vez de tratar a avaliação como uma etapa separada pós-implantação, o toolkit traz todo o fluxo de trabalho para dentro do ambiente de desenvolvimento.

O funcionamento é direto: você descreve seus objetivos de avaliação em linguagem natural, e o toolkit cuida de cada fase — desde a leitura do código-fonte do agente e a geração de casos de teste direcionados, passando pela execução das avaliações, até a produção de um relatório com recomendações de melhoria que referenciam locais específicos no código.

O toolkit foi desenvolvido para funcionar através do seu assistente de codificação existente, que se torna o motor de avaliação ao aplicar sua capacidade de ler código e raciocinar sobre o comportamento do agente em cada fase do processo. O fluxo é controlado por comandos como /evalkit.plan e /evalkit.data, seguidos de instruções em linguagem natural que indicam quais dimensões de qualidade são mais importantes para o seu agente.

Por que a escolha das métricas importa

Além da infraestrutura em si, definir o que medir é igualmente desafiador. A qualidade de um agente abrange dimensões que nenhuma métrica única captura sozinha: se as respostas são fundamentadas no que as ferramentas realmente retornaram, se o agente chamou as ferramentas certas com os parâmetros corretos e se a saída final é coerente e útil.

Uma resposta pode parecer excelente enquanto alucina silenciosamente sobre resultados vazios de ferramentas. Um agente pode chegar a uma resposta plausível por meio de uma sequência quebrada de chamadas de ferramentas. Por isso, cada dimensão precisa ser verificada de forma independente.

Nenhum estilo único de avaliador resolve tudo bem. Avaliadores baseados em código oferecem resultados rápidos e reproduzíveis, mas penalizam variações válidas de abordagem. Avaliadores baseados em Grandes Modelos de Linguagem (LLM) como juízes fornecem avaliações mais nuançadas ao custo de inferência adicional e design cuidadoso de prompts. As estratégias mais eficazes combinam as duas abordagens. Além disso, traduzir pontuações de avaliação em mudanças concretas de código é onde muitos esforços travam — razão pela qual o fluxo precisa terminar em recomendações específicas no nível do código, não em um painel de números.

As seis fases do Agent-EvalKit

O toolkit organiza o trabalho em seis fases, cada uma produzindo artefatos no diretório eval/ que alimentam a fase seguinte. Cada fase é invocada como um comando no assistente de IA, e o texto após o comando serve como orientação em linguagem natural para aquela etapa.

• Plan (/evalkit.plan): lê o código do agente para entender suas ferramentas e framework, então produz um plano de avaliação que associa cada métrica a um método concreto de avaliação. As prioridades definidas aqui se propagam para as fases seguintes.
• Data (/evalkit.data): gera casos de teste baseados no plano de avaliação, cada um com entradas e resultados esperados que visam comportamentos e modos de falha específicos. Se você já tiver dados de teste de logs de produção ou testes manuais, pode apontar esta fase para o conjunto existente.
• Trace (/evalkit.trace): torna o caminho completo de execução visível adicionando rastreamento compatível com OpenTelemetry ao agente. Para frameworks suportados — incluindo Strands, LangGraph e CrewAI — a fase detecta o framework e aplica a instrumentação adequada.
• Run Agent (/evalkit.run_agent): executa o agente contra cada caso de teste, produzindo um arquivo de rastreamento estruturado para cada execução que captura o histórico completo de chamadas de ferramentas, respostas do modelo e estado intermediário.
• Eval (/evalkit.eval): implementa as métricas do plano como código de avaliação executável, roda esse código contra os rastreamentos coletados e salva resultados estruturados. Suporta bibliotecas como DeepEval e o Strands Evals SDK.
• Report (/evalkit.report): analisa padrões entre os casos de teste e gera recomendações priorizadas que referenciam locais específicos no código do agente, com cada recomendação incluindo seu impacto esperado.

Ao longo dessas fases, preocupações vagas de qualidade se transformam em um conjunto estruturado de evidências: casos de teste, rastreamentos de execução, pontuações de métricas e recomendações priorizadas — tudo vinculado a locais específicos no código.

Estudo de caso: avaliando um agente de pesquisa de viagens

Durante o desenvolvimento de um agente de pesquisa de viagens construído com o Strands Agents SDK e o Amazon Bedrock, a equipe percebeu que o agente às vezes fornecia números suspeitosamente precisos em suas respostas. O agente ajuda usuários a planejar viagens usando ferramentas de busca na web, informações de voos, dados climáticos, conversão de moedas e cálculo de orçamento — mas não era possível determinar a extensão do problema ou quais consultas o desencadeavam.

O Agent-EvalKit analisou o código do agente e, durante a fase Plan, projetou uma avaliação focada em três métricas: Faithfulness (Fidelidade), que mede se as respostas estão fundamentadas nos dados que as ferramentas realmente retornaram; Tool Parameter Accuracy (Precisão de Parâmetros de Ferramentas), que verifica se o agente chamou as ferramentas com as entradas corretas; e Response Quality (Qualidade de Resposta), que avalia a coerência e utilidade da saída.

A fase Data gerou 100 sessões de teste com múltiplos turnos cobrindo pesquisa de destino, timing sazonal, construção de itinerário, perguntas comparativas e cálculo de orçamento. As fases seguintes executaram cada sessão enquanto capturavam rastreamentos detalhados de execução.

Os resultados expuseram uma divisão clara entre qualidade e confiabilidade. A Qualidade de Resposta ficou em 83,9%, confirmando que o agente produzia conselhos de viagem claros e acionáveis. A Precisão de Parâmetros de Ferramentas chegou a 64,5%, mostrando que o agente geralmente selecionava as ferramentas certas, mas às vezes passava parâmetros imprecisos. Já a Fidelidade pontuou apenas 32,3%, revelando que o agente fabricava taxas de câmbio, temperaturas e detalhes de atrações sempre que suas ferramentas de busca na web retornavam resultados vazios ou incompletos — e apresentava essas invenções como se viessem das ferramentas.

O relatório identificou as proteções contra alucinação como a correção de maior prioridade, recomendando instruções no system prompt para divulgar quando as ferramentas retornam resultados vazios e melhorias no tratamento de erros das ferramentas em todos os caminhos de código. Antes de rodar o Agent-EvalKit, a equipe sabia que o agente às vezes parecia não confiável. Depois, sabia exatamente que a causa raiz eram saídas vazias de ferramentas desencadeando alucinação — e tinha mudanças específicas de código para resolver o problema.

Como começar a usar

Para executar uma avaliação com o Agent-EvalKit, são necessários alguns pré-requisitos: uma conta AWS ativa com modelos de fundação habilitados no console do Amazon Bedrock (o toolkit usa métricas de LLM-como-juiz que requerem um modelo de fundação para pontuação), Python 3.11 ou superior, Git, o gerenciador de pacotes uv e um assistente de codificação de IA suportado (Claude Code, Kiro CLI ou Kilo Code) instalado e configurado.

A instalação é feita via uv, que puxa diretamente do repositório GitHub do Agent-EvalKit:

uv tool install evalkit --from git+https://github.com/awslabs/Agent-EvalKit.git

Em seguida, inicialize um projeto de avaliação e copie o código do seu agente para o diretório do projeto:

evalkit init my-agent-evaluation
cd my-agent-evaluation
cp -r /path/to/your/agent .

Inicie o assistente de IA dentro do projeto de avaliação. Para o Claude Code:

claude

Para uma primeira avaliação guiada, o comando rápido percorre todas as seis fases passo a passo:

/evalkit.quick <sua orientação em linguagem natural>
/evalkit.quick Evaluate my agent at ./my_agent for response quality and tool accuracy

Para mais controle, execute cada fase individualmente:

/evalkit.plan <sua orientação em linguagem natural>
/evalkit.plan Evaluate my agent at ./my_agent for response quality and tool accuracy
/evalkit.data
/evalkit.trace
/evalkit.run_agent
/evalkit.eval
/evalkit.report

Boas práticas para avaliação contínua

A avaliação de agentes tem mais retorno quando roda a cada mudança significativa, não apenas como um ponto de verificação pré-lançamento. Algumas práticas recomendadas:

• Comece de forma estreita: foque em duas ou três métricas que visem as dimensões de qualidade mais críticas do agente e expanda o escopo em avaliações posteriores.
• Oriente com conhecimento de domínio: descreva as entradas específicas, casos extremos e modos de falha que você já observou. Quanto mais direcionadas forem as instruções em linguagem natural, mais relevantes serão os casos de teste e recomendações gerados.
• Revise os casos de teste antes da execução: a fase de dados sintetiza casos a partir do plano de avaliação, mas seu entendimento do comportamento real dos usuários é insubstituível. Adicione cenários que reflitam padrões que você observa em produção.
• Avalie após cada mudança significativa: isso permite detectar regressões cedo e medir o impacto de cada melhoria. Comparar relatórios entre versões do agente torna o progresso visível.
• Aborde recomendações de forma incremental: comece pelo item de maior impacto no relatório, implemente a correção, reavalie para confirmar a melhoria e então avance para o próximo achado.
• Monitore em produção: capture rastreamentos do tráfego real com o Amazon Bedrock AgentCore Observability e execute métricas de qualidade contra esses rastreamentos com o AgentCore Evaluation. O monitoramento em produção expõe regressões e novos modos de falha que a avaliação pré-implantação não consegue antecipar.
• Mantenha os avaliadores alinhados com especialistas humanos: compare periodicamente as pontuações do LLM-como-juiz com julgamentos de especialistas no domínio. Atualize os prompts dos avaliadores quando os dois divergirem.

Integração com pipelines de CI/CD

Para equipes prontas para automatizar, o Agent-EvalKit pode ser integrado a um pipeline de Integração Contínua e Entrega Contínua (CI/CD), onde mudanças de código disparam avaliações, um portão de qualidade verifica limiares de métricas e regressões, e falhas são encaminhadas de volta como itens sinalizados no relatório de avaliação.

Uma vez que o pipeline esteja em funcionamento, cada rodada de testes reutiliza os casos de teste e a instrumentação da rodada anterior — o que reduz o custo de executar uma nova avaliação conforme o projeto amadurece.

Conclusão

O Agent-EvalKit dá à avaliação de agentes de IA uma forma sistemática ao delegar cada etapa — do design da avaliação ao cálculo de métricas e geração de relatórios — ao mesmo assistente de IA que você já usa para escrever código. O estudo de caso com o agente de pesquisa de viagens ilustrou como isso funciona na prática: transformando uma preocupação difusa de qualidade em uma correção específica em um local específico do código, com impacto esperado definido.

À medida que agentes assumem tarefas com maiores riscos e maior alcance, uma avaliação que vai além da verificação de saída se torna um pré-requisito para a prontidão em produção. O Agent-EvalKit foi projetado para tornar essa avaliação parte do mesmo fluxo de desenvolvimento que você já usa para escrever e revisar código de agentes.

Para leitura adicional sobre a solução, consulte Um Estudo Empírico sobre Automação de Avaliação de Agentes.

Fonte

Evaluate AI agents systematically with Agent-EvalKit (https://aws.amazon.com/blogs/machine-learning/evaluate-ai-agents-systematically-with-agent-evalkit/)