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

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.
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.
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?".

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

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.
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.
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.
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

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.

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

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.
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.
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

O que torna isso diferente de um checklist geral de avaliação de LLM?

Uma avaliação geral de LLM pontua a saída de um modelo contra uma tarefa.
Este checklist pontua um sistema orquestrado: decisões de roteamento, resultados por subagente e como uma etapa de mesclagem os combina.
Modos de falha específicos da orquestração, como um roteador que classifica incorretamente uma tarefa ou uma etapa de mesclagem que omite uma descoberta de subagente, não aparecem se você apenas avaliar a saída final isoladamente.

Quantas tarefas o conjunto de avaliação deve ter?

30-100+ tarefas representativas é um intervalo inicial razoável para a maioria dos sistemas.
Menos de 30 tende a tornar a taxa de sucesso ruidosa de uma execução para outra.
Aumente o conjunto ao longo do tempo alimentando falhas reais encontradas durante a revisão humana (item 10).

Devo pontuar a taxa de sucesso por subagente ou apenas a taxa de sucesso de tarefas de ponta a ponta?

Ambos, e separadamente. A taxa de sucesso de ponta a ponta é o que o usuário experimenta; a taxa de sucesso por subagente informa qual peça corrigir.
Um sistema pode ter uma baixa taxa de ponta a ponta mesmo quando cada subagente individual pontua bem, se a etapa de mesclagem for o elo fraco.
Registre ambos os números em cada execução de avaliação para que uma regressão seja rastreável a um subagente específico ou à própria camada de orquestração.

Um juiz LLM pode substituir completamente a revisão humana?

Não. Um juiz LLM é bom para escala e consistência em critérios de aprovação/reprovação bem definidos, mas pode compartilhar os mesmos pontos cegos que o modelo que ele está julgando.
Mantenha uma porcentagem fixa de revisão humana em saídas de produção (item 10) mesmo após a implementação de um juiz LLM.
Audite periodicamente os vereditos do juiz contra uma amostra humana para confirmar que ele ainda está calibrado.

O que conta como "sobrecarga de delegação" no custo por tarefa?

Qualquer gasto de token além da única chamada que produz a resposta visível para o usuário: a chamada de classificação de um roteador, o contexto e o prompt do sistema de cada subagente, e uma etapa de mesclagem que lê a saída de cada subagente.
Somar apenas os tokens da resposta final rotineiramente subestima o custo real em uma margem ampla em um sistema multi-hop.
O item 5 cobre como medi-lo diretamente.

Por que separar "plausível, mas incorreto" de outras categorias de falha?

Um resultado plausível, mas incorreto, passa na revisão casual porque parece correto; é o modo de falha mais difícil de capturar sem uma rubrica ou etapa de verificação de fatos.
Ele precisa de uma correção diferente (verificação, critérios de verificação de fatos) do que um erro de chamada de ferramenta ou um erro de roteamento, razão pela qual a taxonomia no item 9 o mantém separado.
Estas também são as falhas mais propensas a passar por um conjunto de avaliação que apenas verifica a formatação ou a presença de campos obrigatórios.

Como capturar uma etapa de mesclagem que está perdendo informações?

Registre o resultado bruto de cada subagente ao lado da saída mesclada do orquestrador e, em seguida, compare-os em uma amostra de tarefas de avaliação.
Se um detalhe presente no resultado de um subagente estiver faltando na saída mesclada, isso é um defeito de mesclagem, não um defeito de subagente.
Teste a etapa de mesclagem isoladamente com um conjunto fixo de saídas de subagente, da mesma forma que você testaria qualquer outra função de combinação de dados.

Qual é um limite razoável de aprovação/reprovação para começar?

Não há um número universal: escolha uma taxa de sucesso de tarefas no conjunto de avaliação que corresponda a quanta saída incorreta seu caso de uso pode tolerar e defina-a como zero para qualquer categoria de falha de alta gravidade (perda de dados, saída insegura, ação incorreta tomada).
O que importa mais do que o número específico é escrevê-lo antes do lançamento e nomear quem é o responsável pela decisão de substituí-lo.
Revise o limite à medida que o conjunto de avaliação cresce para cobrir mais casos extremos; um limite desatualizado medido contra um conjunto de avaliação desatualizado subestima o risco real.

Preciso reexecutar todo o conjunto de avaliação para uma alteração de prompt de uma linha?

Sim. Uma pequena edição de prompt em um subagente pode mudar o comportamento de classificação de um roteador ou alterar o que uma etapa de mesclagem recebe, de maneiras que não permanecem locais à peça que você tocou.
Compare a 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 não seja diluída por melhorias em outros lugares.

Como o monitoramento após o lançamento difere da avaliação pré-lançamento?

O conjunto de avaliação mede o comportamento em entradas que você pensou em incluir; o monitoramento mede o comportamento em entradas reais de produção, que variam ao longo do tempo.
Acompanhe os mesmos três números (taxa de sucesso, custo por tarefa, detalhamento dos modos de falha) como métricas contínuas, não apenas como uma pontuação única pré-lançamento.
Alimente qualquer coisa que o monitoramento ou a revisão humana apresentem de volta ao conjunto de avaliação para que ele acompanhe o tráfego real.

Qual é a maior alavanca de custo em um sistema multiagente?

Roteamento de sub-tarefas simples, classificação, extração, formatação, para um nível de modelo mais barato em vez de executar cada subagente no modelo mais capaz.
O item 6 cobre a comparação do custo por tarefa entre os níveis de modelo no mesmo conjunto de avaliação antes de fazer essa troca.
Sempre reexecute o conjunto de avaliação contra o modelo mais barato antes de confiar nele; um modelo de menor custo ainda pode passar no caminho feliz e falhar nos casos extremos.

A latência deve ser medida por chamada de modelo ou por tarefa?

Por tarefa, de ponta a ponta, incluindo quaisquer retentativas. Cadeias de subagentes sequenciais se somam, mesmo quando nenhuma chamada individual é lenta.
Se a latência for visível para o usuário, decida se as sub-tarefas independentes devem ser executadas em paralelo em vez de descobrir o custo serial após o lançamento.

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.

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

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

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.
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.
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?".

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

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.
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.
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.
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

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.

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

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.
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.
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

O que torna isso diferente de um checklist geral de avaliação de LLM?

Uma avaliação geral de LLM pontua a saída de um modelo contra uma tarefa.
Este checklist pontua um sistema orquestrado: decisões de roteamento, resultados por subagente e como uma etapa de mesclagem os combina.
Modos de falha específicos da orquestração, como um roteador que classifica incorretamente uma tarefa ou uma etapa de mesclagem que omite uma descoberta de subagente, não aparecem se você apenas avaliar a saída final isoladamente.

Quantas tarefas o conjunto de avaliação deve ter?

30-100+ tarefas representativas é um intervalo inicial razoável para a maioria dos sistemas.
Menos de 30 tende a tornar a taxa de sucesso ruidosa de uma execução para outra.
Aumente o conjunto ao longo do tempo alimentando falhas reais encontradas durante a revisão humana (item 10).

Devo pontuar a taxa de sucesso por subagente ou apenas a taxa de sucesso de tarefas de ponta a ponta?

Ambos, e separadamente. A taxa de sucesso de ponta a ponta é o que o usuário experimenta; a taxa de sucesso por subagente informa qual peça corrigir.
Um sistema pode ter uma baixa taxa de ponta a ponta mesmo quando cada subagente individual pontua bem, se a etapa de mesclagem for o elo fraco.
Registre ambos os números em cada execução de avaliação para que uma regressão seja rastreável a um subagente específico ou à própria camada de orquestração.

Um juiz LLM pode substituir completamente a revisão humana?

Não. Um juiz LLM é bom para escala e consistência em critérios de aprovação/reprovação bem definidos, mas pode compartilhar os mesmos pontos cegos que o modelo que ele está julgando.
Mantenha uma porcentagem fixa de revisão humana em saídas de produção (item 10) mesmo após a implementação de um juiz LLM.
Audite periodicamente os vereditos do juiz contra uma amostra humana para confirmar que ele ainda está calibrado.

O que conta como "sobrecarga de delegação" no custo por tarefa?

Qualquer gasto de token além da única chamada que produz a resposta visível para o usuário: a chamada de classificação de um roteador, o contexto e o prompt do sistema de cada subagente, e uma etapa de mesclagem que lê a saída de cada subagente.
Somar apenas os tokens da resposta final rotineiramente subestima o custo real em uma margem ampla em um sistema multi-hop.
O item 5 cobre como medi-lo diretamente.

Por que separar "plausível, mas incorreto" de outras categorias de falha?

Um resultado plausível, mas incorreto, passa na revisão casual porque parece correto; é o modo de falha mais difícil de capturar sem uma rubrica ou etapa de verificação de fatos.
Ele precisa de uma correção diferente (verificação, critérios de verificação de fatos) do que um erro de chamada de ferramenta ou um erro de roteamento, razão pela qual a taxonomia no item 9 o mantém separado.
Estas também são as falhas mais propensas a passar por um conjunto de avaliação que apenas verifica a formatação ou a presença de campos obrigatórios.

Como capturar uma etapa de mesclagem que está perdendo informações?

Registre o resultado bruto de cada subagente ao lado da saída mesclada do orquestrador e, em seguida, compare-os em uma amostra de tarefas de avaliação.
Se um detalhe presente no resultado de um subagente estiver faltando na saída mesclada, isso é um defeito de mesclagem, não um defeito de subagente.
Teste a etapa de mesclagem isoladamente com um conjunto fixo de saídas de subagente, da mesma forma que você testaria qualquer outra função de combinação de dados.

Qual é um limite razoável de aprovação/reprovação para começar?

Não há um número universal: escolha uma taxa de sucesso de tarefas no conjunto de avaliação que corresponda a quanta saída incorreta seu caso de uso pode tolerar e defina-a como zero para qualquer categoria de falha de alta gravidade (perda de dados, saída insegura, ação incorreta tomada).
O que importa mais do que o número específico é escrevê-lo antes do lançamento e nomear quem é o responsável pela decisão de substituí-lo.
Revise o limite à medida que o conjunto de avaliação cresce para cobrir mais casos extremos; um limite desatualizado medido contra um conjunto de avaliação desatualizado subestima o risco real.

Preciso reexecutar todo o conjunto de avaliação para uma alteração de prompt de uma linha?

Sim. Uma pequena edição de prompt em um subagente pode mudar o comportamento de classificação de um roteador ou alterar o que uma etapa de mesclagem recebe, de maneiras que não permanecem locais à peça que você tocou.
Compare a 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 não seja diluída por melhorias em outros lugares.

Como o monitoramento após o lançamento difere da avaliação pré-lançamento?

O conjunto de avaliação mede o comportamento em entradas que você pensou em incluir; o monitoramento mede o comportamento em entradas reais de produção, que variam ao longo do tempo.
Acompanhe os mesmos três números (taxa de sucesso, custo por tarefa, detalhamento dos modos de falha) como métricas contínuas, não apenas como uma pontuação única pré-lançamento.
Alimente qualquer coisa que o monitoramento ou a revisão humana apresentem de volta ao conjunto de avaliação para que ele acompanhe o tráfego real.

Qual é a maior alavanca de custo em um sistema multiagente?

Roteamento de sub-tarefas simples, classificação, extração, formatação, para um nível de modelo mais barato em vez de executar cada subagente no modelo mais capaz.
O item 6 cobre a comparação do custo por tarefa entre os níveis de modelo no mesmo conjunto de avaliação antes de fazer essa troca.
Sempre reexecute o conjunto de avaliação contra o modelo mais barato antes de confiar nele; um modelo de menor custo ainda pode passar no caminho feliz e falhar nos casos extremos.

A latência deve ser medida por chamada de modelo ou por tarefa?

Por tarefa, de ponta a ponta, incluindo quaisquer retentativas. Cadeias de subagentes sequenciais se somam, mesmo quando nenhuma chamada individual é lenta.
Se a latência for visível para o usuário, decida se as sub-tarefas independentes devem ser executadas em paralelo em vez de descobrir o custo serial após o lançamento.

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.

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

Buscar na documentação

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