Phase 14 - Lesson 30

Desenvolvimento de Agentes Orientado a Avaliação

Orientação da Anthropic: "comece com prompts simples, otimize-os com avaliação abrangente e adicione sistemas agênticos de múltiplas etapas apenas quando necessário." A avaliação não é a última etapa. É o loop externo que direciona todas as outras escolhas na Fase 14.

Tipo: Aprender + Construir Linguagens: Python (stdlib) Pré-requisitos: Toda a Fase 14. Tempo: ~60 minutos

Objetivos de Aprendizado

• Nomear as três camadas de avaliação — benchmarks estáticos, offline customizada, produção online — e para que serve cada uma.
• Explicar o loop estreito de avaliador-otimizador.
• Descrever a melhor prática de 2026: as avaliações (evals) vivem junto ao código, rodam no CI e servem como barreira em PRs.
• Conectar cada lição da Fase 14 ao caso de avaliação que ela gera.

O Problema

Agentes passam em demonstrações. Eles falham em produção de maneiras que as demonstrações não conseguem prever. Os benchmarks respondem a "este modelo é amplamente capaz?" e não a "este agente está entregando as correções corretas para o meu produto?" A resposta: avaliação em três camadas, rodando continuamente, com cada guardrail e regra aprendida mapeados para um caso de avaliação.

O Conceito

Três camadas de avaliação

1. Benchmarks estáticos — SWE-bench Verified para código (Lição 19), WebArena/OSWorld para navegação / desktop (Lição 20), GAIA para generalista (Lição 19), BFCL V4 para uso de ferramentas (Lição 06). Use para comparação entre modelos e barreira contra regressões (regression gating). A contaminação é real: o SWE-bench+ encontrou 32,67% de vazamento de soluções. Sempre reporte pontuações Verified / auditadas por +.

2. Avaliações offline customizadas — o formato do seu produto:

   • LLM-as-judge (Langfuse, Phoenix, Opik — Lição 24).
   • Baseadas em execução (rodar a correção, verificar os testes).
   • Baseadas em trajetória (comparar sequências de ações contra o gabarito [gold]; OSWorld-Human mostra que os melhores agentes fazem 1,4-2,7x mais etapas do que o gabarito).

3. Avaliações online — produção:

   • Replay de sessões (Langfuse).
   • Alertas acionados por guardrails (Lição 16, 21).
   • Rastreamento de custo / latência por etapa (spans OTel da Lição 23).

Avaliador-otimizador (Anthropic)

O loop estreito:

1. O proponente (Proposer) gera a saída.
2. O avaliador (Evaluator) julga.
3. Refina até que o avaliador aprove.

Este é o Self-Refine (Lição 05) generalizado. Qualquer fluxo de agente com o qual você se importe pode ser envolvido em um avaliador-otimizador para maior confiabilidade.

Melhor prática de 2026

• As avaliações vivem junto ao código.
• Rodam no CI a cada PR.
• Bloqueiam o merge com base nas pontuações de avaliação (ex: "nenhuma regressão > 5% em relação à main").
• Cada guardrail é mapeado para um caso de avaliação.
• Cada regra aprendida (Reflexion, regra de aprendizado do fluxo de trabalho pro) é mapeada para um caso de falha.

Juntando tudo na Fase 14

Cada lição na Fase 14 gera casos de avaliação:

Se o seu conjunto de avaliações tiver casos para cada um, você cobriu a Fase 14.

Onde o desenvolvimento orientado a avaliações falha

• Sem linha de base (baseline). Avaliações sem uma última versão boa conhecida são ilegíveis. Armazene as linhas de base.
• LLM-judge sem ancoragem (grounding). Juízes também alucinam. Padrão CRITIC (Lição 05) — o juiz se ancora em ferramentas externas.
• Overfitting a avaliações. Otimizar para a avaliação desvia da utilidade em produção. Rotacione os casos.
• Avaliações instáveis (flaky evals). Casos não determinísticos causam falsos alarmes. Fixe sementes (seeds), tire snapshots do estado.

Construa

code/main.py é um executor de testes de avaliação (eval harness) da biblioteca padrão:

• Registro de casos com categorias (benchmark, customizado, online).
• Um agente roteirizado sob teste.
• Loop avaliador-otimizador: propor, julgar, refinar até passar ou atingir o limite de rodadas.
• Barreira de CI: taxa de aprovação agregada + regressão em relação à linha de base.

Execute-o:

python3 code/main.py

Saída: passa/falha por caso, flag de regressão, veredito da barreira de CI.

Use

• Escreva os casos de avaliação no mesmo repositório do código do seu agente.
• Execute-os em cada PR via CI.
• Falhe o build em caso de regressão.
• Acompanhe a taxa de aprovação ao longo do tempo.
• Vincule cada falha de produção a um novo caso.

Ship It

outputs/skill-eval-suite.md constrói uma suíte de avaliação de três camadas para um produto de agente com barreiras de CI e rastreamento de regressão.

Exercícios

1. Pegue uma de suas falhas de produção. Escreva um caso de avaliação que a reproduza. Seu agente passa por ela agora?
2. Crie uma rubrica de LLM-judge para seu domínio com três dimensões (factual, tom, escopo). Avalie 50 sessões.
3. Integre a suíte de avaliação ao CI. Falhe o build em caso de regressão >=5%.
4. Adicione uma métrica de eficiência de trajetória: quantas etapas o agente realizou versus uma trajetória gabarito (gold)?
5. Mapeie cada lição da Fase 14 para um caso de avaliação em sua suíte. Há algum faltando? Essa é uma lacuna a ser preenchida.

Termos-Chave

Leitura Adicional

• Anthropic, Building Effective Agents — "comece simples, otimize com avaliações"
• OpenAI, SWE-bench Verified — o benchmark selecionado
• Berkeley Function Calling Leaderboard — benchmark de uso de ferramentas
• Langfuse docs — avaliações + replay de sessão na prática