Avaliação

Métodos de Avaliação para Sistemas de Agentes

Avalie sistemas de agentes de forma diferente do software tradicional, porque os agentes tomam decisões dinâmicas, são não determinísticos entre execuções e muitas vezes carecem de respostas corretas únicas. Construa estruturas de avaliação que levem em conta essas características, forneçam feedback acionável, detectem regressões e validem se as escolhas de engenharia de contexto alcançam os efeitos pretendidos.

Quando Ativar

Ative esta habilidade quando:

• Testar o desempenho do agente sistematicamente
• Validar escolhas de engenharia de contexto
• Medir melhorias ao longo do tempo
• Detectar regressões antes da implantação
• Construir portões de qualidade para pipelines de agentes
• Comparar diferentes configurações de agentes
• Avaliar sistemas de produção continuamente

Não ative esta habilidade para trabalhos adjacentes de outras habilidades:

• Projetar o próprio juiz LLM, comparação pareada, calibração do juiz ou mitigação de viés: avaliacao-avancada.
• Projetar superfícies de controle autônomas, portões de novidade, rollback ou limites de aprovação de PR: engenharia-de-arneses.
• Depurar um modo de falha de contexto específico antes de medi-lo: degradacao-de-contexto.

Conceitos Principais

Concentre a avaliação nos resultados, em vez dos caminhos de execução, porque os agentes podem encontrar rotas alternativas válidas para as metas. Julgue se o agente alcança o resultado correto por meio de um processo razoável, não se seguiu uma sequência específica de etapas.

Use rubricas multidimensionais em vez de pontuações únicas, porque um número esconde falhas críticas em dimensões específicas. Capture precisão factual, completude, precisão de citação, qualidade da fonte e eficiência de ferramentas como dimensões separadas, depois pondere-as para o caso de uso.

Use a avaliação julgada por modelo somente após verificações determinísticas e rubricas estarem estáveis. Quando o trabalho se concentrar em prompts de juiz, comparação pareada, calibração ou mitigação de viés, mude para Avaliação Avançada.

Execute validação determinística antes do julgamento do LLM sempre que o artefato tiver estrutura verificável por máquina. Validade de esquema, chaves duplicadas, matemática de rubrica, sincronização de manifesto, status de recuperação e caminhos de evidência necessários devem falhar rapidamente antes que um avaliador gaste tokens ou retorne uma pontuação subjetiva.

Direcionadores de Desempenho

Aplique pesquisas de agentes de navegação ao projetar orçamentos de avaliação: uso de tokens, chamadas de ferramentas e escolha do modelo podem dominar a variância medida do desempenho (claim-evaluation-browsecomp-variance).

Fator	Variância Explicada	Implicação
Uso de tokens	Direcionador primário	Mais exploração pode melhorar o desempenho até que o custo ou a qualidade do contexto colapsem
Número de chamadas de ferramentas	Direcionador secundário	Mais uso de ferramentas ajuda apenas quando as chamadas recuperam evidências úteis
Escolha do modelo	Secundário, mas multiplicativo	Modelos melhores geralmente usam tokens e ferramentas de forma mais eficiente

Aja sobre essas implicações ao projetar avaliações:

• Defina orçamentos de tokens realistas: Avalie agentes com limites de tokens realistas de produção, não recursos ilimitados.
• Compare atualizações de modelo com aumentos de tokens: Modelos melhores podem usar tokens de forma mais eficiente do que modelos mais fracos com orçamentos maiores.
• Valide arquiteturas multiagente: Agentes extras adicionam tokens e chamadas de ferramentas; avalie-os em relação a baselines de agente único.

Tópicos Detalhados

Desafios de Avaliação

Lidar com Não Determinismo e Múltiplos Caminhos Válidos

Projete avaliações que tolerem variação de caminho, porque os agentes podem seguir caminhos válidos completamente diferentes para alcançar metas. Um agente pode pesquisar três fontes enquanto outro pesquisa dez; ambos podem produzir respostas corretas. Evite verificar etapas específicas. Em vez disso, defina critérios de resultado (correção, completude, qualidade) e pontue em relação a eles, tratando o caminho de execução como informativo, e não avaliativo.

Testar Falhas Dependentes de Contexto

Avalie em uma variedade de níveis de complexidade e comprimentos de interação, porque as falhas do agente geralmente dependem do contexto de maneiras sutis. Um agente pode ter sucesso em consultas simples, mas falhar em complexas, funcionar bem com um conjunto de ferramentas, mas falhar com outro, ou degradar após interação prolongada à medida que o contexto se acumula. Inclua casos de teste simples, médios, complexos e muito complexos para revelar esses padrões.

Pontuar Dimensões de Qualidade Compostas Separadamente

Divida a qualidade do agente em dimensões separadas (precisão factual, completude, coerência, eficiência de ferramenta, qualidade do processo) e pontue cada uma independentemente, porque um agente pode pontuar alto em precisão, mas baixo em eficiência, ou vice-versa. Em seguida, calcule agregados ponderados ajustados às prioridades do caso de uso. Essa abordagem revela quais dimensões precisam de melhoria, em vez de calcular a média do sinal.

Projeto de Rubrica de Avaliação

Construir Rubricas Multidimensionais

Defina rubricas cobrindo dimensões-chave com níveis descritivos de excelente a falhou. Inclua estas dimensões principais e adapte os pesos por caso de uso:

• Precisão factual: As afirmações correspondem à verdade básica (peso alto para tarefas de conhecimento)
• Completude: A saída cobre os aspectos solicitados (peso alto para tarefas de pesquisa)
• Precisão de citação: As citações correspondem às fontes reivindicadas (peso para contextos sensíveis à confiança)
• Qualidade da fonte: Usa fontes primárias apropriadas (peso para saídas autoritativas)
• Eficiência de ferramenta: Usa as ferramentas certas um número razoável de vezes (peso para sistemas sensíveis a custo)

Converter Rubricas em Pontuações Numéricas

Mapeie as avaliações de dimensão para pontuações numéricas (0,0 a 1,0), aplique pesos por dimensão e calcule pontuações gerais ponderadas. Defina limites de aprovação com base nos requisitos do caso de uso, tipicamente 0,7 para uso geral e 0,9 para aplicações de alto risco. Armazene as pontuações de dimensão individuais junto com o agregado, porque a discriminação orienta a melhoria direcionada.

Metodologias de Avaliação

Usar LLM-como-Juiz para Escala

Construa prompts de avaliação baseados em LLM que incluam: descrição clara da tarefa, a saída do agente sob teste, verdade básica quando disponível, uma escala de avaliação com descrições explícitas de nível e uma solicitação de julgamento estruturado com raciocínio. Juízes LLM fornecem avaliação consistente e escalável em grandes conjuntos de teste. Use uma família de modelos diferente da do agente sendo avaliado para evitar viés de autoaprimoramento.

Complementar com Avaliação Humana

Encaminhe casos extremos, consultas incomuns e uma amostra aleatória de tráfego de produção para revisores humanos, porque humanos percebem respostas alucinadas, falhas de sistema e vieses sutis que a avaliação automatizada perde. Acompanhe padrões nas revisões humanas para identificar problemas sistemáticos e alimente as descobertas de volta nos critérios de avaliação automatizada.

Aplicar Avaliação de Estado Final para Agentes com Estado

Para agentes que alteram estado persistente (arquivos, bancos de dados, configurações), avalie se o estado final corresponde às expectativas, em vez de como o agente chegou lá. Defina asserções de estado final esperadas e verifique-as programaticamente após cada execução de teste.

Projeto de Conjunto de Teste

Selecionar Amostras Representativas

Comece com amostras pequenas (20-30 casos) durante o desenvolvimento inicial, quando as mudanças têm impactos dramáticos e há frutos baixos abundantes. Escale para 50+ casos para sinal confiável à medida que o sistema amadurece. Amostre de padrões de uso reais, adicione casos extremos conhecidos e garanta cobertura entre níveis de complexidade.

Estratificar por Complexidade

Estruture conjuntos de teste em níveis de complexidade para evitar que exemplos fáceis inflacionem as pontuações:

• Simples: única chamada de ferramenta, consulta factual
• Médio: múltiplas chamadas de ferramenta, lógica de comparação
• Complexo: muitas chamadas de ferramenta, ambiguidade significativa
• Muito complexo: interação estendida, raciocínio profundo, síntese

Reporte as pontuações por estrato juntamente com as pontuações gerais para revelar onde o agente realmente luta.

Avaliação de Engenharia de Contexto

Validar Estratégias de Contexto Sistematicamente

Execute agentes com diferentes estratégias de contexto no mesmo conjunto de teste e compare pontuações de qualidade, uso de tokens e métricas de eficiência. Isso isola o efeito da engenharia de contexto de outras variáveis e evita decisões baseadas em anedotas.

Executar Testes de Degradação

Teste como a degradação do contexto afeta o desempenho executando agentes em diferentes tamanhos de contexto. Identifique penhascos de desempenho onde o contexto se torna problemático e estabeleça limites operacionais seguros. Alimente esses limites de volta nas estratégias de gerenciamento de contexto.

Avaliação Contínua

Construir Pipelines de Avaliação Automatizada

Integre a avaliação no fluxo de trabalho de desenvolvimento para que as avaliações sejam executadas automaticamente nas alterações do agente. Acompanhe os resultados ao longo do tempo, compare versões e bloqueie implantações que regridam em métricas-chave.

Monitorar a Qualidade da Produção

Amostre interações de produção e avalie-as continuamente. Defina alertas para quedas de qualidade abaixo dos limites de aviso (0,85 taxa de aprovação) e crítico (0,70 taxa de aprovação). Mantenha painéis mostrando análise de tendências em janelas de tempo para detectar degradação gradual.

Orientação Prática

Construindo Estruturas de Avaliação

Siga esta sequência para construir uma estrutura de avaliação, porque pular etapas iniciais leva a medições que não refletem a qualidade real:

1. Defina as dimensões de qualidade relevantes para o caso de uso antes de escrever qualquer código de avaliação, porque as dimensões escolhidas posteriormente tendem a refletir o que é fácil de medir, em vez do que importa.
2. Crie rubricas com definições de nível claras e descritivas para que os avaliadores (humanos ou LLM) produzam pontuações consistentes.
3. Construa conjuntos de teste a partir de padrões de uso reais e casos extremos, estratificados por complexidade, com pelo menos 50 casos para sinal confiável.
4. Implemente pipelines de avaliação automatizada que sejam executados em cada mudança significativa.
5. Estabeleça métricas de baseline antes de fazer alterações para que as melhorias possam ser medidas em relação a uma referência conhecida.
6. Execute avaliações em todas as mudanças significativas e compare com o baseline.
7. Acompanhe as métricas ao longo do tempo para análise de tendências, porque a degradação gradual é mais difícil de notar do que quedas repentinas.
8. Complemente a avaliação automatizada com revisão humana em uma cadência regular.
9. Separe as falhas de validação determinística dos julgamentos de qualidade para que artefatos inválidos não possam ser lavados por uma pontuação favorável do LLM.

Evitando Armadilhas de Avaliação

Proteja-se contra essas falhas comuns que prejudicam a confiabilidade da avaliação:

• Overfitting em caminhos específicos: Avalie resultados, não etapas específicas, porque os agentes encontram novos caminhos válidos.
• Ignorar casos extremos: Inclua diversos cenários de teste cobrindo todo o espectro de complexidade.
• Obsessão por métrica única: Use rubricas multidimensionais, porque uma única pontuação esconde falhas específicas de dimensão.
• Negligenciar efeitos de contexto: Teste com tamanhos e históricos de contexto realistas, em vez de condições de laboratório.
• Pular avaliação humana: A avaliação automatizada perde problemas sutis que os humanos detectam de forma confiável.

Exemplos

Exemplo 1: Avaliação Simples

def evaluate_agent_response(response, expected):
    rubric = load_rubric()
    scores = {}
    for dimension, config in rubric.items():
        scores[dimension] = assess_dimension(response, expected, dimension)
    overall = weighted_average(scores, config["weights"])
    return {"passed": overall >= 0.7, "scores": scores}

Exemplo 2: Estrutura do Conjunto de Teste

Os conjuntos de teste devem abranger vários níveis de complexidade para garantir uma avaliação abrangente:

test_set = [
    {
        "name": "simple_lookup",
        "input": "What is the capital of France?",
        "expected": {"type": "fact", "answer": "Paris"},
        "complexity": "simple",
        "description": "Single tool call, factual lookup"
    },
    {
        "name": "medium_query",
        "input": "Compare the revenue of Apple and Microsoft last quarter",
        "complexity": "medium",
        "description": "Multiple tool calls, comparison logic"
    },
    {
        "name": "multi_step_reasoning",
        "input": "Analyze sales data from Q1-Q4 and create a summary report with trends",
        "complexity": "complex",
        "description": "Many tool calls, aggregation, analysis"
    },
    {
        "name": "research_synthesis",
        "input": "Research emerging AI technologies, evaluate their potential impact, and recommend adoption strategy",
        "complexity": "very_complex",
        "description": "Extended interaction, deep reasoning, synthesis"
    }
]

Exemplo 3: Portão determinístico antes do julgamento do modelo

def evaluate_pr_candidate(candidate):
    structure = run_validate_repo(candidate)
    if not structure.ok:
        return {"passed": False, "reason": "deterministic validation failed", "details": structure.errors}

    quality = run_rubric_eval(candidate)
    return {"passed": quality.overall >= 0.8, "scores": quality.dimensions}

Exemplo 4: Dimensões do portão de qualidade

gate:
  deterministic:
    - schema_valid
    - required_files_present
    - no_duplicate_ids
  quality:
    factual_accuracy: min 0.85
    completeness: min 0.80
    source_traceability: min 0.90

Diretrizes

1. Use rubricas multidimensionais, não métricas únicas
2. Avalie resultados, não caminhos de execução específicos
3. Cubra níveis de complexidade de simples a complexo
4. Teste com tamanhos e históricos de contexto realistas
5. Execute avaliações continuamente, não apenas antes do lançamento
6. Complemente a avaliação do LLM com revisão humana
7. Acompanhe métricas ao longo do tempo para detecção de tendências
8. Defina limites claros de aprovação/reprovação com base no caso de uso

Armadilhas

1. Overfitting de avaliações em caminhos de código específicos: Os testes passam, mas o agente falha em pequenas variações de entrada. Escreva critérios de avaliação em relação a resultados e semântica, não padrões de superfície, e rotacione as entradas de teste periodicamente.
2. Viés de autoaprimoramento do juiz LLM: Os modelos avaliam suas próprias saídas mais alto do que juízes independentes. Use uma família de modelos diferente como juiz de avaliação do que o modelo sendo avaliado.
3. Contaminação do conjunto de teste: Exemplos de avaliação vazam para dados de treinamento ou modelos de prompt, inflacionando as pontuações. Mantenha os conjuntos de avaliação versionados e separados de quaisquer dados usados em prompts ou fine-tuning.
4. Jogo de métricas: Otimizar para a métrica de avaliação em vez da qualidade real.varie os conjuntos de teste e use múltiplas dimensões para evitar essa armadilha.

Informações de Contexto e Assistência

Consulte estes recursos para decisões de avaliação:

• regras-prompt-filestate.md para regras que governam como agentes interagem com sistemas de arquivos.
• design-de-teste-e-avaliacao.md para padrões de teste estruturados para sistemas de agentes.

Referências

• Diretrizes de avaliação de agentes: Confiabilidade, métricas e práticas recomendadas
• Pesquisa de variância de navegação e agente de compras para orçamentos de tokens
• Padrões de avaliação contínua para sistemas de produção
• Design de rubrica multidimensional para avaliação de LLM
• Estratégias de estratificação de conjunto de teste para sistemas de agentes