Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Trace grading: uitvoeringen scoren

Les 23 van 25 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Trace grading: uitvoeringen scoren
  2. Het concept van trace grading
  3. Automatische grading met regels
  4. LLM-gebaseerde grading
  5. Grading-pipeline in productie
  6. Kwaliteitsdashboard
  7. Belangrijkste punten

Trace grading: uitvoeringen scoren

Tracing legt vast wat uw agent doet. Dat is essentieel, maar niet voldoende: niemand leest dagelijks tienduizend traces, en problemen verbergen zich juist in die u nooit opent. Trace grading gaat verder: het scoort automatisch elke uitvoering om problemen op te sporen, de kwaliteit in de tijd te meten en een continue verbetercyclus te voeden.

Het concept van trace grading

Elke trace die uw agent produceert, bevat de volledige uitvoering: het gebruikersbericht, tool-aanroepen, tussenliggende antwoorden en het eindantwoord. Trace grading analyseert deze traces en kent scores toe op basis van uw criteria. U verschuift van een logboek dat u achteraf raadpleegt naar een metriek die u continu bewaakt, en de vraag “Hoe presteert de agent op dit moment?” is geen gokwerk meer.

Automatische grading met regels

Het eenvoudigste niveau gebruikt programmatische regels om elke trace te scoren. Elke regel vertrekt van een perfecte score van 1,0 en trekt punten af op basis van wat wordt waargenomen. Een uitvoering die langer dan tien seconden duurt, verliest 0,2 punt, niet omdat het resultaat fout is, maar omdat de gebruiker waarschijnlijk heeft afgehaakt. Meer dan vijftien beurten kost 0,3 punt: dat is het kenmerk van een agent die tussen twee tools in cirkels draait. Elke tool-fout trekt 0,1 punt af. Geactiveerde guardrails worden gemarkeerd zonder strafpunten—ze deden hun werk—maar een antwoord korter dan tien tekens kost alleen al een half punt, want een zwijgzame agent is een nutteloze agent.

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

Het details-woordenboek gaat altijd samen met de score: zonder dit weet u wel dat een uitvoering 0,5 scoorde, maar niet waarom. Deze drempelwaarden zijn van u, geen universele constanten; een onderzoeksagent tolereert vijftien beurten waar een checkout-assistent binnen drie moet antwoorden.

LLM-gebaseerde grading

Regels zien geen inhoud. Een snel, kort, beleefd antwoord dat de kern volledig mist, scoort toch 1,0. Voor fijnere evaluatie gebruikt u een model om traces op inhoud te scoren: relevantie, nauwkeurigheid en toon, elk van 1 tot 5, samen met geïdentificeerde problemen en suggesties voor verbetering. Ook hier maakt gestructureerde output via Pydantic scores aggregeerbaar in plaats van vrijblijvend commentaar te produceren.

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

De prompt geeft ook de aangeroepen tools en de duur door: de rechter kan de agent zo straffen voor het geven van een antwoord zonder de catalogus te raadplegen, wat bij alleen lezen van het antwoord niet mogelijk zou zijn.

Grading-pipeline in productie

Combineer nu beide benaderingen zonder uw budget te laten ontploffen. Het scoren van elke trace met een LLM bij productievolume vermenigvuldigt uw inferentiefactuur; alleen regels gebruiken maakt u blind voor de inhoud. De onderstaande pipeline past een filter toe: alle traces doorlopen de programmatische grading, wat snel en gratis is, en alleen die onder de 0,7 gaan naar de rechter. De score van de rechter, de som van drie ratings van 1–5, wordt geschaald naar 0–1 door te delen door 15 om vergelijkbaar te blijven met de eerste. Onder de 0,5 belandt de trace op de lijst met kritieke waarschuwingen.

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

Het rapport houdt de minimumscore bij en een steekproef van de tien slechtste traces: daar begint een onderzoek, nooit bij het gemiddelde.

Kwaliteitsdashboard

Een enkele score betekent niets; het traject informeert. Door het dagelijkse rapport naar een JSONL-bestand te schrijven, bouwt u een tijdreeks op die elke visualisatietool kan lezen, en kunt u het laatste punt automatisch vergelijken met het vorige. Een daling van meer dan 0,1 activeert een regressie-alert—en correlatie met uw deployments van die dag wijst meestal binnen enkele minuten op de boosdoener.

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

Het vergelijken van twee opeenvolgende dagen blijft gevoelig voor ruis: bij laag volume geeft u de voorkeur aan een voortschrijdend gemiddelde voordat u van regressie spreekt, anders jaagt u op een statistische toevalstreffer.

Belangrijkste punten

  • Trace grading scoort automatisch elke uitvoering van uw agent
  • Programmatische regels (latentie, fouten, lengte) zijn snel en betrouwbaar
  • LLM-grading evalueert relevantie, nauwkeurigheid en toon
  • Combineer beide: snelle regels voor filtering, LLM voor twijfelgevallen
  • Houd scores in de tijd bij om regressies op te sporen
  • Kritieke waarschuwingen (score < 0,5) moeten een onderzoek triggeren