Valuta i tuoi agenti: metriche e benchmark
In questa pagina
Valuta i tuoi agenti: metriche e benchmark
Un agente che funziona in sviluppo può fallire in produzione. La valutazione sistematica è l’unico modo per garantire la qualità prima e dopo il deployment. In questa lezione imparerai a definire le metriche, creare suite di test e automatizzare la valutazione.
Perché valutare?
Senza una valutazione formale, voli alla cieca. Riformuli un’istruzione perché un utente si è lamentato, ma nulla ti dice se l’agente è migliorato o se hai appena rotto tre altri scenari. Esiti tra Terra e Luna per il tuo caso d’uso, o tra due livelli di ragionamento sullo stesso modello, e senza misurazioni la decisione si basa su un’intuizione dopo cinque prove manuali. Modifichi lo schema di uno strumento, l’agente smette di chiamarlo in un caso specifico e nessuno se ne accorge finché il volume dei ticket non esplode. Una suite di valutazione trasforma ciascuna di queste situazioni in un numero comparabile da una versione all’altra.
Metriche fondamentali
Accuratezza
La prima domanda è la più diretta: l’agente fornisce la risposta corretta? Riproduci un insieme di domande di cui conosci la risposta e verifichi la sua presenza nell’output. Il matching di sottostringhe case-insensitive è intenzionalmente grossolano: tollera “Il laptop Pro costa 1.299 € IVA inclusa” dove l’uguaglianza stretta fallirebbe, ma basta per fatti verificabili e si calcola in un secondo.
from agents import Agent, Runner
async def evaluate_accuracy(agent, test_cases):
results = []
for case in test_cases:
result = await Runner.run(agent, case["question"])
# Verifica automatica o basata su LLM
is_correct = case["expected_answer"].lower() in result.final_output.lower()
results.append({
"question": case["question"],
"answer": result.final_output,
"expected": case["expected_answer"],
"correct": is_correct,
})
rate = sum(1 for r in results if r["correct"]) / len(results)
print(f"Accuratezza: {rate:.1%} ({sum(1 for r in results if r['correct'])}/{len(results)})")
return results
# Suite di test
test_cases = [
{"question": "Qual è il prezzo del laptop Pro?", "expected_answer": "1299"},
{"question": "Quanti laptop sono in stock?", "expected_answer": "45"},
{"question": "Qual è il prodotto più economico?", "expected_answer": "tablet"},
]
Uso corretto degli strumenti
Una risposta corretta ottenuta per caso rimane un problema. Un agente che recita un prezzo memorizzato invece di interrogare il catalogo supererà il test di accuratezza oggi e fornirà una tariffa obsoleta domani. La seconda metrica guarda quindi al percorso, non al risultato: l’agente chiama gli strumenti giusti con gli argomenti corretti? Leggi le chiamate in raw_responses, filtrando per output function_call, e il confronto usa gli insiemi per rimanere indifferente all’ordine.
async def evaluate_tools(agent, test_cases):
results = []
for case in test_cases:
result = await Runner.run(agent, case["question"])
# Estrai gli strumenti chiamati dalle risposte grezze
called_tools = []
for response in result.raw_responses:
for output in getattr(response, "output", []):
if hasattr(output, "type") and output.type == "function_call":
called_tools.append(output.name)
tools_correct = set(case["expected_tools"]) == set(called_tools)
results.append({
"question": case["question"],
"called_tools": called_tools,
"expected_tools": case["expected_tools"],
"correct": tools_correct,
})
rate = sum(1 for r in results if r["correct"]) / len(results)
print(f"Strumenti corretti: {rate:.1%}")
return results
tool_cases = [
{
"question": "Qual è il prezzo del laptop?",
"expected_tools": ["search_product"],
},
{
"question": "Prezzo del laptop con sconto del 10%",
"expected_tools": ["search_product", "calculate_discount"],
},
]
Il secondo caso di test è il più istruttivo: la domanda richiede di concatenare due strumenti, ed è esattamente il tipo di composizione che una modifica nella descrizione può rompere silenziosamente.
Latenza e costo
Infine, c’è la dimensione operativa. Una media non dice nulla sull’esperienza reale: è la coda della distribuzione che allontana gli utenti, quando una richiesta su cento impiega venti secondi. Ripetendo ogni messaggio più volte, ottieni una distribuzione utilizzabile e leggi la mediana come comportamento tipico e il P99 come il tuo scenario peggiore comune.
import time
async def evaluate_performance(agent, messages, iterations=10):
latencies = []
for message in messages:
for _ in range(iterations):
start = time.perf_counter()
result = await Runner.run(agent, message)
duration = time.perf_counter() - start
latencies.append(duration)
import statistics
print(f"Latenza media: {statistics.mean(latencies):.2f}s")
print(f"Latenza P50: {statistics.median(latencies):.2f}s")
print(f"Latenza P99: {sorted(latencies)[int(len(latencies) * 0.99)]:.2f}s")
Valutazione tramite LLM (LLM-as-Judge)
Queste tre metriche lasciano fuori tutto ciò che non ha una singola risposta corretta: una spiegazione di una politica di reso, una riformulazione di vendita, un messaggio di scuse. Per queste risposte aperte, usa un modello per valutare la qualità. Il giudice riceve la domanda e la risposta, applica criteri che hai scritto (accuratezza, pertinenza, professionalità) e restituisce un punteggio strutturato grazie a un output_type Pydantic. È il vincolo di formato che rende il processo utilizzabile: ottieni un intero aggregabile, non un commento da rileggere.
from pydantic import BaseModel
class Evaluation(BaseModel):
score: int # 1-5
reason: str
is_correct: bool
is_relevant: bool
is_professional: bool
evaluator_agent = Agent(
name="Evaluator",
instructions="""Valuta la qualità della risposta dell'agente.
Criteri:
- Accuratezza: La risposta è fattuale e corretta?
- Pertinenza: La risposta risponde alla domanda posta?
- Professionalità: Il tono è appropriato?
Punteggio da 1 (molto scarso) a 5 (eccellente).""",
model="gpt-5.6-sol",
output_type=Evaluation,
)
async def evaluate_quality(question, agent_response):
prompt = f"""Domanda posta: {question}
Risposta dell'agente: {agent_response}
Valuta questa risposta."""
result = await Runner.run(evaluator_agent, prompt)
return result.final_output
Il campo reason merita la tua attenzione durante le revisioni: è qui che il giudice spiega perché ha dato 3 su 5, ed è spesso la formulazione di un difetto che non eri riuscito a nominare.
Suite di test strutturate
Una valutazione non riproducibile è inutile. Organizza i tuoi casi di test in un formato stabile in cui ogni voce porta un ID, una categoria, la domanda, la risposta attesa, gli strumenti attesi e i criteri qualitativi. La categoria fa tutto il lavoro qui: un punteggio complessivo di 4,2 su 5 è ingannevolmente rassicurante, mentre un punteggio dettagliato rivela che la categoria “stock” crolla a 2,8 mentre “prezzo” tira su la media.
import json
# evaluation_dataset.json
DATASET = [
{
"id": "test_001",
"category": "price",
"question": "Qual è il prezzo del laptop Pro?",
"expected_answer": "1.299 €",
"expected_tools": ["search_product"],
"criteria": ["contains_price", "professional_tone"],
},
{
"id": "test_002",
"category": "stock",
"question": "Il Tablet Air è in stock?",
"expected_answer": "sì",
"expected_tools": ["search_product"],
"criteria": ["clear_answer", "stock_information"],
},
]
async def run_complete_evaluation(agent):
results = []
for case in DATASET:
result = await Runner.run(agent, case["question"])
eval_result = await evaluate_quality(case["question"], result.final_output)
results.append({
**case,
"agent_response": result.final_output,
"score": eval_result.score,
"evaluation": eval_result.reason,
})
# Report
average_score = sum(r["score"] for r in results) / len(results)
print(f"\nPunteggio medio: {average_score:.1f}/5")
for cat in set(r["category"] for r in results):
cat_scores = [r["score"] for r in results if r["category"] == cat]
print(f" {cat}: {sum(cat_scores)/len(cat_scores):.1f}/5")
return results
Esegui questa valutazione nella tua pipeline di integrazione continua, proprio come i tuoi unit test, e imposta una soglia al di sotto della quale la consegna viene bloccata. Da quel momento, ogni cambiamento (nuovo modello, istruzioni modificate, strumento aggiunto) si confronta con il precedente sugli stessi casi e la discussione smette di girare attorno alle impressioni.
Punti chiave
- Valuta accuratezza, uso degli strumenti, latenza e costo
- La valutazione tramite LLM (LLM-as-Judge) gestisce le risposte aperte
- Crea suite di test strutturate e riproducibili
- Automatizza la valutazione nel tuo CI/CD per rilevare le regressioni
- Confronta sistematicamente i cambiamenti (modello, istruzioni, strumenti)