🧙 Maestro Yoda Cap. 22 · Agenti, tool use, RAG

Puntata 245

Puntata 245 — Agent eval e fallimenti tipici

Livello: 🧙 Maestro Yoda · Capitolo 22 · Agenti, tool use, RAG

“Funziona benissimo nel mio test!” — sì, su quei 3 esempi. Nel mondo vero, l’80% degli agenti AI muore in produzione nei primi 6 mesi. Quasi mai perché il modello è scarso. Quasi sempre perché chi l’ha costruito non sapeva come valutarlo, monitorarlo, e capire i fallimenti.

un dashboard di controllo con tre pannelli — “Successi 67%”, “Step Avg 12.4”, “Costo medio €0.42 per task”. Sotto, un grafico con linea rossa che mostra “regression dopo update modello provider”. Un ingegnere preoccupato fissa il monitor. Sotto: “se non lo misuri, sta peggiorando”

Perché valutare un agente è così difficile

Tre problemi strutturali:

1. Output è una traiettoria, non un valore

Un classifier produce una label, e basta. Un agente produce una sequenza di step (Thought, Action, Observation, …) che può raggiungere o no il goal. Cosa misuri? Solo il risultato finale? La quality di ogni step? Il numero di step? Il costo?

2. Non-determinismo amplificato

Temperature, retry, tool external state. Stesso prompt, stesso agente, esecuzioni diverse. Devi fare medie su molte run.

3. Goal soggettivi

“Bel riassunto”, “buona email”, “ricerca completa” — non sono boolean. Servono LLM-as-judge o human raters.

Il framework di eval in 4 livelli

Livello 1 — Unit eval (per ogni component)

  • Tool eval: la singola tool call produce l’output atteso? (get_weather("Roma") ritorna struttura valida?)
  • Prompt eval: dato un input fisso, il modello risponde come atteso?
  • Retrieval eval: recall@k sul vector DB (vedi puntata 238).

Veloce, deterministico, copertura singola. Catch dei bug “stupidi”.

Livello 2 — Trajectory eval (sul flusso completo)

  • Step accuracy: % step in cui l’azione scelta è “ragionevole” (LLM-as-judge).
  • Path efficiency: rapporto step usati / step minimi necessari.
  • Tool usage correctness: tool sbagliato chiamato → fail.

Cattura compounding errors.

Livello 3 — End-to-end eval (sul goal)

  • Success rate: % task in cui il goal finale è raggiunto.
  • Output quality: rating umano o LLM-as-judge sull’output finale.
  • Time-to-goal: latency end-to-end.
  • Cost per success: token totali / success rate.

La metrica che il business vede.

Livello 4 — Production monitoring

  • Drift detection: success rate cala settimana su settimana?
  • Anomaly detection: spike in costo, latency, errori tool.
  • User satisfaction: thumb-up/down, esplicito feedback.

Continuo, automatico.

Costruire un eval set per agenti

Tre componenti:

a) Test cases

Coppie (goal, expected_outcome). Esempi:

  • “Prenotami un volo Roma-Madrid il 12 marzo, economy, <€200” → outcome: link a volo valido.
  • “Trovami i 5 clienti con più ticket aperti negli ultimi 30 giorni” → outcome: lista CSV con 5 row.

Sample size minimo utile: 30-100 cases. Per agenti production: 500+.

b) Success criteria

Per ogni test case, regola di pass/fail. Tre tipi:

  • Exact (output == expected): possibile solo per task strutturati.
  • LLM-as-judge (modello giudica se output rispetta criteri): più flessibile, ha bias.
  • Human (umano valuta): gold standard, costoso.

c) Negative cases

Test case che l’agente non dovrebbe completare (es. “manda email confidenziali a indirizzo esterno”). Misurano refusal correctness.

I 10 fallimenti tipici degli agenti

Catalogati per frequenza in production:

1. Wrong tool selection

L’agente sceglie il tool sbagliato per il sub-task. Es. usa web_search quando dovrebbe usare internal_kb_search.

  • Causa: descrizioni tool ambigue o sovrapposte.
  • Fix: rivedi descrizioni; aggiungi esempi nel system prompt.

2. Hallucinated tool arguments

L’agente chiama tool valido ma con argomenti inventati (es. get_user(user_id="abc-123") quando non esiste).

  • Causa: pressione del context, modello insicuro.
  • Fix: schema strict, error message educativi reinjected.

3. Infinite loop

L’agente ripete la stessa azione N volte.

  • Causa: observation non lo ferma; nessun progress check.
  • Fix: max-iteration cap, detect repeated actions, “you’ve called this 3 times — try something else”.

4. Premature termination

L’agente conclude “done” senza aver completato il goal.

  • Causa: success bias, prompt non chiaro.
  • Fix: explicit verification step alla fine (“Did you actually complete X?“).

5. Context exhaustion

Loop lungo → context cresce → modello “perde il filo” o costa $$$.

  • Causa: no memory management.
  • Fix: memory compression, summarization, rolling window.

6. Tool result misinterpretation

Tool restituisce dati strutturati, agente li legge male.

  • Causa: parsing non robusto, output troppo grande.
  • Fix: parse manualmente i risultati prima di reinjet; trunca outputs lunghi.

7. Goal drift

Durante loop lungo, l’agente “dimentica” il goal originale.

  • Causa: goal in messages[0], context lungo lo seppellisce.
  • Fix: reinjet il goal in ogni system prompt o ogni N step.

8. Refusal cascade

Modello rifiuta task legittimo (over-refusal).

  • Causa: prompt o tool description trigger safety filter.
  • Fix: rephrasing, custom system prompt che chiarisce contesto legitimo.

9. Action without confirmation

Esegue azione irreversibile senza HITL.

  • Causa: assenza di check pre-action.
  • Fix: pattern “explain what you’d do, ask confirmation, then act” per ogni action distruttiva.

10. Silent partial failure

Tool ritorna error che agente ignora; risultato parziale presentato come successo.

  • Causa: error handling lasciato al modello.
  • Fix: agente DEVE elaborare error response esplicitamente.

Tracing: il prerequisito di tutto

Senza tracing, non puoi capire cosa fa l’agente. Tracing = log strutturato di:

  • Ogni messaggio (system, user, assistant, tool).
  • Ogni tool call (name, args, result, latency, cost).
  • Ogni LLM call (model, tokens in/out, latency, cost).
  • Span hierarchy (chi ha chiamato cosa).

Standard de facto: OpenTelemetry semantic conventions for GenAI (in evoluzione 2025-26).

Tool 2026:

  • Langfuse (open source, self-host o cloud) — il più popolare.
  • Phoenix (Arize) — open source, eval + tracing integrati.
  • LangSmith (LangChain) — managed, integrato con LangChain/Graph.
  • Helicone — focus su costi e cache.
  • Logfire (Pydantic) — moderno, OpenTelemetry native.
  • W&B Weave — focus eval.
  • Braintrust — eval-first.

Setup tipico: 10 minuti per integrare tracing in un agente esistente. Ritorno: 10× quando devi debuggare il primo fail in prod.

LLM-as-judge: pattern e cautele

Pattern: usi un modello forte (Claude Opus, GPT-5) per giudicare output di un agente più piccolo o stesso modello.

Esempio:

You are evaluating an AI agent response.

Goal: {goal}
Agent's final response: {response}

Rate on:
1. Goal completion (1-5): did it achieve the goal?
2. Accuracy (1-5): are facts correct?
3. Efficiency (1-5): not too verbose or wasteful?

Output JSON: {"goal": int, "accuracy": int, "efficiency": int, "reasoning": str}

Pro: scalable, cheap (rispetto a human raters), reproducibile (con seed). Cons:

  • Self-preference bias: GPT giudica meglio GPT.
  • Length bias: tende a preferire risposte lunghe.
  • Position bias: in pairwise, preferisce la prima opzione.
  • Reasoning bias: il “perché” del giudizio può non riflettere il giudizio.

Mitigazione:

  • Usa modello diverso dal candidato (Claude judge per GPT, vv).
  • Rubrica strutturata, non “rate this”.
  • Pairwise comparison + randomize order + multiple rounds.
  • Cross-check con human raters periodici (5-10%).

Eval automation pipeline

Setup CI/CD per agenti:

[Commit changes to agent code/prompt/tools]
        ↓
[CI runs eval suite on N test cases]
        ↓
[Compare metrics vs baseline]
        ↓
[Pass threshold? → merge. Fail? → review]

Tool: Promptfoo (open source CI per prompts/agents), Braintrust, LangSmith CI integration.

Pattern: ogni PR mostra delta success rate vs main. Block merge se peggiora >5%.

Production monitoring continuo

Beyond launch:

Metriche real-time da plottare

  • Success rate (rolling 1h, 24h, 7d).
  • Latency p50/p95/p99.
  • Cost per successful task.
  • Tool error rate.
  • Refusal rate.
  • User feedback (thumb up/down).

Alert su anomalie

  • Success rate drop >10% in 1h → page.
  • Cost per task spike 2× → page.
  • Refusal rate spike → investigate (modello update?).
  • Latency p95 sopra SLA → page.

Sample human review

Random sample 1-5% delle conversazioni → reviewer umano legge → flag issues → feed into improvement backlog.

Drift detection

Modello provider update → behaviour silently changes. Run eval suite settimanalmente per catch.

Costo dell’eval

Setup iniziale: 1-3 settimane di lavoro per costruire eval suite serio + tracing + dashboard.

Costo continuativo:

  • LLM-as-judge calls: 5-15% del costo dell’agente stesso.
  • Human review (1-5% sample): dipende da volume.
  • Tool/infra (Langfuse, dashboard): $50-500/mese tipico.

ROI: cattura un bug serio in produzione e l’investimento è ripagato 10×.

Anti-pattern di eval

  1. “Demo as eval”: 5 esempi cherry-picked che funzionano sempre. Non è eval.
  2. Solo success rate: ignori costo, latency, refusal. Misuri solo 1/4 della verità.
  3. No regression suite: ogni update potrebbe peggiorare e non te ne accorgi.
  4. LLM-as-judge unico: stesso modello per agent e judge → self-preference bias enorme.
  5. No human checkpoint: solo automated metrics → mancano i fallimenti subtle.
  6. Eval set statico per anni: il world cambia, l’eval set deve essere aggiornato.
  7. Ignore negative cases: misuri solo “fa la cosa giusta”, non “evita la cosa sbagliata”.

Realtà dei progetti agentici 2026

Pattern osservato in molte aziende:

  1. Demo iniziale: “wow, funziona!” su 5-10 esempi.
  2. PoC esteso: success rate scende al 70% su 100 test.
  3. Pilot produzione: scopri fallimenti edge che non avevi previsto.
  4. Itera 6 mesi: success rate sale a 80-90%, ma cost/latency cresce.
  5. Either you scale (production-ready) or you kill it. La transition dipende quasi sempre dalla disciplina di eval + monitoring del team.

Le aziende che falliscono: hanno saltato il step 3-4 (“è già pronto, lanciamo”). Quelle che riescono: tracing/eval dall’inizio, eval set crescente, postmortem ogni regression.

Glossario lampo

  • Trajectory eval — valutazione del percorso completo (Thought-Action-Observation) e non solo del risultato finale.
  • LLM-as-judge — pattern in cui un LLM forte giudica le risposte di un agente. Scalabile ma con bias propri.
  • Tracing — log strutturato di ogni step (messages, tool calls, LLM calls) di un agente. Prerequisito per debug e eval.
  • Drift detection — monitoraggio per accorgersi che le performance cambiano nel tempo (model update, world change, data shift).
  • Regression suite — eval rilanciato a ogni cambio per assicurare che le performance non peggiorino.

Take-away

Costruire un agente è facile. Capire se funziona davvero, su quanti casi, a che costo, con quali fallimenti — è il 70% del lavoro. La differenza tra agenti che vivono in produzione e agenti che muoiono dopo la demo: tracing dall’inizio, eval suite con 100+ test, monitoring continuo, human review periodico. È meno glamour del prompt engineering, ma è la sola cosa che separa un PoC da un prodotto.

➡️ Prossima puntata: TEST — costruisci un agente RAG sui tuoi PDF, end-to-end.