Objetivos de aprendizado:
- Escrever uma rubrica multidimensional para saídas em texto livre, deixar clara a pergunta de cada dimensão e entender que um único critério de sucesso muitas vezes precisa de várias rubricas para ser avaliado por inteiro
- Apertar a saída do juiz até um formato que programas consigam tratar: primeiro o raciocínio, depois a nota, de 0.0 a 1.0 mais aprovado/reprovado, e explicar por que uma única chamada costuma ser mais estável do que vários juízes avaliando aspectos separados
- Reconhecer três modos de falha dos juízes — corrigir o próprio trabalho, receber a ordem de achar problemas e por isso sempre achar, confiar apenas no autorrelato do agente — e apresentar mitigações acionáveis para cada um
Pré-requisitos: Lições 1–3, com o entendimento da avaliação “estado final primeiro” e da prioridade dos verificadores determinísticos | Anterior: << Lição 3 | Próxima: Lição 5 >>
Você passou uma tarefa ao seu agente de pesquisa: resumir como os subsídios domésticos para recarga de veículos elétricos mudaram nos últimos três anos e produzir um relatório de duas páginas. Ele rodou por quinze minutos, chamou ferramentas de busca, baixou PDFs, escreveu 1.800 palavras. A leitura é plausível.
Agora você quer verificar. Nenhuma das verificações determinísticas da lição 3 se aplica aqui: não há suíte de testes para rodar, não há código de saída de build para ler, não há golden_answer para output == golden_answer porque você não consegue escrever um — coloque dois analistas humanos no mesmo relatório e eles não vão produzir textos idênticos.
Isso não é falta de imaginação. É assim que essas saídas são. Quando a Anthropic refletiu sobre seu sistema de pesquisa multiagente, foi direta: saídas de pesquisa são texto livre, raramente têm uma única resposta correta e por isso são difíceis de avaliar programaticamente — LLMs são um encaixe natural para corrigir saídas desse tipo1.
Mas antes de jogar o relatório despreocupadamente para outro modelo e perguntar “o que achou disso”, entenda onde os juízes LLM ficam na ordenação oficial. O princípio para escolher um método de correção é "fastest, most reliable, most scalable" (o mais rápido, mais confiável e mais escalável)2: a correção por código é a mais rápida e mais confiável, escala muitíssimo bem, mas carece de nuance para julgamentos complexos que exigem menos rigidez baseada em regras2; a correção por LLM é rápida, flexível, escalável e adequada a julgamentos complexos — e a orientação oficial emparelha isso com um pré-requisito na mesma frase: teste primeiro para garantir a confiabilidade e só então escale2; a correção humana é a mais flexível e de maior qualidade, mas lenta e cara, então evite se possível2.
Trate o pré-requisito daquela opção do meio como exigência rígida, não como ressalva. Um juiz LLM não é “uma verificação mais inteligente”, é uma chamada de modelo: ele pode errar, custa dinheiro e pode pontuar a mesma entrada de formas diferentes em execuções sucessivas. Seu valor é singular — ele alcança coisas que verificações determinísticas não alcançam.
Então esta lição não é sobre “como fazer um modelo pontuar sua saída”. Isso é trivial — qualquer prompt devolve um número. É sobre tornar esse número digno de confiança: como estruturar rubricas, como restringir a saída, quem roda o juiz, como ele quebra e quando você não deveria nem perguntar.
Rubrica soa formal. Em termos simples, é um boletim: quebre o vago “isto está bom” em perguntas específicas, responda cada uma separadamente, pontue cada uma separadamente.
Por que quebrar? Pergunte “este relatório está bom” e o modelo devolve elogio vago ou crítica vaga. Pergunte “toda afirmação do relatório aparece nas fontes citadas” e o modelo consegue conferir afirmação por afirmação. A maioria dos casos de uso precisa de avaliação multidimensional ao longo de vários critérios de sucesso2.
O agente de pesquisa da Anthropic usou uma rubrica de cinco dimensões1, cada dimensão atrás de um modo de falha real:
Essas cinco dimensões são para tarefas de pesquisa. Tarefas diferentes precisam de conjuntos diferentes. O que dá para levar é o método de decomposição: comece de “se esta saída quebrar, como ela quebra”, derive as dimensões disso, um modo de falha por dimensão. E não deixe passar: um dado caso de uso, ou mesmo um critério de sucesso específico desse caso, pode exigir várias rubricas para uma avaliação holística2. Não espere que um único boletim cubra tudo.
Primeiro, o formato do veredito. A Anthropic testou vários juízes avaliando componentes diferentes — um juiz por componente. O resultado: uma única chamada de LLM com um único prompt, devolvendo notas de 0.0 a 1.0 e uma nota de aprovado/reprovado, foi o mais consistente e mais alinhado com julgamentos humanos1.
Vale a ressalva justa: quebrar a avaliação em várias chamadas de LLM, cada chamada avaliando um aspecto, é em si um padrão de automação de evals que a orientação oficial já descreveu3. Nenhuma das duas abordagens está errada. A diferença é que “uma única chamada é melhor” vem da comparação que a Anthropic fez no próprio sistema real1. Abordagem recomendada: comece com uma única chamada e só divida se você tiver evidência de que dividir melhora a precisão.
Em seguida, o quanto restringir a saída. A orientação oficial para prompts de juiz é "empirical or specific" (empírica ou específica): por exemplo, instrua o LLM a devolver apenas 'correct' ou 'incorrect', ou a julgar numa escala de 1–5; avaliações puramente qualitativas são difíceis de apurar rapidamente e em escala2. Em termos simples: se o juiz devolve “qualidade geral aceitável, mas alguns detalhes tratados de forma um pouco tosca”, você não tem nada — não dá para tirar média de 200 respostas dessas, não dá para dizer se hoje está melhor que ontem, e você ainda tem que ler uma por uma. Então para que perguntar ao juiz?
A técnica crítica: primeiro o raciocínio, depois a nota, e então descarte o raciocínio. A orientação oficial afirma isso explicitamente: peça ao LLM que raciocine antes de produzir uma nota de avaliação e depois descarte o raciocínio — isso aumenta o desempenho da avaliação, particularmente em tarefas que exigem julgamento complexo2. “Descartar” não quer dizer não olhar. O raciocínio é o andaime do juiz — ele precisa escrever “a afirmação do parágrafo 3 mapeia para qual trecho da transcrição” antes de conseguir julgar com precisão. Mas esse texto não deve entrar nas suas estatísticas rio abaixo. O relatório quer notas e aprovado/reprovado; o raciocínio vai para os logs, esperando por você quando uma nota parecer suspeita.
E as dimensões subjetivas? Algumas dimensões não podem ser binárias, como “o tom deste relatório é apropriado para enviar a clientes?”. A orientação oficial oferece uma ferramenta: a escala Likert baseada em LLM, que usa um LLM para julgar atitudes ou percepções subjetivas2 — uma escala Likert são aqueles formatos de questionário com incrementos fixos, do tipo “discordo totalmente / discordo / neutro / concordo / concordo totalmente” (a quantidade de pontos é convenção de desenho de pesquisa, não exigência oficial). O princípio central continua valendo: dê incrementos fixos, não deixe o juiz escrever livremente.
Juntando tudo, a saída do juiz fica mais ou menos assim (o exemplo mostra só as três primeiras dimensões; source_quality e tool_efficiency têm o mesmo formato e foram omitidas por brevidade). Os programas leem score e verdict; reasoning é persistido para revisão:
Neste ponto aparece um atalho tentador: fazer o agente se corrigir no final. Ele é quem melhor sabe o que acabou de fazer.
Reprima essa tentação. Duas razões. Primeiro, a experiência oficial: implementar guardrails em que uma instância do modelo processa as consultas do usuário enquanto outra as filtra em busca de conteúdo ou pedidos inapropriados tende a funcionar melhor do que deixar a mesma chamada de LLM cuidar tanto dos guardrails quanto da resposta principal3 — essa experiência descrevia originalmente moderação de conteúdo (uma instância responde, outra filtra), mas o princípio “não deixe a mesma chamada usar os dois chapéus” se aplica aqui. Repare que diz “mesma chamada” — o problema é contexto compartilhado, não inteligência insuficiente. Segundo, o mecanismo: a documentação oficial do Claude Code descreve uma prática em que um revisor rodando em um contexto novo de subagente vê apenas o diff e os critérios que você deu, não o raciocínio que produziu a mudança, e por isso avalia o resultado nos termos dele mesmo4.
Leia de trás para frente para ver por que a autocorreção falha: a cadeia de raciocínio que produziu a saída ainda está pendurada no contexto. O modelo acabou de se convencer de que “escrever assim está correto”, você emenda logo em seguida com “isto está correto”, e ele provavelmente vai repetir o mesmo raciocínio. O que você recebe não é um julgamento independente, é autorrepetição.
Se você está preocupado que o juiz seja brando ou rígido demais, a orientação oficial oferece um botão de ajuste: avaliar se um dado conteúdo é inapropriado, com vários prompts avaliando aspectos diferentes ou exigindo limiares de voto diferentes para equilibrar falsos positivos e falsos negativos3. Num cenário de verificação, um falso positivo é “marcar como quebrado algo que está bem” — você vai ser torturado por alarmes falsos; um falso negativo é “deixar passar algo quebrado” — trabalho ruim vai para produção. Três juízes em que dois precisam dizer reprovado para valer como reprovado é mais brando do que um juiz cujo reprovado já vale — qual configuração você escolhe depende de qual tipo de erro custa mais no seu cenário.
Você já trocou para uma instância diferente, já escreveu uma rubrica, e o juiz ainda quebra. Ele quebra de maneiras previsíveis.
Um: revisores mandados achar problemas sempre vão achar problemas. O mais contraintuitivo, o mais caro. A documentação oficial é clara: um revisor instruído a encontrar lacunas normalmente vai reportar algumas, mesmo quando o trabalho está sólido, porque foi isso que se pediu a ele4. A consequência não é só “algumas sugestões inúteis”: a mesma passagem observa que perseguir cada achado leva a superengenharia — camadas extras de abstração, código defensivo e testes para casos que não podem acontecer4. Seu agente entra num loop de autoescalada: o revisor sugere três coisas, você corrige, a nova revisão sugere mais três, o código engorda, os problemas reais continuam sem solução.
Você provavelmente já viu esses relatórios: “sugiro acrescentar defesa contra string vazia em parseDate” — mas o passo anterior já garante que não é vazia; “sugiro extrair estas três constantes para configuração” — mas elas não mudam há três anos; “sugiro acrescentar testes de retry para timeout de rede” — mas este caminho não faz chamadas de rede. Nenhuma das três está errada, nenhuma das três vale a pena, mas misturadas num relatório de revisão elas parecem idênticas a problemas reais.
A orientação oficial fornece a mitigação: diga ao revisor para sinalizar apenas lacunas que afetam a correção ou os requisitos declarados, e trate o resto como opcional4. Escreva isso literalmente no prompt do juiz e dê às “outras sugestões” um lugar para ir — acrescente um campo optional_notes e declare explicitamente que ele não participa da pontuação. Ter onde escrever significa não precisar espremer preferências de estilo dentro de justificativas de desconto.
Dois: o autorrelato do agente não é evidência. Muita gente toma um atalho e alimenta o juiz só com o resumo final do agente: “recuperei três fontes autoritativas e fiz verificação cruzada antes de confirmar a taxa do subsídio”. O juiz lê, acha que o processo soa sólido, dá nota alta. Mas essa afirmação não é evidência. A orientação oficial sobre avaliação de ferramentas faz o ponto: o que os agentes omitem em seus retornos e respostas costuma ser mais importante do que o que eles incluem — LLMs nem sempre dizem o que querem dizer5. Ele diz “verifiquei três fontes de forma cruzada”, mas talvez tenha chamado a busca só uma vez; o retry que falhou e ele não menciona, o momento em que recebeu resultados vazios e continuou inventando, é justamente o que você mais precisa ver. A solução também é direta: revise as transcrições brutas (incluindo chamadas de ferramenta e respostas de ferramenta) para pegar qualquer comportamento não descrito explicitamente na cadeia de raciocínio do agente5. Traduzindo para uma solução: a entrada do juiz precisa incluir logs brutos, não só o autorrelato. A dimensão “eficiência de ferramentas” precisa disso em especial — ela avalia o número real de chamadas e se as chamadas estavam corretas; essa informação só existe nos logs.
Três: a própria pergunta é ambígua. A rigor isso não é o juiz quebrando, é você tendo dado a ele uma pergunta quebrada. A orientação oficial sobre desenho de eval nomeia uma categoria a evitar: casos de teste ambíguos em que mesmo humanos teriam dificuldade de chegar a um consenso de avaliação2. Você vai reconhecê-los ao validar o juiz: você e um colega julgam a mesma saída e chegam a resultados opostos. Não corra para consertar o prompt do juiz — o juiz é “impreciso” porque esta pergunta não tem resposta precisa. Ou você refina os critérios até humanos conseguirem concordar, ou remove o caso. Usá-lo para calcular a taxa de consistência do juiz só produz um número autoenganoso.
O juiz termina e acabou, ou você alimenta o retorno dele de volta ao agente para uma revisão e julga de novo? Esse loop é tentador, e vira facilmente um moto-perpétuo queimando tokens.
A orientação oficial dá dois sinais de quando esse workflow realmente encaixa3: primeiro, que as respostas do LLM podem ser demonstravelmente melhoradas quando um humano articula seu retorno; e segundo, que o LLM consegue fornecer esse tipo de retorno. A mesma passagem acrescenta um pré-requisito: esse workflow é particularmente eficaz quando temos critérios de avaliação claros e quando o refinamento iterativo entrega valor mensurável3.
Use essas duas condições como testes de admissão. A abordagem é direta: seja você o juiz primeiro, escreva o retorno para o agente, veja se ele de fato melhora depois da revisão. Se um retorno escrito por humano não move o ponteiro, um retorno escrito por LLM vai mover menos ainda. Nesse ponto o que precisa de conserto é o prompt ou as ferramentas, não acrescentar uma camada de revisão. Por outro lado, se o retorno humano funciona claramente, cheque a segunda condição — peça a um LLM que escreva o retorno contra a rubrica e compare com o seu. Se as duas passarem, o loop vale a pena ser construído.
Volte à ordenação da lição 3. O princípio para escolher um método de correção é o mais rápido, mais confiável e mais escalável2; a correção por código fica à frente da correção por LLM nos três2. Então os juízes vão onde as verificações determinísticas não alcançam, não como substitutas delas. Para o mesmo relatório, a estratificação correta fica assim:
Não mande para a camada 2 pagar o que a camada 1 já pega — uma saída que nem sequer é formato válido não precisa de uma chamada de modelo para lhe dizer que é inaceitável. A camada 3 não pode ser pulada: pessoas testando agentes encontram casos extremos que os evals deixam passar1; o viés anterior de “preferir consistentemente fazendas de conteúdo” foi pego por teste humano1.
A fronteira desta lição: como organizar conjuntos de avaliação, com quantos casos rodar este juiz — isso é a lição 5. Ligar o juiz a uma trilha de eval repetível que produz relatórios — isso é a lição 6. Esta lição só resolve como tornar um único julgamento confiável.
>> Lição 5: Conjuntos de avaliação: comece com 20 tarefas reais
How we built our multi-agent research system — Anthropic Engineering — https://www.anthropic.com/engineering/multi-agent-research-system ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11
Define success criteria and build evaluations — Claude API documentation — https://platform.claude.com/docs/en/test-and-evaluate/develop-tests ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13 ↩14 ↩15 ↩16 ↩17 ↩18
Building Effective AI Agents — Anthropic Engineering — https://www.anthropic.com/engineering/building-effective-agents ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8
Best practices for Claude Code — Claude Code official documentation — https://code.claude.com/docs/en/best-practices ↩ ↩2 ↩3 ↩4 ↩5 ↩6
Writing effective tools for agents — with agents — Anthropic Engineering — https://www.anthropic.com/engineering/writing-tools-for-agents ↩ ↩2 ↩3 ↩4
Sua tarefa: ① Liste pelo menos 4 falhas neste prompt, cada uma correspondendo a uma regra coberta nesta lição (escreva qual regra e por que isso a viola); ② Reescreva-o em uma versão funcional diretamente utilizável, não uma descrição de “como deveria ser escrito”.
Sua tarefa: ① Projete uma rubrica de três dimensões (fidelidade aos fatos, cobertura dos pontos-chave, nenhum item de ação faltando), cada dimensão de 0.0 a 1.0 mais um aprovado/reprovado geral, escrevendo com clareza o que cada dimensão pergunta e o que conta como desconto; ② Escreva o prompt de juiz completo, incluindo a ordem primeiro-raciocínio-depois-nota e restrições estritas de formato de saída; ③ Projete as etapas de “validar o próprio juiz”: prepare um conjunto pequeno de exemplos bons/ruins rotulados por humanos, rode o juiz, compare a taxa de concordância e especifique o que corrigir primeiro e o que corrigir depois quando a concordância for insuficiente. Não é preciso chamar APIs de verdade; as entregas são o prompt, o JSON e as próprias etapas.
{
"factual_accuracy": { "reasoning": "A '30% reduction' do parágrafo 2 aparece literalmente na página 4 da fonte A; a 'suspensão de pagamentos em várias regiões' do parágrafo 4 não tem respaldo em nenhuma das três fontes.", "score": 0.5 },
"citation_accuracy": { "reasoning": "4 das 5 citações batem com suas afirmações; o link da citação 3 leva a outro artigo do mesmo site.", "score": 0.8 },
"completeness": { "reasoning": "A tarefa pedia os últimos três anos, o relatório cobre apenas 2024 e 2025.", "score": 0.6 },
"verdict": "fail"
}
Camada 1 (determinística, milissegundos, custo zero) JSON / Markdown válido? Comprimento dentro da faixa exigida? Links das citações acessíveis (status HTTP)? Número de citações >= 3? Qualquer item falha → reprovado imediato, não invoque o juiz
Camada 2 (juiz LLM, segundos, cobrado por token) Pontuação pela rubrica de cinco dimensões + aprovado/reprovado Entrada: requisitos da tarefa + saída + logs brutos (chamadas e respostas de ferramenta)
Camada 3 (humano, lento e caro, apenas amostragem) O juiz disse reprovado mas você desconfia Amostra aleatória do que o juiz aprovou, para se proteger de brandura sistemáticaVocê acabou de terminar de escrever este relatório setorial. Agora avalie o seu próprio resumo:Você acha que este resumo está bom? Avalie em detalhe os pontos fortes e fracos dele,seja o mais abrangente possível, e liste todas as sugestões de melhoria em que conseguir pensar.Obrigado!