Capítulo 5.4 — Eval harness

🎯 Objetivo

Tornar avaliação contínua parte do CI/CD. Sem eval automatizado, qualquer mudança em prompt, modelo, tool ou retriever entra em produção no escuro.

🧠 Componentes

• Datasets: golden, sintético, adversarial, regression, traces redigidos (ver Cap. 2.11).
• Checks: deterministic (schema, regex, contratos), policy (Rego/Cedar tests), LLM-as-judge (com rubrica e calibração), human sampling (para casos críticos).
• Release gates: critérios objetivos de aprovação para promover versão. Falha em policy ou em regressão crítica = bloqueio automático.

🧠 Eval de agentes multi-step

Avaliar agente é mais difícil do que avaliar LLM:

• Trajetória importa, não só resposta final. Um agente que acerta a resposta passando por uma tool errada é um sucesso frágil.
• Tool call accuracy por etapa: o agente escolheu a tool correta? Os argumentos passaram no schema?
• Custo por sucesso, não só taxa de sucesso. Um agente que resolve mas consome 10x mais tokens não está melhor.
• Replay de cenários com forks: e se a tool A tivesse falhado? O agente faz fallback correto?

📝 Exemplo de eval suite

eval_suite:
  name: support_agent_regression
  version: 4
  agent: support-agent@2.1.0
  datasets:
    - name: golden_support_cases_v3
      type: golden
    - name: prompt_injection_cases_v2
      type: adversarial
  checks:
    - id: schema_validity
      type: deterministic
      assertion: output.matches_schema("support_answer_v2")
    - id: groundedness
      type: llm_judge
      rubric: "Todas as afirmações factuais devem estar suportadas pelos trechos recuperados."
      threshold: 0.92
    - id: tool_call_accuracy
      type: deterministic_or_human_sample
      threshold: 0.95
    - id: pii_leakage
      type: policy
      assertion: no_unmasked_pii(output)
    - id: cost
      type: metric
      assertion: cost_per_task <= 0.20
    - id: latency
      type: metric
      assertion: p95_latency_ms <= 10000
  release_gate:
    fail_on_policy_violation: true
    minimum_pass_rate: 0.90
    require_human_review_for_failures: true

🧰 Exemplos práticos relacionados (planejados)

• EX-EVAL-01 - eval harness com pytest + golden dataset.
• EX-EVAL-02 - regression test de prompts.
• EX-EVAL-03 - eval de retrieval com Ragas.

---