Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Valutazione delle tracce: punteggio delle esecuzioni

Lezione 23 di 25 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Valutazione delle tracce: punteggio delle esecuzioni
  2. Il concetto di valutazione delle tracce
  3. Valutazione automatica con regole
  4. Valutazione basata su LLM
  5. Pipeline di valutazione in produzione
  6. Dashboard della qualità
  7. Punti chiave

Valutazione delle tracce: punteggio delle esecuzioni

Il tracciamento registra ciò che il tuo agente fa. È essenziale, ma non basta: nessuno legge diecimila tracce al giorno e i problemi si nascondono proprio in quelle che non apri mai. La valutazione delle tracce va oltre: assegna automaticamente un punteggio a ogni esecuzione per individuare problemi, misurare la qualità nel tempo e alimentare un ciclo di miglioramento continuo.

Il concetto di valutazione delle tracce

Ogni traccia prodotta dal tuo agente contiene l’esecuzione completa: il messaggio dell’utente, le chiamate agli strumenti, le risposte intermedie e la risposta finale. La valutazione delle tracce analizza questi dati e assegna punteggi basati sui tuoi criteri. Passi da un log che consulti a posteriori a una metrica che monitori continuamente, e la domanda “Come sta performando l’agente in questo momento?” smette di essere un’ipotesi.

Valutazione automatica con regole

Il livello più semplice utilizza regole programmatiche per assegnare un punteggio a ogni traccia. Ogni regola parte da un punteggio perfetto di 1,0 e sottrae punti in base a ciò che osserva. Un’esecuzione che richiede più di dieci secondi perde 0,2 punti, non perché il risultato sia errato, ma perché l’utente probabilmente ha rinunciato. Più di quindici turni costano 0,3 punti: è la firma di un agente che gira a vuoto tra due strumenti. Ogni errore dello strumento sottrae 0,1 punti. Le guardie di sicurezza attivate vengono segnalate senza penalità—hanno fatto il loro lavoro—ma una risposta inferiore a dieci caratteri costa da sola mezzo punto, perché un agente silenzioso è un agente inutile.

from dataclasses import dataclass

@dataclass
class GradeTrace:
    trace_id: str
    score: float  # 0.0 to 1.0
    details: dict
    alerts: list[str]

def grade_trace(trace_data: dict) -> GradeTrace:
    """Scores a trace based on business rules."""
    score = 1.0
    alerts = []
    details = {}

    # Rule 1: Latency
    duration = trace_data.get("duration_ms", 0)
    if duration > 10000:
        score -= 0.2
        alerts.append(f"High latency: {duration}ms")
    details["latency_ms"] = duration

    # Rule 2: Number of turns
    num_turns = trace_data.get("num_turns", 0)
    if num_turns > 15:
        score -= 0.3
        alerts.append(f"Too many turns: {num_turns}")
    details["num_turns"] = num_turns

    # Rule 3: Tool errors
    tool_errors = trace_data.get("tool_errors", 0)
    if tool_errors > 0:
        score -= 0.1 * tool_errors
        alerts.append(f"{tool_errors} tool error(s)")
    details["tool_errors"] = tool_errors

    # Rule 4: Triggered guardrails
    guardrails = trace_data.get("guardrails_triggered", 0)
    if guardrails > 0:
        alerts.append(f"{guardrails} guardrail(s) triggered")
    details["guardrails"] = guardrails

    # Rule 5: Empty response
    response = trace_data.get("final_output", "")
    if not response or len(response) < 10:
        score -= 0.5
        alerts.append("Empty or too short response")
    details["response_length"] = len(response)

    return GradeTrace(
        trace_id=trace_data["trace_id"],
        score=max(0.0, score),
        details=details,
        alerts=alerts,
    )

Il dizionario details accompagna sempre il punteggio: senza di esso, sapresti che un’esecuzione ha ottenuto 0,5 ma non il perché. Queste soglie sono tue, non costanti universali: un agente di ricerca tollera quindici turni, mentre un assistente al checkout deve rispondere in tre.

Valutazione basata su LLM

Le regole non vedono il contenuto. Una risposta veloce, breve e educata che manca completamente l’obiettivo otterrà 1,0. Per una valutazione più fine, usa un modello per assegnare punteggi alle tracce sulla sostanza: pertinenza, accuratezza e tono, ciascuno da 1 a 5, insieme ai problemi identificati e ai suggerimenti di miglioramento. Anche in questo caso, l’output strutturato tramite Pydantic rende i punteggi aggregabili invece di produrre commenti in forma libera.

from pydantic import BaseModel
from agents import Agent, Runner

class GradeLLM(BaseModel):
    relevance_score: int  # 1-5
    accuracy_score: int  # 1-5
    tone_score: int  # 1-5
    issues: list[str]
    suggestions: list[str]

grader_agent = Agent(
    name="Trace Grader",
    instructions="""You score executions of a sales agent.

    Analyze the full trace (question, tools called, response) and score:
    - Relevance (1-5): Does the response answer the question?
    - Accuracy (1-5): Is the information correct?
    - Tone (1-5): Is the tone professional and appropriate?

    Identify issues and propose improvements.""",
    model="gpt-5.6-sol",
    output_type=GradeLLM,
)

async def grade_trace_llm(trace: dict) -> GradeLLM:
    prompt = f"""Execution trace to score:

    User question: {trace['user_message']}
    Tools called: {trace['tools_called']}
    Final response: {trace['final_output']}
    Duration: {trace['duration_ms']}ms
    Number of turns: {trace['num_turns']}"""

    result = await Runner.run(grader_agent, prompt)
    return result.final_output

Il prompt passa anche gli strumenti chiamati e la durata: il giudice può quindi rimproverare l’agente per aver risposto senza consultare il catalogo, cosa che la sola lettura della risposta non permetterebbe.

Pipeline di valutazione in produzione

Ora combina entrambi gli approcci senza far esplodere il budget. Valutare ogni traccia con un LLM a volumi di produzione moltiplica la tua fattura di inferenza; usare solo regole ti lascia cieco sulla sostanza. La pipeline seguente applica un filtro: tutte le tracce passano attraverso la valutazione programmatica, che è veloce e gratuita, e solo quelle sotto 0,7 vanno al giudice. Il punteggio del giudice, somma di tre valutazioni da 1 a 5, viene scalato a 0–1 dividendo per 15 per rimanere comparabile al primo. Sotto 0,5, la traccia entra nella lista degli avvisi critici.

import asyncio
from collections import defaultdict

class GradingPipeline:
    def __init__(self):
        self.scores = defaultdict(list)
        self.critical_alerts = []

    async def grade_batch(self, traces: list[dict]):
        """Scores a batch of traces."""
        for trace in traces:
            # Programmatic grading (fast)
            rule_grade = grade_trace(trace)

            # LLM grading for borderline cases
            if rule_grade.score < 0.7:
                llm_grade = await grade_trace_llm(trace)
                final_score = (
                    llm_grade.relevance_score +
                    llm_grade.accuracy_score +
                    llm_grade.tone_score
                ) / 15.0  # Normalize to 0-1
            else:
                final_score = rule_grade.score

            self.scores["global"].append(final_score)

            # Alerts
            if final_score < 0.5:
                self.critical_alerts.append({
                    "trace_id": trace["trace_id"],
                    "score": final_score,
                    "alerts": rule_grade.alerts,
                })

    def report(self):
        """Generates a quality report."""
        scores = self.scores["global"]
        if not scores:
            return "No traces evaluated."

        import statistics
        return {
            "num_traces": len(scores),
            "avg_score": statistics.mean(scores),
            "median_score": statistics.median(scores),
            "min_score": min(scores),
            "pct_critical": len(self.critical_alerts) / len(scores),
            "critical_alerts": self.critical_alerts[:10],
        }

# Usage
pipeline = GradingPipeline()
await pipeline.grade_batch(traces_of_the_day)
print(pipeline.report())

Il report mantiene il punteggio minimo e un campione delle dieci tracce peggiori: è da lì che inizia un’indagine, mai dalla media.

Dashboard della qualità

Un singolo punteggio non significa nulla; è la sua traiettoria a informare. Scrivendo il report giornaliero in un file JSONL, costruisci una serie temporale che qualsiasi strumento di visualizzazione può leggere, e puoi confrontare automaticamente l’ultimo punto con il precedente. Un calo superiore a 0,1 attiva un avviso di regressione: correlarlo con i deploy del giorno indica solitamente il colpevole in pochi minuti.

import json
from datetime import datetime

def log_metrics(report: dict, file: str = "agent_metrics.jsonl"):
    """Logs daily metrics."""
    entry = {
        "date": datetime.now().isoformat(),
        **report,
    }
    with open(file, "a") as f:
        f.write(json.dumps(entry) + "\n")

def detect_regression(recent_metrics: list[dict], threshold: float = 0.1):
    """Detects a significant quality drop."""
    if len(recent_metrics) < 2:
        return False
    latest = recent_metrics[-1]["avg_score"]
    previous = recent_metrics[-2]["avg_score"]
    drop = previous - latest
    if drop > threshold:
        print(f"REGRESSION DETECTED: score dropped from {previous:.2f} to {latest:.2f}")
        return True
    return False

Confrontare due giorni consecutivi rimane sensibile al rumore: a basso volume, preferisci una media mobile prima di gridare alla regressione, altrimenti inseguirai un’anomalia statistica.

Punti chiave

  • La valutazione delle tracce assegna automaticamente un punteggio a ogni esecuzione del tuo agente
  • Le regole programmatiche (latenza, errori, lunghezza) sono veloci e affidabili
  • La valutazione con LLM analizza pertinenza, accuratezza e tono
  • Combina entrambi: regole veloci per filtrare, LLM per i casi limite
  • Monitora i punteggi nel tempo per rilevare regressioni
  • Gli avvisi critici (punteggio < 0,5) devono attivare un’indagine