Rubricas de avaliação de agentes que viajam entre pilhas

Definindo uma rubrica pronta para viagem

Começo escrevendo a rubrica antes de olhar para qualquer saída do modelo. A rubrica deve conter três eixos independentes: sucesso da tarefa, correção da ferramenta e fidelidade. Cada eixo recebe seu próprio guia de pontuação que não menciona o nome do modelo, a versão do framework ou a palavra exata do prompt. Mantenho os guias em um arquivo de texto simples que vive ao lado do conjunto de testes, para que qualquer pessoa possa verificá-los.

Propriedades principais

- Critérios pré-registrados – as condições de sucesso são escritas antes da primeira execução. - Isolamento de eixos – as pontuações para um eixo nunca se misturam com outro. - Linguagem livre de versão – evite frases como "a partir do " ou "ao usar o ".

Por que o sucesso da tarefa deve ser baseado no resultado

O sucesso da tarefa responde à simples pergunta: o agente terminou o que foi solicitado? Eu julgo isso contra uma lista de verificação que olha para o estado final do mundo, não para a redação da resposta. Por exemplo, se a tarefa for 'atualizar o endereço de e-mail do usuário para alice@example.com', eu verifico o registro do banco de dados após a execução. Eu não me importo se o agente disse 'Eu atualizei seu e-mail' ou 'Seu e-mail agora é alice@example.com'.

Lista de verificação concreta

- Pré-condição verificada (por exemplo, usuário existe). - Pós-condição verificada (por exemplo, campo de e-mail é igual a alice@example.com). - Nenhum efeito colateral extra (por exemplo, nenhum outro campo alterado). - Opcional: latência abaixo de um limite (por exemplo, 2 segundos).

Eu registro um resultado binário de passar/falhar para cada trajetória. Se o agente falhar na pós-condição, a pontuação de sucesso da tarefa é zero, independentemente de quão fluente a prosa pareça.

Correção da ferramenta como um eixo separado

A correção da ferramenta examina as chamadas que o agente faz para APIs, funções ou bancos de dados externos. Trato cada chamada como um mini-experimento: o agente escolheu a ferramenta certa, passou os argumentos certos e chamou-a o número certo de vezes? Sigo as orientações dos sheets de dicas do OWASP sobre uso seguro de ferramentas, como o Prompt Injection Prevention Cheat Sheet e o SQL Injection Prevention Cheat Sheet para evitar injeção acidental.

Rubrica de pontuação

- Ferramenta certa selecionada – 1 ponto. - Todos os argumentos correspondem ao esquema – 1 ponto por argumento. - Nenhuma chamada extra – 1 ponto se a contagem de chamadas for igual à esperada. - Nenhum efeito colateral proibido (por exemplo, gravação em um log que deve permanecer somente leitura) – 1 ponto.

A pontuação do eixo é a soma dos pontos dividida pelo máximo possível.

Fidelidade: rastreando cada afirmação

A fidelidade pergunta se todas as declarações na saída do agente podem ser rastreadas até os resultados da ferramenta ou o contexto que foi dado ao modelo. Trato a saída como um conjunto de afirmações e verifico cada uma delas contra as evidências. Se uma afirmação não puder ser suportada, marco-a como uma alucinação. Este eixo importa mais quando o agente resume documentos, cita fontes ou responde a perguntas que requerem dados externos.

Verificação passo a passo

- Divida a saída em frases atômicas. - Para cada frase, liste os fatos que ela afirma. - Associe cada fato a uma linha na saída da ferramenta ou a um trecho do contexto fornecido. - Se um fato não tiver uma correspondência, conte-o como uma falha. - Pontuação de fidelidade = (número de fatos suportados) / (número total de fatos).

Registro as contagens brutas para que eu possa ver se uma queda na fidelidade vem de algumas grandes alucinações ou muitos pequenos erros.

O que isso não é

Quero deixar claro os limites de uma rubrica pronta para viagem. Ela não garante que o agente seja seguro, barato ou rápido. Ela não promete 100 % de precisão em todos os possíveis inputs. Ela não substitui uma revisão de segurança dedicada, uma análise de custo ou um benchmark de latência. A rubrica apenas mede os três eixos que defini acima. Se você precisa saber se o agente vazou chaves privadas, você deve executar uma verificação de gerenciamento de segredos separada, por exemplo, usando a Secrets Management Cheat Sheet. Se você precisa saber se o agente permanece dentro de um orçamento, você deve acompanhar o uso de tokens ou custos de chamadas de API fora dessa rubrica.

Em resumo, a rubrica é uma ferramenta para comparar a qualidade do agente em pilhas, não uma bala de prata para todas as preocupações de produção.

Construindo trajetórias comparáveis

Uma trajetória é o registro completo do que aconteceu durante uma execução: o prompt inicial, cada chamada de ferramenta com seus argumentos e resultados, e a saída final do modelo. Eu armazeno cada trajetória como um objeto JSON com um esquema fixo, para que eu possa diferençar execuções automaticamente. Abaixo está um exemplo do esquema que eu uso.

Campo | Tipo | Descrição prompt | string | O prompt exato enviado pelo usuário ou sistema para o modelo. calls | array | Lista ordenada de execuções de ferramentas. calls[].tool | string | Nome da ferramenta ou API. calls[].args | object | Argumentos passados para a ferramenta. calls[].result | any | Saída bruta da ferramenta. output | string | Texto final retornado pelo modelo. metadata | object | Tags opcionais, como nome do modelo, versão do framework, carimbo de data/hora.

Como o esquema nunca muda, eu posso calcular as três pontuações de eixo para cada trajetória usando os mesmos scripts. Eu mantenho um conjunto mestre de trajetórias que cobre as tarefas principais que eu envio e os modos de falha comuns que eu vi.

Executando avaliações em cada alteração

Integro o passo de avaliação no meu pipeline de integração contínua. O pipeline faz o seguinte em cada commit que pode afetar o comportamento:

- Verifica o código mais recente. - Instala as dependências do AgentGrade. - Executa o agente contra o conjunto de trajetórias fixo. - Analisa os logs e calcula as pontuações de sucesso da tarefa, correção da ferramenta e fidelidade. - Publica os resultados em um painel e sinaliza qualquer eixo que caia mais de cinco por cento em comparação com a última compilação verde.

Essa prática detecta regressões precocemente. Por exemplo, quando mudei a biblioteca de recuperação subjacente, o eixo de correção da ferramenta caiu de 0,96 para 0,82 porque a nova biblioteca retornou resultados em uma ordem diferente, causando o agente a fazer chamadas extras. A queda apareceu no relatório de CI antes que qualquer usuário notasse um problema.

Também mantenho um conjunto de vinte trajetórias avaliadas por humanos. Todos os meses, avalio essas com uma pessoa e comparo a média com as pontuações automáticas.

Lista de verificação do operador para avaliar rubricas do Agent que viajam entre pilhas

Mantenho uma lista de verificação escrita ao lado de cada lançamento que toca nesse tópico. A lista é propositadamente simples: nomear o proprietário, nomear o artefato de evidência e nomear o rollback. Se uma etapa não puder produzir um arquivo, um ticket ou uma linha de log, não é uma etapa - é um desejo.

Antes de alterar a produção

- Congele o branch ou a revisão de configuração que você medirá. - Registre o modo de falha atual com uma entrada concreta e uma saída concreta. - Confirme qual identidade o trabalho é executado e se essa identidade pode alcançar dados que não deveria. - Abra as referências principais que você citará: https://cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html, https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html.

Enquanto você executa a verificação

- Prefira um caminho reprodutível em vez de dez telas anedóticas. - Escreva o resultado seguro esperado antes de acionar a ferramenta ou consulta. - Capture o comando exato, prompt, esquema ou regex em teste - não uma paráfrase. - Se o sistema pode agir (enviar, escrever, excluir, transferir), exija um limite de confirmação na mesma passagem.

Depois de terminar

- Arquive o risco residual com um proprietário e uma data, mesmo quando a varredura estiver limpa. - Não converta um check verde em linguagem de vendas que afirme completude. - Execute a mesma lista de verificação quando o modelo, a ferramenta de esquema ou as regras de validação mudarem.

Sinal | O que registrar | Parar o envio? Escrita ou envio inesperado | Nome da ferramenta, args, identidade | Sim até que seja bloqueado Falta de confirmação em ação destrutiva | Caminho de chamada e bypass | Sim Texto não confiável tratado como instrução | Superfície de origem e ação resultante | Sim para alcance do agente Varredura limpa, julgamento aberto | Itens adiados + proprietário | Somente se o caminho central for seguro

O agenteval ajuda com a primeira passagem mensurável. As escolhas de arquitetura, a aprovação legal e as alegações voltadas para o cliente ainda precisam de um proprietário humano. Trate cada linha da lista de verificação como suporte à decisão, não como um certificado.

Como explico limites para compradores

Quando um prospect pergunta se o produto "cobrir tudo", respondo com o limite: verificações automatizadas capturam padrões conhecidos; cadeias novas e julgamento de política ainda precisam de revisão. Essa honestidade mantém a carga de suporte baixa e mantém o blog alinhado com o que o produto realmente faz.

Se você precisar de uma segunda opinião, combine este texto com as referências abaixo e com sua própria reprodução de teste. Não pule a etapa de reprodução apenas porque um modelo escreveu um resumo confiante.

Referências

- https://cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html - https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html - https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html - https://docs.agents-squads.com/guides/config-files

Perguntas frequentes

Quantos casos de teste precisamos?

O suficiente para cobrir as tarefas que você realmente envia e as maneiras pelas quais elas falham. Um punhado de trajetórias bem escolhidas supera um grande conjunto de trajetórias fáceis.

Podemos julgar saídas com outro modelo?

Você pode, mas registre que o juiz é um modelo e mantenha uma amostra fixa avaliada por humanos, para que você possa dizer se o próprio juiz mudou.

O que é fidelidade, concretamente?

Se cada afirmação na saída é suportada pelos resultados da ferramenta ou contexto que o agente recebeu, em vez de ser produzida a partir dos próprios priores do modelo.

Deveríamos pontuar apenas a resposta final?

Não. Pontue a trajetória também — as chamadas de ferramentas são onde a maioria das falhas do agente se origina.

Com que frequência as avaliações devem ser executadas?

Em cada alteração que possa afetar o comportamento: prompt, modelo, lista de ferramentas ou configuração de recuperação.

Um bom score significa que o agente é seguro?

Não. Significa que ele performou bem nas tarefas que você testou. Segurança, custo e tratamento de falhas são avaliações separadas.

Referências

- NIST — Estrutura de Gerenciamento de Riscos de IA - Stanford CRFM — HELM (Avaliação Holística de Modelos de Linguagem)

Experimente o produto: AgentGrade

2026-09-20 · somente fontes primárias · sem métricas de tráfego fabricadas · somente suporte à decisão

Artigos relacionados

- Avaliação offline versus monitoramento online para agentes de IA - Explore a matriz completa de tópicos de micro-SaaS de IA →