Trace grading: uitvoeringen scoren
Op deze pagina
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