Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Trace grading: scoring executions

Lektion 23 af 25 Opdateret 29. juli 2026 Udvikler
På denne side
  1. Trace grading: scoring executions
  2. Konceptet bag trace grading
  3. Automatisk grading med regler
  4. LLM-baseret grading
  5. Grading-pipeline i produktion
  6. Kvalitetsdashboard
  7. Vigtige pointer

Trace grading: scoring executions

Tracing registrerer, hvad din agent gør. Det er afgørende, men det er ikke nok: ingen læser ti tusind traces om dagen, og problemer gemmer sig netop i dem, du aldrig åbner. Trace grading går videre: det scorer automatisk hver kørsel for at opdage fejl, måle kvalitet over tid og drive en løbende forbedringscyklus.

Konceptet bag trace grading

Hvert trace, din agent producerer, indeholder hele kørslen: brugerbeskeden, værktøjskald, mellemliggende svar og det endelige svar. Trace grading analyserer disse traces og tildeler scorer baseret på dine kriterier. Du går fra en log, du slår op efterfølgende, til en metrik, du overvåger løbende, og spørgsmålet „Hvordan klarer agenten sig lige nu?” holder op med at være et gæt.

Automatisk grading med regler

Det enkleste niveau bruger programmerbare regler til at score hvert trace. Hver regel starter med en perfekt score på 1,0 og trækker point fra baseret på observationer. En kørsel, der tager længere tid end ti sekunder, mister 0,2 point – ikke fordi resultatet er forkert, men fordi brugeren sandsynligvis gav op. Mere end femten ture koster 0,3 point: det er signaturen på en agent, der løber i ring mellem to værktøjer. Hver værktøjsfejl trækker 0,1 point fra. Udløste guardrails flagges uden straf – de gjorde deres job – men et svar på under ti tegn koster alene et halvt point, for en tavs agent er en ubrugelig 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,
    )

Ordbogen details følger altid med scoren: uden den ville du vide, at en kørsel scoredes 0,5, men ikke hvorfor. Disse tærskler er dine, ikke universelle konstanter – en forskningsagent tolererer femten ture, hvor en kasseassistent skal svare på tre.

LLM-baseret grading

Regler ser ikke indholdet. Et hurtigt, kort, høfligt svar, der helt misser pointen, vil score 1,0. Til finere evaluering bruger du en model til at score traces på substans: relevans, nøjagtighed og tone, hver fra 1 til 5, sammen med identificerede problemer og forbedringsforslag. Igen gør struktureret output via Pydantic scorerne aggregerbare i stedet for at producere frit formulerede kommentarer.

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

Prompten sender også de kaldte værktøjer og varigheden med: dommeren kan dermed bebrejde agenten, at den svarer uden at konsultere kataloget, hvilket læsning af selve svaret ikke ville tillade.

Grading-pipeline i produktion

Kombinér nu begge tilgange uden at sprænge budgettet. At score hvert trace med en LLM ved produktionsvolumen ganger din inferensregning op; at bruge kun regler efterlader dig blind for substans. Pipelinen nedenfor anvender et filter: alle traces går gennem programmatiske grading, som er hurtig og gratis, og kun dem, der falder under 0,7, sendes til dommeren. Dommerens score, summen af tre 1–5-vurderinger, skaleres til 0–1 ved at dividere med 15 for at forblive sammenlignelig med den første. Under 0,5 rykker tracen ind på listen over kritiske alarmer.

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

Rapporten beholder minimumsscoren og en prøve på de ti værste traces: det er her, en undersøgelse starter, aldrig med gennemsnittet.

Kvalitetsdashboard

En enkelt score betyder ingenting; dens udvikling giver information. Ved at skrive den daglige rapport til en JSONL-fil bygger du en tidsserie, som ethvert visualiseringsværktøj kan læse, og du kan automatisk sammenligne det seneste punkt med det foregående. Et fald på mere end 0,1 udløser en regressionsalarm – og korrelerer du det med dagens deploymenter, peger det normalt på synderen inden for få minutter.

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

Sammenligning af to på hinanden følgende dage forbliver følsom over for støj: ved lavt volumen bør du foretrække et glidende gennemsnit, før du råber regression, ellers jagter du en statistisk udsving.

Vigtige pointer

  • Trace grading scorer automatisk hver kørsel af din agent
  • Programmerbare regler (latens, fejl, længde) er hurtige og pålidelige
  • LLM-grading evaluerer relevans, nøjagtighed og tone
  • Kombinér begge: hurtige regler til filtrering, LLM til grænsetilfælde
  • Følg scorer over tid for at opdage regressioner
  • Kritiske alarmer (score < 0,5) skal udløse en undersøgelse