Lição 2: O que verificar: estado final primeiro, processo como rede de segurança

Objetivos de aprendizado:

• Entender por que “gravar as etapas corretas e depois conferi-las uma a uma” está fadado a julgar agentes de forma errada, e trocar isso pela avaliação de estado final
• Para fluxos complexos, identificar alguns checkpoints de verificação discretos que confirmam que “as mudanças de estado esperadas aconteceram”, em vez de validar cada etapa
• Transformar um requisito vago em critérios de sucesso mensuráveis, alcançáveis e multidimensionais, e saber até onde levar as asserções de trajetória

Pré-requisitos: concluir a Lição 1, saber que sem uma verificação que rode você vira o loop de verificação | Anterior: Lição 1 << | Próxima: Lição 3 >>

Três execuções, três veredictos de “reprovado”

Você decide adicionar verificação ao seu agente. O primeiro impulso é quase universal: gravar a “abordagem padrão”. Rodar a tarefa na mão uma vez, anotar cada etapa — a etapa 1 deveria chamar search, a etapa 2 deveria chamar fetch_page, a etapa 3 deveria chamar write_note — e salvar isso como gabarito. Dali em diante, toda vez que o agente rodar, comparar a sequência de chamadas dele com essa resposta, etapa por etapa. Uma divergência e é reprovado.

Você roda três vezes. Três reprovações.

Você olha as saídas: três resumos, fatos corretos, fontes confiáveis, todos os ângulos pedidos cobertos. A única diferença foi o caminho — a primeira execução buscou em três fontes e isso bastou, a segunda buscou em dez, a terceira consultou definições de terminologia antes de buscar. É exatamente isso que a Anthropic observou no próprio sistema multiagente de pesquisa: mesmo com pontos de partida idênticos, agentes podem tomar caminhos completamente diferentes, mas válidos, para chegar ao objetivo, um buscando em três fontes enquanto outro busca em dez, ou usando ferramentas diferentes para achar a mesma resposta¹.

O que falhou não foi o agente. Foi o seu método de verificação.

Você não sabe de verdade quais são as “etapas corretas”

A avaliação tradicional carrega uma premissa padrão enterrada bem fundo: dada a entrada X, o sistema deveria seguir o caminho Y e produzir a saída Z — as mesmas etapas toda vez¹. Essa premissa vale de forma tão natural para sistemas determinísticos que a maioria das pessoas nunca percebe que ela é uma premissa. Agentes a derrubam de imediato.

O que é de fato desconfortável não é só “o caminho vai variar” — é esta frase:

"Because we don’t always know what the right steps are, we usually can't just check if agents followed the “correct” steps we prescribed in advance. Instead, we need flexible evaluation methods that judge whether agents achieved the right outcomes while also following a reasonable process."¹

(Como nem sempre sabemos quais são as etapas certas, em geral não dá para simplesmente checar se os agentes seguiram as etapas “corretas” que prescrevemos de antemão. Em vez disso, precisamos de métodos de avaliação flexíveis que julguem se os agentes alcançaram os resultados certos e, ao mesmo tempo, seguiram um processo razoável.)

“Nem sempre sabemos quais são as etapas certas” — essa é a chave. O caminho que você gravou não é o único caminho correto. Ele é apenas o caminho que você por acaso tomou naquela vez. Você o elevou a gabarito, então toda outra abordagem virou erro.

Repare na segunda metade: “e, ao mesmo tempo, seguiram um processo razoável”. Isso não significa ignorar o processo por completo. Significa não usar um caminho fixo como régua.

Avaliação de estado final: julgue resultados, não o fluxo

A abordagem da Anthropic é direta: foque na avaliação de estado final, e não na análise turno a turno — não julgue se o agente seguiu um processo específico, julgue se ele alcançou o estado final correto¹. Essa abordagem reconhece que agentes podem achar caminhos alternativos para o mesmo objetivo, garantindo ainda assim que entreguem o resultado pretendido¹.

Primeiro, uma definição em linguagem simples de “estado final”: depois que a tarefa termina, o estado que você consegue observar no ambiente e verificar depois do fato. Quais arquivos apareceram no sistema de arquivos, que valores os campos daquele registro do banco têm agora, qual etiqueta o chamado carrega, se o JSON retornado tem status: "resolved".

Um teste decisivo útil: estado final é um substantivo, não um verbo. “Chamou rename_file” é verbo; “todos os nomes de arquivo batem com determinado formato” é substantivo. A verificação só aceita substantivos.

Tarefa: renomear os PDFs de faturas em downloads/ para "data_fornecedor.pdf"
Verificação por etapas (frágil)        Verificação de estado final (estável)1. Chamar list_files                   downloads/ não tem mais nenhum nome original2. Chamar read_pdf para cada um        Cada nome bate com ^\d{8}_[a-z0-9-]+\.pdf$3. Chamar extract_date                 A contagem de arquivos bate com a de antes, nada perdido nem criado4. Chamar rename_file para cada um     As datas dos nomes batem com as datas das faturas no conteúdo do PDF

A coluna da esquerda falha no instante em que o agente usa uma leitura em lote em vez de quatro leituras individuais, mesmo que os resultados sejam idênticos. A coluna da direita não se importa com como ele lê — porque ela descreve “como downloads/ está agora”, sem relação com o caminho que levou até lá.

Há um ponto fácil de perder ao escrever asserções de estado final: escreva também o que não deveria mudar. Aquela linha de “a contagem de arquivos bate com a de antes” é um exemplo. Se o agente renomear dois arquivos para o mesmo nome e o segundo sobrescrever o primeiro, a verificação de “todos os nomes são válidos” passa numa boa. Asserções de estado final precisam proteger dos dois lados: “as mudanças esperadas aconteceram” e “as inesperadas não aconteceram”.

Fluxos complexos: divida a avaliação em checkpoints

Avaliação de estado final não é “ignorar o processo por completo”. A frase seguinte na fonte dá uma saída: para fluxos complexos, quebre a avaliação em checkpoints discretos onde mudanças de estado específicas deveriam ter ocorrido, em vez de tentar validar cada etapa intermediária¹.

Repare na formulação — “mudanças de estado específicas deveriam ter ocorrido”, continua sendo estado, continuam sendo substantivos. Só se moveu o ponto de observação da “linha de chegada” para “alguns pontos ao longo do caminho”.

Aviso de colisão de termos: o “checkpoint” do Curso 9 desta série significa salvar contexto — gravar em disco o estado de execução do agente para que ele possa retomar dali depois de uma queda, com finalidade de recuperação. O “checkpoint” desta lição significa verificar estado — confirmar que as mudanças de estado esperadas aconteceram em um ponto do fluxo, com finalidade de validação. As posições muitas vezes se sobrepõem (é natural verificar no mesmo lugar em que você grava o checkpoint), mas eles resolvem problemas diferentes. Misturá-los na discussão gera confusão, então daqui em diante vamos chamar estes de “checkpoints de verificação” e os do Curso 9 de “checkpoints de recuperação”.

Para saber quando vale a pena adicionar um checkpoint de verificação, olhe três coisas:

• Fluxo longo, estado final distante demais do início. Quando falha, você só sabe que “não chegou ao fim”, não onde o desvio começou.
• Operações irreversíveis. E-mails enviados, estoque baixado, arquivos sobrescritos — quando o estado final revela o erro, já é tarde.
• A saída intermediária é a base das etapas seguintes. O script de migração cria a tabela e depois carrega os dados; estrutura de tabela errada significa que todo dado carregado é lixo, e o custo de refazer se multiplica.

Se nenhuma dessas se aplica, não adicione.

Onde colocá-los: nas posições em que o estado sofre mudança substantiva, não depois de cada chamada de ferramenta.

Tarefa: migrar a tabela de usuários do schema antigo para o schema novo
Checkpoint de verificação 1 (depois da criação da tabela): a tabela new_users existe, as colunas batem exatamente com o schema alvoCheckpoint de verificação 2 (depois da carga de dados): contagem de linhas de new_users == contagem de linhas de old_users, sem chaves primárias duplicadasEstado final: a aplicação lê a tabela nova e passa no smoke test (a verificação mais básica de “roda?”), old_users renomeada para old_users_backup
O que não verificamos: se ele escreveu CREATE TABLE ou copiou de um template,se carregou tudo de uma vez ou em lotes, quantos lotes, quantas linhas por lote.

Dois checkpoints, um estado final. Três asserções governam a migração inteira. Se você fosse de “validar cada etapa intermediária”, esse fluxo poderia gerar dezenas de asserções, a maioria penalizando diferenças legítimas de implementação.

Pare aqui: o que há de errado nesta proposta

Como definir critérios de sucesso: mensuráveis, alcançáveis, multidimensionais

Aquelas três palavras, “estado final correto”, precisam pousar em números concretos ou julgamentos claros; caso contrário você só deu a volta e voltou para o “parece certo”. A documentação oficial dá dois requisitos duros para critérios de sucesso:

• Mensurável: use métricas quantitativas ou escalas qualitativas bem definidas (uma escala é um checklist de rubrica de pontuação; como escrever uma é conteúdo da Lição 4). Números trazem clareza e escalabilidade, mas medidas qualitativas podem ser valiosas se aplicadas de forma consistente junto com as quantitativas².
• Alcançável: baseie suas metas em benchmarks do setor, experimentos anteriores, pesquisa de IA ou conhecimento de especialistas. Suas métricas de sucesso não deveriam ser irrealistas para as capacidades atuais dos modelos de fronteira².

E mais uma: a maioria dos casos de uso precisa de avaliação multidimensional ao longo de vários critérios de sucesso².

O exemplo completo da documentação oficial é uma frase só (as anotações entre parênteses são do original):

"The sentiment analysis model should achieve an F1 score of at least 0.85 (Measurable, Specific) on a held-out test set* of 10,000 diverse Twitter posts (Relevant), which is a 5% improvement over the current baseline (Achievable)."²

(O modelo de análise de sentimento deveria alcançar uma pontuação F1 de pelo menos 0,85 (mensurável, específico) em um conjunto de teste de holdout* de 10.000 posts variados do Twitter (relevante), o que representa uma melhora de 5% sobre o baseline atual (alcançável).)

Vale desmontar essa frase, porque cada componente bloqueia um modo de falha específico:

Essa última linha é o método concreto para “alcançável”: o limiar não é deduzido de trás para frente a partir do desejo; ele é um passo pequeno adiante do estado atual. Se você não tem baseline, rode uma versão da implementação mais ingênua possível e use a pontuação dela como baseline. Quando você nem consegue rodar um baseline, não tenha pressa de fixar números.

Há uma pergunta ainda mais anterior. Quando a Anthropic descreve cenários adequados a agentes, ela diz: agentes agregam mais valor em tarefas que exigem tanto conversa quanto ação, têm critérios de sucesso claros, permitem loops de feedback e integram supervisão humana significativa³. Leia ao contrário — se você não consegue escrever critérios de sucesso para esta tarefa de jeito nenhum, o problema não é a etapa de verificação; esta tarefa não deveria ter sido entregue inteira ao agente para rodar sozinho. Se você não consegue escrever critérios, vai ter que acompanhar tudo — como a Lição 1 disse, nesse ponto você vira o loop de verificação.

Asserções de trajetória: pode adicionar, mas não engesse

A avaliação de estado final pega “o resultado está correto”, mas ela deixa passar uma classe de problema: o agente de fato reconhece aquela ferramenta nova que você deu a ele?

A documentação oficial dá um acréscimo opcional: para cada par prompt-resposta, você pode opcionalmente especificar também as ferramentas que espera que um agente chame para resolver a tarefa, para medir se os agentes conseguem ou não captar o propósito de cada ferramenta durante a avaliação⁴. Isso é asserção de trajetória — não julga ordem, não julga contagem, julga apenas se certas ferramentas apareceram na trajetória.

Quando ela é útil: você acabou de adicionar uma ferramenta search_internal_docs e quer que o agente a use para perguntas sobre processos internos. Mas ele sai buscando na web pública, acha uma resposta suficientemente parecida, e a validação de estado final continua passando. Só a trajetória enxerga essa diferença.

O limite está escrito na frase logo seguinte: como pode haver múltiplos caminhos válidos para resolver tarefas corretamente, tente evitar especificar demais ou se sobreajustar a estratégias⁴.

Fronteiras concretas:

• Afirme apenas “o conjunto contém”, não ordem, não contagem
• Liste apenas uma ou duas ferramentas com que você de fato se importa; não copie a sequência inteira para dentro — isso é gravar-e-reproduzir de novo
• Asserção de trajetória falha mas o estado final passa: registre uma observação, não reprove a avaliação inteira
• É um acréscimo opcional, não o padrão. O padrão continua sendo o estado final¹

Além da taxa de aprovação: o que mais registrar

Depois de uma rodada de eval, se você só recebe uma taxa de aprovação, vai se ver sem nada a dizer — o que significa 78%? Você deveria ajustar o prompt a seguir, ou as ferramentas?

A documentação oficial recomenda coletar estas métricas além da acurácia de topo: o tempo total de execução de chamadas de ferramenta individuais e de tarefas, o número total de chamadas de ferramenta, o consumo total de tokens e os erros de ferramenta⁴. Essas métricas não participam do julgamento; elas participam do diagnóstico.

A documentação oficial dá duas leituras:

• Muitas chamadas de ferramenta redundantes podem sugerir que vale redimensionar os parâmetros de paginação ou de limite de tokens⁴
• Muitos erros de ferramenta por parâmetros inválidos podem sugerir que as ferramentas se beneficiariam de descrições mais claras ou exemplos melhores⁴

O que essas duas têm em comum: elas apontam o dedo para o desenho da ferramenta, não para o modelo. Muitas chamadas redundantes normalmente significam que a ferramenta só consegue trazer 20 itens por vez, então o agente tem que paginar por dez páginas; muitos erros de parâmetro normalmente significam que a descrição da ferramenta não explicou em que formato aquele campo precisa vir. Esses problemas têm raiz no lado da ferramenta — só acrescentar “chame menos vezes” ou “escreva os parâmetros com cuidado” ao prompt de sistema normalmente não funciona; você tem que ajustar o desenho dos parâmetros e a descrição da ferramenta.

Puxando esse fio, aparecem mais algumas (as de baixo não são endossadas oficialmente, são julgamentos de engenharia extrapolados das duas acima — verifique nos seus próprios dados): taxa de aprovação inalterada mas consumo de tokens dobrado significa que essa mudança não é de graça; uma categoria de tarefas com variância de duração especialmente grande provavelmente esconde retentativas ou giro em falso; erros concentrados em uma ferramenta, olhe primeiro para aquela ferramenta, não desconfie do prompt.

Uma rodada de eval deveria despejar pelo menos estas colunas; a Lição 6, ao construir o harness de eval, vai usá-las direto (para economizar largura de coluna, os tokens de entrada e saída serão fundidos em um só):

case_id | passed | duration_ms | tool_calls | tokens_in | tokens_out | tool_errors

Limites: três coisas que não se deve fazer

Um: não tente validar cada etapa intermediária¹. Este é o limite mais fácil de romper nesta lição, porque a intuição de que “verificar mais é mais seguro” é muito forte. O resultado real é o oposto: quanto mais finas as asserções, mais diferenças legítimas são penalizadas, mais ruidoso fica o eval, até você começar a ignorar o vermelho — e nesse ponto ele é completamente inútil.

Dois: não faça das asserções de trajetória o padrão. Adicionar uma asserção de trajetória é tão barato que você escreve mais uma entrada de expectedTools sem esforço nenhum. Na décima entrada você já está prescrevendo estratégia de forma substantiva, só formalmente ainda chamando aquilo de “asserção”. Toda vez que você adicionar uma, pergunte a si mesmo: a saída vai realmente quebrar se esta ferramenta não for chamada? Se a resposta for “não necessariamente”, não adicione.

Três: não defina limiares depois da execução. Olhar uma pontuação de 0,82 e dizer “0,8 deve bastar”, e olhar 0,86 e dizer “tem que ser 0,85”, são o mesmo autoengano. Defina limiares antes da execução, e anote a justificativa.

💻 Exercícios

Recapitulação

• A avaliação tradicional assume “dada a entrada X siga o caminho Y obtenha a saída Z”; agentes não satisfazem essa premissa: pontos de partida idênticos ainda podem tomar caminhos completamente diferentes, mas válidos, um buscando em três fontes e outro em dez¹
• Você nem sempre sabe quais são as etapas certas, então em geral não dá para checar se os agentes seguiram as etapas que você prescreveu; use métodos de avaliação flexíveis que julguem se eles alcançaram os resultados certos e, ao mesmo tempo, seguiram um processo razoável¹
• A abordagem padrão é avaliação de estado final, não análise turno a turno: não julgue se ele seguiu um processo específico, julgue se ele alcançou o estado final correto¹. Estado final é substantivo e não verbo, e precisa proteger tanto “as mudanças esperadas aconteceram” quanto “as inesperadas não aconteceram”
• Para fluxos complexos, quebre a avaliação em checkpoints discretos que confirmem que “mudanças de estado específicas deveriam ter ocorrido”, não tente validar cada etapa intermediária¹. O “checkpoint” daqui significa verificar estado, diferente do checkpoint de salvar contexto do Curso 9
• Critérios de sucesso precisam ser mensuráveis (métricas quantitativas ou escalas qualitativas bem definidas), alcançáveis (basear as metas em benchmarks do setor, experimentos anteriores ou conhecimento de especialistas), e a maioria dos casos de uso precisa de avaliação multidimensional²
• A documentação oficial lista “ter critérios de sucesso claros, permitir loops de feedback” como condições em que agentes agregam mais valor³; leia ao contrário — tarefas para as quais você não consegue escrever critérios de sucesso não deveriam ser entregues inteiras a agentes para rodar sozinhos; você vai ter que acompanhar o tempo todo
• Asserções de trajetória são um acréscimo opcional: você pode especificar quais ferramentas espera que ele chame, para medir se ele capta o propósito das ferramentas, mas como os caminhos válidos não são únicos, evite especificar demais ou se sobreajustar a estratégias⁴
• Além da taxa de aprovação, registre também tempo de execução, contagem de chamadas, consumo de tokens e erros de ferramenta; muitas chamadas redundantes, considere ajustar os parâmetros de paginação e de limite de tokens; muitos erros de parâmetro inválido, considere deixar as descrições e os exemplos das ferramentas mais claros⁴

>> Lição 3: Verificadores determinísticos: só valem verificações que produzem passa/falha