Betygssättning av spår: poängsättning av körningar
På denna sida
Betygssättning av spår: poängsättning av körningar
Spårning registrerar vad din agent gör. Det är avgörande, men det räcker inte: ingen läser tiotusen spår om dagen, och problemen gömmer sig just i de du aldrig öppnar. Betygssättning av spår går ett steg längre: den poängsätter automatiskt varje körning för att upptäcka problem, mäta kvalitet över tid och mata en loop för kontinuerlig förbättring.
Konceptet med betygssättning av spår
Varje spår din agent producerar innehåller hela körningen: användarens meddelande, verktygsanrop, mellanliggande svar och det slutgiltiga svaret. Betygssättning av spår analyserar dessa spår och tilldelar poäng baserat på dina kriterier. Du går från en logg du konsulterar i efterhand till en metrik du övervakar kontinuerligt, och frågan “Hur presterar agenten just nu?” slutar vara ett gissningsspel.
Automatisk betygssättning med regler
Den enklaste nivån använder programmatiska regler för att poängsätta varje spår. Varje regel utgår från en perfekt poäng på 1,0 och drar av poäng baserat på vad den observerar. En körning som tar längre tid än tio sekunder förlorar 0,2 poäng, inte för att resultatet är fel utan för att användaren sannolikt gav upp. Fler än femton turer kostar 0,3 poäng: det är signaturerna för en agent som snurrar i cirklar mellan två verktyg. Varje verktygsfel drar av 0,1 poäng. Aktiverade skyddsräcken flaggas utan straff – de gjorde sitt jobb – men ett svar kortare än tio tecken kostar ensam en halv poäng, för en tyst agent är en värdelös 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,
)
Ordboken details följer alltid med poängen: utan den skulle du veta att en körning fick 0,5 men inte varför. Dessa tröskelvärden är dina, inte universella konstanter – en forskningsagent tolererar femton turer där en kassaassistent måste svara inom tre.
LLM-baserad betygssättning
Regler ser inte innehållet. Ett snabbt, kort, artigt svar som helt missar poängen kommer att få 1,0. För finare utvärdering använder du en modell för att poängsätta spår efter substans: relevans, noggrannhet och ton, vardera från 1 till 5, tillsammans med identifierade problem och förbättringsförslag. Återigen gör strukturerad utmatning via Pydantic poängen aggregerbara istället för att producera fri text-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 skickar också de anropade verktygen och varaktigheten: domaren kan därmed fälla agenten för att svara utan att konsultera katalogen, vilket att bara läsa svaret inte skulle tillåta.
Betygssättningspipeline i produktion
Kombinera nu båda metoderna utan att spränga din budget. Att poängsätta varje spår med en LLM i produktionsvolym multiplicerar din inferensräkning; att bara använda regler lämnar dig blind för substans. Pipelinen nedan applicerar ett filter: alla spår går igenom programmatisk betygssättning, vilket är snabbt och gratis, och endast de som hamnar under 0,7 skickas till domaren. Domarens poäng, summan av tre betyg på 1–5, skalas till 0–1 genom division med 15 för att förbli jämförbar med den första. Under 0,5 hamnar spåret på listan över kritiska varningar.
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 behåller minimipoängen och ett urval av de tio sämsta spåren: det är där en undersökning börjar, aldrig med medelvärdet.
Kvalitetsdashboard
En ensam poäng betyder ingenting; dess utveckling informerar. Genom att skriva den dagliga rapporten till en JSONL-fil bygger du en tidsserie som alla visualiseringsverktyg kan läsa, och du kan automatiskt jämföra den senaste punkten med den föregående. Ett fall på mer än 0,1 utlöser en regressionsvarning – och att korrelera den med dagens distributioner pekar oftast ut boven inom minuter.
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
Att jämföra två på varandra följande dagar förblir känsligt för brus: vid låg volym, föredra ett glidande medelvärde innan du skriker regression, annars jagar du en statistisk tillfällighet.
Viktiga punkter
- Betygssättning av spår poängsätter automatiskt varje körning av din agent
- Programmatiska regler (latens, fel, längd) är snabba och tillförlitliga
- LLM-betygssättning utvärderar relevans, noggrannhet och ton
- Kombinera båda: snabba regler för filtrering, LLM för gränsfall
- Spåra poäng över tid för att upptäcka regressioner
- Kritiska varningar (poäng < 0,5) måste utlösa en undersökning