Nos capítulos anteriores, projetamos agentes que têm ferramentas, usam memória e dividem tarefas entre vários. Aqui há um muro com que muitos desenvolvedores esbarram: "construí, mas não sei se isto está realmente funcionando direito". Como o agente age de forma probabilística, com a mesma instrução ele não age exatamente igual todas as vezes. Justamente por isso, "o mecanismo de medir (avaliação)" e "o mecanismo de tornar visível (observabilidade)" viram a linha de vida para colocá-lo em produção. Neste capítulo, montamos a base para captar a qualidade em números, reproduzir falhas e girar melhorias sem parar.
A meta é "melhorar o agente com números medidos, não com achismo"
Por que a avaliação é o mais importante
Um programa comum devolve o mesmo resultado para a mesma entrada. Mas no centro do agente está o LLM, e sua saída é probabilística. Com a mesma instrução, as ferramentas escolhidas, os passos e o modo de dizer mudam ligeiramente a cada vez. Ou seja, ter funcionado bem uma vez não é garantia alguma de que funcionará na próxima.
Aqui está uma armadilha típica do desenvolvimento de agentes. Funcionou lindamente na demo, mas desmorona assim que um usuário real pede de um jeito um pouco diferente — isso não é raro. A causa é simples: "funcionou" não significa "está certo". Talvez tenha só tirado a resposta certa por acaso, e talvez erre 3 em cada 10 vezes. Para saber, só contando.
💡 O que não se mede, não se melhora. "Tenho a impressão de que melhorou" não é melhoria. Ao mudar o prompt, a taxa de sucesso subiu ou desceu? Ao adicionar uma ferramenta, não ficou desnecessariamente mais lento e mais caro? Só quando dá para comparar em números é que se decide se a mudança é avanço ou retrocesso. Avaliação não é "tarefa de casa para depois de pronto"; é o alicerce do desenvolvimento.
Outra coisa importante é não deixar a avaliação para depois. Não é preciso uma base de avaliação perfeita desde o início. Mas, se você segue "primeiro construo e, quando funcionar, penso na avaliação", em geral ela nunca é feita. Por menor que seja, comece a medir logo após montar o primeiro agente — parece rodeio, mas é o caminho mais curto. Para o panorama da avaliação, Guia prático de avaliação de agentes de IA; para o que o termo significa afinal, O que é avaliação de agentes (evals) são a porta de entrada.
O que se avalia — resultado e trajetória
Ao ouvir "avaliar", muita gente pensa só em se a resposta final está correta. Esse é, de fato, o ponto de partida, mas para agentes ele não basta. Isso porque "o que ele fez pelo caminho" importa muitíssimo. Mesmo chegando à resposta certa, se chamou ferramentas inúteis 10 vezes e desperdiçou tempo e custo, não serve na prática. E, ao contrário, há casos em que a resposta por pouco errou, mas o julgamento pelo caminho estava certo.
Por isso, dividimos o objeto da avaliação em 4 aspectos. Guardar esses 4 na cabeça dissolve a dúvida de "não sei o que medir".
Cumpriu o objetivo dado? A resposta é exata, atende aos requisitos? O indicador mais básico.
Qual ferramenta, em que ordem e por que chamou. O processo é razoável? Há rodeios ou passos desnecessários?
Chamou a ferramenta certa, com os argumentos certos? Não chamou ferramenta inexistente nem ignorou falhas?
Tokens, preço e tempo consumidos em uma execução. Está proporcional à qualidade?
📊 Medir a "trajetória" é o cerne da avaliação de agentes. Enquanto avaliar a saída comum de IA é "conferir a resposta", avaliar agentes olha "a resposta + o processo até ela". Um agente de processo sujo desmorona fácil quando as condições mudam um pouco. Já um de processo coerente se recupera mesmo se desvia. É por olhar o processo que se encontram as pistas de melhoria.
As 5 técnicas de avaliação
"Então, como medir?" — é aqui o centro da prática. Há vários tipos de técnica de avaliação, e cada um tem seus pontos fortes e fracos. O procedimento padrão é não confiar em um só, mas combinar conforme o que se quer medir. Vejamos as 5 representativas, com vantagens e desvantagens.
Confronta a saída do agente com um "gabarito" preparado de antemão e mede a coincidência. Serve para tarefas de resposta única, como classificação, extração e cálculo.
Vantagem: nítido, fácil de automatizar e não oscila.
Desvantagem: difícil de usar em texto livre, em que "o gabarito não é único".
Julga mecanicamente por condições fixas: "contém as palavras obrigatórias?", "é um JSON de formato válido?", "não há termos proibidos?".
Vantagem: rápida e barata, forte em checar formato e condições de segurança.
Desvantagem: não mede qualidade nebulosa, como "faz sentido semanticamente?".
Entrega a critérios de nota a outro LLM e o faz avaliar se a saída é boa ou ruim. Mede tarefas sem gabarito único, como a qualidade de um resumo ou a cordialidade de uma resposta.
Vantagem: avalia texto livre e qualidade subjetiva, em massa e de forma automática.
Desvantagem: o próprio avaliador oscila/enviesa. Exige critérios explícitos e conferência amostral por humanos.
Reúne tarefas representativas em um conjunto de teste e o roda inteiro a cada mudança. Um mecanismo para proteger "o que passava até ontem não quebrou com a correção de hoje".
Vantagem: detecta cedo a degradação (regressão) causada por mudanças.
Desvantagem: preparar e manter o conjunto de teste dá trabalho.
Após o lançamento, observa continuamente as execuções de usuários reais. Reúne a evolução de taxa de sucesso, custo e latência e a avaliação do usuário (👍/👎) para acompanhar o desempenho real.
Vantagem: descobre problemas que só surgem no ambiente real e usos inesperados.
Desvantagem: é a posteriori. O problema só se conhece "depois que acontece". Pressupõe uso conjunto com a avaliação prévia.
⚠️ Combinar é o básico. Formato e condições de segurança, na baseada em regras; o que tem resposta única, no cotejo com gabarito; o texto livre, no LLM-as-judge; a cada mudança, no teste de regressão; e, após o lançamento, no monitoramento em produção. Não tente cobrir tudo com uma só técnica. Peneirar a maior parte com técnicas baratas e rápidas (①②) e usar a técnica cara (③) só onde é preciso mantém a precisão com custo contido. Para mais detalhes, veja O que é avaliação de LLM.
Como montar os dados de avaliação (conjunto de teste)
Para qualquer técnica, o alicerce são os "insumos do que medir" = os dados de avaliação (conjunto de teste). Em essência, é reunir tarefas representativas de "diante desta entrada, quero este resultado". Se isto for pobre, nenhuma técnica de avaliação, por mais elegante, é confiável. E, ao contrário, com um bom conjunto de teste, 80% da avaliação já está resolvida.
A forma de montar é simples e segue esta ordem. Em vez de mirar a perfeição, a regra de ouro é começar pequeno e fazer crescer.
Reúna pedidos que o agente provavelmente receberá de verdade, incluindo exemplos típicos, de fronteira e propensos a falha.
Escreva o "quero que fique assim" de cada tarefa. Pode ser o gabarito, as condições a cumprir ou os critérios de nota.
No começo, 10 a 20 itens bastam. Mais do que a quantidade, priorize a "qualidade" que reflete a realidade do dia a dia.
Vá adicionando ao conjunto de teste os casos de falha encontrados em produção. Um ativo que fica mais esperto conforme se usa.
✅ Não subestime "apenas 10 itens". Você pode sentir que "amostras de menos, não tem sentido". Mas 10 itens escolhidos com cuidado são muito mais úteis do que 1000 reunidos ao acaso. Torne mensuráveis, primeiro, 10 casos representativos que realmente incomodam. Só com isso, você já passa a decidir na hora se a mudança no prompt ou nas ferramentas vai para o lado bom ou ruim. O conjunto de teste não se faz de uma vez; é um ativo vivo, ao qual você acrescenta um item a cada falha encontrada.
Observabilidade — tornar o comportamento visível
Se avaliar é "medir o que é bom ou ruim", a observabilidade é "conseguir acompanhar por que ficou assim". Mesmo sabendo pela avaliação que "a taxa de sucesso caiu", se você não consegue ver o que aconteceu ali dentro, não tem como consertar. Como o agente gira vários passos internamente, de fora ele tende a virar uma caixa-preta: "botei a entrada, algo aconteceu, saiu o resultado". Abrir essa caixa e deixar o interior visível é a observabilidade.
São basicamente 3 os elementos que sustentam a observabilidade.
O registro contínuo de uma execução, do início ao fim. Dá para acompanhar de ponta a ponta, em ordem cronológica, o fluxo "entrada → raciocínio → chamada de ferramenta → resultado → próxima decisão".
Em cada passo, que prompt foi enviado, com que argumentos a ferramenta foi chamada e o que retornou. Consumo de tokens e tempo também ficam aqui.
Conseguir refazer, com a mesma entrada e o mesmo estado, a execução em que o problema surgiu. Só reproduzindo é que se identifica a causa e se valida a correção.
Dá para ir anexando isso a mão nos logs, mas, na prática, o comum é usar ferramentas de tracing. Elas capturam automaticamente cada passo do agente e o visualizam de forma legível, como uma árvore cronológica. "Em que passo demorou", "onde a chamada de ferramenta falhou", "em que decisão desviou para o rumo errado" passam a ficar visíveis num relance.
📊 O trace é o "olho do debug". No exemplo acima, no ④ a chamada de ferramenta falha e, no ⑤, o próprio agente se recupera. Olhando só o resultado, é "sucesso"; mas, pelo trace, aparece a fraqueza de "tende a errar o número da coluna". Essa percepção leva à próxima melhoria. A ideia de observabilidade é explicada de forma sistemática em O que é observabilidade de IA.
Girar o laço de melhoria
O ferramental até aqui — avaliação e conjunto de teste, e a observabilidade — já é útil isolado, mas o real valor aparece quando gira como um único laço. Desenvolver agentes não é "montou, acabou"; é o ofício de melhorar aos poucos no ciclo medir, achar a fraqueza, corrigir e medir de novo.
Rode a avaliação sobre o conjunto de teste e produza, em números, taxa de sucesso, custo e latência.
Leia o trace das execuções que falharam e descubra onde e por que ele errou.
Mude uma parte que corresponda à causa: prompt, descrição de ferramenta, procedimento, divisão de papéis.
Reavalie com o mesmo conjunto de teste e confirme se a melhoria almejada saiu e se nada mais piorou.
Há um truque importante nesse laço: mudar, de cada vez, o máximo possível uma coisa só. Se você muda prompt, ferramentas e procedimento ao mesmo tempo, mesmo que a taxa de sucesso suba, fica impossível saber "qual mudança surtiu efeito". É por mudar um de cada vez e medir que a causa e o resultado se ligam e o conhecimento se acumula. É discreto, mas é o divisor entre a "melhoria por achismo" e a "melhoria segura".
✅ Gire o laço rápido e pequeno. Em vez de acertar uma grande reforma de uma vez, girar mudanças pequenas rápido e muitas vezes melhora mais rápido no fim. Com 10 itens no conjunto de teste, você mede logo após mudar. Quando essa cadência "mudar → medir na hora" entra no corpo, o desenvolvimento de agentes deixa de ser jogo de adivinhação e vira um trabalho de engenharia que avança com firmeza.
- O agente é probabilístico e "funcionou" não significa "está certo". Sem medir, não se melhora.
- O objeto da avaliação tem 4 aspectos — resultado final, trajetória, chamadas de ferramenta e custo/latência. A "trajetória", em especial, é o cerne.
- São 5 as técnicas — cotejo com gabarito, baseada em regras, LLM-as-judge, teste de regressão e monitoramento em produção —, combinadas conforme o alvo.
- Os dados de avaliação, com poucas tarefas representativas. 10 itens caprichados vencem 1000 ao acaso. Cresça acrescentando as falhas.
- A observabilidade é trace de execução, log de cada passo e reprodução da falha. Torne o comportamento visível com ferramentas de tracing.
- A melhoria é o laço medir → achar a fraqueza → corrigir → medir de novo. Mude um de cada vez, pequeno e rápido.
Medida a qualidade e tornado o comportamento visível, o próximo é "como evitar descontrole, erro e uso indevido". Aprendamos o desenho para tratar com segurança a autonomia que aumentamos no Capítulo 4 "Desenho multiagente". Avançamos para o próximo Capítulo 6 "Guardrails e segurança".