AWS lança o UAEF: um único conjunto de 36 métricas para agentes em qualquer framework

Você montou um agente em LangGraph, ele funciona e as métricas estão configuradas. Aí a equipe decide migrar para o Strands ou mover parte da lógica para o AgentCore, e descobre que o scoring, o armazenamento de resultados e os relatórios foram feitos sob o formato de traces do framework antigo. A avaliação precisa ser refeita do zero, e a pergunta simples «o agente melhorou depois que mudamos o prompt?» fica sem resposta.

A AWS propõe desfazer esse acoplamento. O UAEF (Universal Agent Evaluation Framework) é um projeto aberto sob licença Apache 2.0 (repositório awslabs/uaef). Ele separa «como o framework registrou a execução do agente» de «como avaliamos a qualidade». Segundo a AWS, o projeto já foi usado por 12 organizações dos setores de telecomunicações, saúde e finanças.

Como funciona

A entrada são duas coisas: um agente e um dataset. O dataset contém as consultas e, opcionalmente, as respostas de referência. Para verificar as chamadas de ferramentas, é preciso incluir na referência as chamadas esperadas: quais ferramentas, em que ordem e com quais argumentos.

Em seguida, o pipeline funciona assim:

1. O adaptador lê o rastro nativo de execução (mensagens, chamadas de ferramentas, transferências entre agentes) e o converte para o formato unificado AgentTrace. Pode-se fornecer um trace pronto, vindo de logs ou do Langfuse. Ou o próprio UAEF chama o agente por ARN ou endpoint HTTP para cada entrada do dataset.
2. O trace é verificado quanto a dados pessoais (e-mails, telefones, números de cartão) antes de ser salvo.
3. O motor calcula as métricas. São 36, distribuídas em 7 dimensões: chamada de ferramentas, qualidade da resposta, IA responsável, desempenho, diálogo de várias etapas, coordenação de vários agentes e raciocínio.
4. O resultado é gravado como um experimento: metadados no DynamoDB e resultados completos, junto com as justificativas do juiz, no S3.

A ideia central está na ordem das etapas: primeiro a normalização, depois a avaliação. Por isso, um agente em um framework pode ser comparado de forma justa com um agente em outro, na mesma escala. Cada métrica retorna um número de 0 a 1, em que 1 é o melhor valor.

Métricas determinísticas e LLM como juiz

Há dois tipos de métricas. As determinísticas são calculadas diretamente a partir do trace e da referência e são reproduzíveis de forma idêntica. As demais usam LLM-as-a-judge: um modelo no Amazon Bedrock avalia o que é difícil de formalizar, como relevância ou segurança. É possível adicionar métricas próprias e conectar RAGAS e DeepEval.

Os autores descrevem separadamente a proteção do juiz. A resposta do agente entra no prompt do juiz e, portanto, é uma entrada não confiável. Caso contrário, um agente capaz de influenciar o juiz poderia influenciar as próprias avaliações. Os critérios são enviados separadamente do conteúdo, o conteúdo é escapado, e o juiz é obrigado a citar um trecho literal do texto avaliado. Se a citação não está no texto, a avaliação é descartada. Ainda assim, a AWS alerta com franqueza: as avaliações do juiz são um sinal para o desenvolvimento, não um mecanismo de segurança. Para proteção em runtime são necessários os Bedrock Guardrails.

Comparação de versões e regressões

Esta é a parte mais prática. Para cada métrica comum a duas execuções, o UAEF calcula a variação absoluta e percentual e a classifica como regressão, melhoria ou sem mudança. O limite padrão é 5%. A gravidade da regressão é dividida em três níveis: leve (5–10%), moderada (10–20%) e grave (mais de 20%). As regressões são agrupadas por dimensão.

Imagine que você ajustou o prompt de sistema. A comparação pode mostrar que a qualidade da resposta não mudou, enquanto a precisão na escolha de ferramentas caiu 12%, ou seja, uma regressão moderada. Sem o recorte por dimensões, você veria apenas a nota média, que quase não se moveu.

É possível vincular uma configuração à execução: framework, modelo, ferramentas, prompt, parâmetros e até o commit do Git. Uma execução pode ser designada como a de referência. Assim, cada nota fica associada à mudança que a gerou.

Os relatórios funcionam em três níveis: resumo dos resultados na interface web, relatório estatístico e insights de LLM. O relatório estatístico é calculado apenas a partir das notas, sem LLM, com intervalos de confiança e outliers, por isso é sempre idêntico para os mesmos dados. Os insights, isto é, hipóteses sobre as causas e prioridades de correção, são gerados por um modelo no Bedrock por meio da biblioteca Python.

O que fazer com isso

Primeiro: não ative as 36 métricas de uma vez. No playbook, a AWS recomenda partir do cenário de uso. Um assistente RAG precisa de relevância, precisão e faithfulness do RAGAS; um agente com ferramentas precisa da escolha e da ordem das chamadas e da qualidade dos parâmetros. Métricas desnecessárias custam tempo e chamadas ao Bedrock.

Segundo: o UAEF pode ser integrado ao CI/CD por meio da biblioteca Python, e, para colegas menos técnicos, há um serviço implantável com interface low-code. O motor é o mesmo nos dois casos.

As limitações também são evidentes. A ferramenta é fortemente atrelada à AWS: o juiz roda no Bedrock, e o armazenamento é DynamoDB e S3. Um limite de 5% em um dataset pequeno pode facilmente ser confundido com ruído, por isso observe os intervalos de confiança no relatório. E não confunda avaliação de qualidade com proteção: para segurança, são necessárias barreiras separadas.

Para equipes que executam agentes em vários frameworks ou planejam migrar, essa é uma base pronta para testes de regressão de agentes, que de outro modo teria de ser escrita internamente.