Avaliando a Qualidade do Agente: Um Checklist para Prontidão em Produção

Um checklist para pontuar a taxa de sucesso de tarefas, custo e modos de falha de um sistema de agente orquestrado antes de ir para produção. Este não é um framework geral de avaliação de LLM: trata-se especificamente das coisas que quebram em um sistema multiagente, como um subagente produzindo um resultado plausível, mas incorreto, uma etapa de mesclagem perdendo informações ou um roteador classificando incorretamente uma tarefa.

Como Usar Este Checklist

• Percorra a lista antes do primeiro lançamento em produção e novamente antes de qualquer alteração em um prompt, configuração de subagente ou lógica de roteamento.
• Para cada item, registre a métrica ou artefato que ele produz (uma pontuação, um log, um limite) para que o próximo revisor não comece do zero.
• Trate o nível "Aprovar/Reprovar" como um portão: não envie além dele apenas com base em julgamento.
• Reexecute todo o checklist, não apenas a peça alterada, sempre que o prompt de um subagente ou o acesso a ferramentas mudar. Sistemas multiagentes falham de maneiras que não permanecem locais à peça que você tocou.

Construindo o Conjunto de Avaliação

1. Taxa de sucesso de tarefas em um conjunto de avaliação fixo: pontue contra um conjunto curado de tarefas representativas, não verificações pontuais ad hoc.

   • Ad hoc: executar o agente no que vier à mente naquele dia e inspecionar a saída.
   • Conjunto de avaliação fixo: 30-100+ tarefas representativas com uma "resposta correta" definida ou critérios de aceitação, executadas da mesma maneira sempre.
   • Um conjunto fixo é o que torna uma pontuação comparável entre execuções; verificações ad hoc apenas informam sobre as entradas de hoje.

2. Cubra casos extremos e entradas adversárias no conjunto de avaliação, não apenas o caminho feliz. Inclua entradas malformadas, solicitações ambíguas que poderiam ser roteadas de duas maneiras e entradas projetadas para acionar o ponto cego de um subagente.

   • Conjuntos de avaliação apenas com o caminho feliz superestimam sistematicamente a qualidade, porque o tráfego de produção nunca é apenas o caminho feliz.
   • Obtenha casos extremos reais de qualquer QA manual existente, tickets de suporte ou uso inicial em beta em vez de inventá-los do zero.

3. Defina os critérios de aprovação/reprovação por tarefa antes de executar a avaliação, não depois. Escreva os critérios de aceitação no próprio conjunto de avaliação (campos esperados, fatos necessários, frases proibidas) para que a pontuação não varie com base em quem está lendo a transcrição naquele dia.

   • Critérios escritos após o fato tendem a se curvar para o que o modelo realmente produziu.
   • Uma rubrica com 3-5 verificações concretas por tarefa pontua de forma mais consistente do que uma única decisão de "isso foi bom?".

4. Automatize a pontuação sempre que possível e use uma segunda chamada do Claude como um juiz LLM para o restante. Verificações determinísticas (validação de esquema, presença de campo obrigatório, fatos de correspondência exata) nunca devem depender de um humano lendo transcrições.

   import asyncio
   from claude_agent_sdk import query
    
   async def judge_result(task: str, expected: str, actual: str) -> bool:
       prompt = (
           f"Tarefa: {task}\nEsperado: {expected}\nResultado real: {actual}\n\n"
           "O resultado real satisfaz a tarefa, permitindo diferenças de formulação, "
           "mas sem fatos ausentes ou incorretos? Responda apenas 'pass' ou 'fail'."
       )
       verdict = ""
       async for message in query(prompt=prompt):
           if message.get("type") == "text":
               verdict += message["text"]
       return "pass" in verdict.lower()

   • Um juiz LLM é mais rápido que um revisor humano e mais consistente do que "isso parece certo para mim", mas não é gratuito: reserve seu próprio custo de token e audite periodicamente seus vereditos contra uma amostra humana.
   • Reserve a revisão humana para as categorias no item 10, não para todo o conjunto de avaliação.

Medindo Custo e Latência

5. Custo por tarefa, incluindo sobrecarga de delegação, não apenas a chamada final do modelo. Uma única tarefa orquestrada pode gastar tokens na chamada de classificação do roteador, no contexto de cada subagente e em uma etapa de mesclagem que relê a saída de cada subagente.

   • Some o uso de tokens de cada chamada query() para uma tarefa de ponta a ponta, não apenas a resposta de nível superior que o usuário vê.
   • Uma tarefa que "custa US$ 0,02" contando apenas a resposta final pode, na verdade, custar US$ 0,11 após a inclusão da sobrecarga de delegação; essa diferença é o número que importa para uma decisão de precificação ou margem.

6. Compare o custo por tarefa entre os níveis de modelo antes de optar pelo modelo mais capaz em todos os lugares. Execute o mesmo conjunto de avaliação com um subagente mais barato (Claude Haiku 4.5) substituindo um mais caro (Claude Sonnet 5 ou Claude Opus 4.8) em tarefas que não precisam da capacidade extra.

   • Roteamento de sub-tarefas simples (classificação, extração, formatação) para um modelo mais barato é frequentemente a maior alavanca de custo em um sistema multiagente.
   • Não rebaixe o modelo de um subagente sem reexecutar o conjunto de avaliação contra ele; um modelo mais barato pode passar no caminho feliz e falhar nos casos extremos que você adicionou no item 2.

7. Latência e tempo de relógio por tarefa, não apenas por chamada de modelo. Cadeias de subagentes sequenciais se somam: três subagentes a 4 segundos cada mais uma etapa de mesclagem resultam em uma tarefa de 15+ segundos, mesmo que nenhuma chamada individual seja lenta.

   • Meça o tempo de relógio de ponta a ponta no conjunto de avaliação, incluindo quaisquer retentativas.
   • Se a latência for visível para o usuário, decida antecipadamente se as sub-tarefas independentes devem ser executadas em paralelo (veja o padrão de fan-out em Noções Básicas de Orquestração de Agentes) em vez de descobrir o custo serial em produção.

8. Acompanhe o crescimento do uso de tokens à medida que a complexidade da conversa ou da tarefa aumenta. Um subagente que funciona bem em uma tarefa curta pode ultrapassar seu orçamento de contexto em uma tarefa mais longa, truncando silenciosamente as instruções anteriores.

   • Inclua pelo menos algumas tarefas de longa duração ou de várias etapas no conjunto de avaliação especificamente para capturar isso.
   • Um número de custo ou latência que vem apenas de tarefas de avaliação curtas não preverá o que acontece quando o uso real incluir sessões mais longas.

Nomeando Modos de Falha

9. Construa uma taxonomia de modos de falha: nomeie o que especificamente quebrou, não apenas "falhou". No mínimo, acompanhe estas categorias separadamente, pois cada uma tem uma correção diferente:

   Modo de falha	O que parece	Correção típica
   Resultado de subagente plausível, mas incorreto	O subagente retorna uma resposta confiante e bem formatada que é factualmente incorreta	Adicione critérios de verificação de fatos ao conjunto de avaliação; considere um subagente de verificação
   Etapa de mesclagem perdendo informações	O orquestrador combina as saídas dos subagentes, mas omite um detalhe que um deles retornou	Registre o resultado bruto de cada subagente ao lado da saída mesclada; teste a etapa de mesclagem isoladamente
   Classificação incorreta do roteador	A tarefa é enviada para o subagente errado (relatório de bug roteado para o definidor de recursos, ou vice-versa)	Adicione casos de roteamento ambíguo ao conjunto de avaliação; registre a decisão de roteamento separadamente do resultado final
   Falha na chamada de ferramenta	A chamada de ferramenta de um subagente falha (argumentos incorretos, permissões, dependência instável) e o orquestrador não percebe	Envolva as chamadas de ferramenta com lógica de retentativa e disjuntor (veja Estratégias de Recuperação de Erros e Retentativas em Loops de Agente)
   Delegação descontrolada	Um subagente gera subagentes adicionais além da profundidade pretendida, inflando custo e latência	Limite a profundidade de delegação explicitamente em SubagentConfig, não confie no modelo para se autolimitar

   • Um único contador de "falha" informa que algo está errado; uma taxonomia informa o que corrigir e aproximadamente a urgência.
   • Marque cada tarefa de avaliação com falha com uma dessas categorias (ou uma específica do projeto) para que a taxonomia permaneça um artefato vivo, não uma lista única.

10. Amostre a revisão humana de uma porcentagem fixa de saídas de produção, não apenas de saídas de avaliação. Um conjunto de avaliação, por melhor que seja, ainda é um instantâneo; o tráfego de produção varia.

    • Escolha uma taxa fixa (1-5% das tarefas é um ponto de partida razoável para a maioria das cargas de trabalho) e revise essa amostra em uma cadência regular, não apenas quando algo parecer quebrado.
    • Alimente qualquer coisa que um revisor humano marque como incorreta de volta ao conjunto de avaliação como um novo caso de teste, para que o conjunto de avaliação cresça para cobrir os modos de falha que o uso real apresenta.

Testes de Regressão e Portões de Lançamento

11. Reexecute todo o conjunto de avaliação antes de enviar qualquer alteração de prompt ou configuração de subagente, não apenas a peça que você alterou. Uma alteração de prompt em um subagente pode mudar o comportamento de classificação do roteador ou alterar o que a etapa de mesclagem recebe.

    • Compare os resultados de aprovação/reprovação da nova execução com a execução anterior por tarefa, não apenas a pontuação agregada, para que uma regressão em uma categoria de tarefa específica não seja diluída pela média.
    • Armazene os resultados da avaliação por execução (timestamp, versão da configuração, pontuação) para que uma regressão seja rastreável à alteração que a causou.

12. Defina um limite explícito de aprovação/reprovação antes do lançamento e escreva-o. Esperar até que os resultados estejam disponíveis para decidir o que é "bom o suficiente" convida a mover a meta para corresponder à pontuação que você obteve.

    • Uma barra inicial razoável: taxa de sucesso de tarefas de ponta a ponta acima de uma porcentagem definida no conjunto de avaliação, com zero falhas em qualquer categoria que você marcou como de alta gravidade (perda de dados, ação incorreta tomada, saída insegura).
    • Documente o limite e quem é o responsável pela decisão de substituí-lo, pois a pressão de produção eventualmente produzirá um caso para enviar abaixo da barra.

13. Monitore a taxa de sucesso de tarefas, o custo e a taxonomia de falhas após o lançamento, não apenas antes dele. A avaliação pré-lançamento informa como o sistema se comporta com as entradas que você pensou; o monitoramento informa como ele se comporta com as entradas reais de produção.

    • Acompanhe os mesmos três números deste checklist (taxa de sucesso, custo por tarefa, detalhamento dos modos de falha) como métricas de produção contínuas, idealmente no mesmo painel usado para a avaliação pré-lançamento.
    • Alerte sobre uma queda na taxa de sucesso ou um pico em uma categoria de falha específica, da mesma forma que alertaria sobre uma taxa de erro para um serviço tradicional. Veja Instrumentando Loops de Agente com Rastreamento OpenTelemetry para configurar isso.

Aplicando o Checklist em Ordem

• Fundação da Avaliação (1-4): construa e defina o conjunto de avaliação primeiro. Todos os números posteriores dependem de ter um conjunto fixo e pontuado de tarefas para executar.
• Custo e Latência (5-8): meça o custo real do sistema como construído, incluindo a sobrecarga de delegação, antes de otimizar qualquer coisa.
• Taxonomia de Falhas (9-10): nomeie os modos de falha com precisão suficiente para que uma correção seja óbvia a partir da categoria, e mantenha uma amostra de revisão humana fluindo de volta para o conjunto de avaliação.
• Portões e Monitoramento (11-13): transforme o conjunto de avaliação em um portão de regressão repetível, e depois continue medindo os mesmos números após o lançamento.

Armadilhas

• Pontuar apenas o caminho feliz - Um conjunto de avaliação construído a partir de tarefas fáceis e obviamente corretas relatará uma taxa de sucesso que a produção nunca atinge. Correção: semeie deliberadamente o conjunto de avaliação com casos extremos e entradas adversárias (item 2).
• Contar apenas o custo da chamada final do modelo - A sobrecarga de delegação de roteamento e etapas de mesclagem é invisível se você registrar apenas o uso de tokens da resposta de nível superior. Correção: some cada chamada query() dentro de uma tarefa (item 5).
• Tratar "falhou" como um único balde - Um contador de falhas genérico não pode dizer se a correção é uma alteração de prompt, uma política de retentativa ou uma regra de roteamento. Correção: marque cada falha com uma categoria da taxonomia (item 9).
• Pular execuções de regressão em alterações "pequenas" de prompt - Uma edição de prompt de uma linha em um subagente pode mudar o comportamento de classificação de um roteador de maneiras que só aparecem em tarefas de avaliação específicas. Correção: reexecute todo o conjunto de avaliação, não uma verificação pontual, antes de enviar qualquer alteração de configuração (item 11).
• Parar a avaliação no lançamento - O tráfego de produção se desvia do que o conjunto de avaliação cobriu no primeiro dia. Correção: continue monitorando os mesmos três números (taxa de sucesso, custo, taxonomia de falhas) após o lançamento e alimente os achados da revisão humana de volta ao conjunto de avaliação (itens 10 e 13).

FAQs

Relacionados

• Estratégias de Recuperação de Erros e Retentativas em Loops de Agente - retentativas, fallbacks e disjuntores para o modo de falha de chamada de ferramenta acima
• Modelo de ADR: Agente Único vs. Orquestrador para um Novo Fluxo de Trabalho - decidindo se a orquestração é justificada antes de ter que avaliá-la
• Orquestração de Agentes e Melhores Práticas Multiagente - práticas de design mais amplas que este checklist assume
• Instrumentando Loops de Agente com Rastreamento OpenTelemetry - configurando os números de monitoramento pós-lançamento em rastros reais
• Modelo de Análise de Causa Raiz para Falhas de Agente - um modelo para investigar uma falha específica quando a taxonomia a sinaliza

Versões da Stack: Escrito contra a linha de modelos Claude atual por volta de junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o Claude Agent SDK (última versão). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.