Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Trace grading: scoring executions

Nodarbība 23 no 25 Atjaunota 2026. gada 29. jūlijs Programmētājs
Šajā lapā
  1. Trace grading : notation des exécutions
  2. Le concept de trace grading
  3. Notation automatique par règles
  4. Notation par LLM
  5. Pipeline de notation en production
  6. Tableau de bord qualité
  7. Galvenās atziņas

Trace grading : notation des exécutions

La traçabilité enregistre ce que fait ton agent. C’est essentiel, mais insuffisant : personne ne lit dix mille traces par jour, et les problèmes se cachent précisément dans celles que tu n’ouvres jamais. Le trace grading (notation des traces) va plus loin : il note automatiquement chaque exécution pour repérer les anomalies, mesurer la qualité dans le temps et alimenter une boucle d’amélioration continue.

Le concept de trace grading

Chaque trace produite par ton agent contient l’exécution complète : le message de l’utilisateur, les appels d’outils, les réponses intermédiaires et la réponse finale. Le trace grading analyse ces traces et attribue des scores selon tes critères. Tu passes d’un journal consulté après coup à une métrique surveillée en continu, et la question « Comment l’agent performe-t-il maintenant ? » cesse d’être une devinette.

Notation automatique par règles

Le niveau le plus simple utilise des règles programmatiques pour noter chaque trace. Chaque règle part d’un score parfait de 1,0 et déduit des points selon ce qu’elle observe. Une exécution qui prend plus de dix secondes perd 0,2 point, non parce que le résultat est faux, mais parce que l’utilisateur a probablement abandonné. Plus de quinze tours coûtent 0,3 point : c’est la signature d’un agent qui tourne en rond entre deux outils. Chaque erreur d’outil déduit 0,1 point. Les garde-fous déclenchés sont signalés sans pénalité — ils ont fait leur travail — mais une réponse de moins de dix caractères coûte à elle seule un demi-point, car un agent silencieux est un agent 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,
    )

Le dictionnaire details accompagne toujours le score : sans lui, tu saurais qu’une exécution a obtenu 0,5, mais pas pourquoi. Ces seuils t’appartiennent, ce ne sont pas des constantes universelles : un agent de recherche tolère quinze tours là où un assistant de paiement doit répondre en trois.

Notation par LLM

Les règles ne voient pas le contenu. Une réponse rapide, courte et polie qui rate complètement la cible obtiendra 1,0. Pour une évaluation plus fine, utilise un modèle pour noter les traces sur le fond : pertinence, exactitude et ton, chacun de 1 à 5, accompagnés des problèmes identifiés et des suggestions d’amélioration. Là encore, une sortie structurée via Pydantic rend les scores agrégables au lieu de produire des commentaires en forme libre.

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

Le prompt transmet aussi les outils appelés et la durée : le juge peut ainsi reprocher à l’agent d’avoir répondu sans consulter le catalogue, ce que la seule lecture de la réponse ne permettrait pas.

Pipeline de notation en production

Combine maintenant les deux approches sans faire exploser ton budget. Noter chaque trace avec un LLM à volume de production multiplie ta facture d’inférence ; n’utiliser que des règles te rend aveugle au fond. Le pipeline ci-dessous applique un filtre : toutes les traces passent par la notation programmatique, rapide et gratuite, et seules celles tombant sous 0,7 vont au juge. Le score du juge, somme de trois notes de 1 à 5, est ramené à l’échelle 0–1 par division par 15 pour rester comparable au premier. En dessous de 0,5, la trace rejoint la liste des alertes critiques.

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())

Le rapport conserve le score minimum et un échantillon des dix pires traces : c’est là que commence une investigation, jamais avec la moyenne.

Tableau de bord qualité

Un score isolé ne signifie rien ; c’est sa trajectoire qui informe. En écrivant le rapport quotidien dans un fichier JSONL, tu construis une série temporelle lisible par n’importe quel outil de visualisation, et tu peux comparer automatiquement le dernier point au précédent. Une chute de plus de 0,1 déclenche une alerte de régression — et la corréler avec tes déploiements du jour pointe généralement le coupable en quelques minutes.

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

Comparer deux jours consécutifs reste sensible au bruit : sur un faible volume, privilégie une moyenne mobile avant de crier à la régression, sinon tu courras après un artefact statistique.

Galvenās atziņas

  • Le trace grading note automatiquement chaque exécution de ton agent
  • Les règles programmatiques (latence, erreurs, longueur) sont rapides et fiables
  • La notation par LLM évalue la pertinence, l’exactitude et le ton
  • Combine les deux : règles rapides pour filtrer, LLM pour les cas limites
  • Suis les scores dans le temps pour détecter les régressions
  • Les alertes critiques (score < 0,5) doivent déclencher une investigation