Trace grading: suoritusten pisteytys
Tällä sivulla
Trace grading: suoritusten pisteytys
Jäljitys (tracing) tallentaa, mitä agenttisi tekee. Se on välttämätöntä, mutta ei riittävää: kukaan ei lue kymmentätuhatta jäljitystä päivässä, ja ongelmat piilevät nimenomaan niissä, joita et koskaan avaa. Trace grading menee pidemmälle: se pisteyttää automaattisesti jokaisen suorituksen tunnistaakseen ongelmia, mitatakseen laatua ajan myötä ja ruokkiakseen jatkuvan parantamisen kiertoa.
Trace gradingin käsite
Jokainen agenttisi tuottama jäljitys sisältää koko suorituksen: käyttäjän viestin, työkalukutsut, välivastaukset ja lopullisen vastauksen. Trace grading analysoi nämä jäljitykset ja määrittää pisteet kriteeriesi perusteella. Siirryt lokista, jota tarkastelet jälkikäteen, mittariin, jota valvot jatkuvasti, ja kysymys “Miten agentti suoriutuu juuri nyt?” lakkaa olemasta arvaus.
Automaattinen pisteytys sääntöjen avulla
Yksinkertaisin taso käyttää ohjelmallisia sääntöjä jokaisen jäljityksen pisteyttämiseen. Jokainen sääntö lähtee täydestä 1,0:n pisteestä ja vähentää pisteitä havaintojensa perusteella. Suoritus, joka kestää yli kymmenen sekuntia, menettää 0,2 pistettä, ei siksi että tulos olisi väärä, vaan koska käyttäjä todennäköisesti luovutti. Yli viisitoista kierrosta maksaa 0,3 pistettä: se on merkki agentista, joka pyörii kehää kahden työkalun välillä. Jokainen työkaluvirhe vähentää 0,1 pistettä. Laukaistut suojakaiteet (guardrails) merkitään ilman sakkoa – ne tekivät tehtävänsä – mutta alle kymmenen merkin pituinen vastaus maksaa yksinään puoli pistettä, sillä vaikenava agentti on hyödytön agentti.
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,
)
details-sanakirja seuraa aina pistemäärää: ilman sitä tietäisit suorituksen saaneen 0,5 pistettä, mutta et tietäisi miksi. Nämä kynnykset ovat sinun, eivät universaaleja vakioita – tutkimusagentti sietää viisitoista kierrosta, kun taas kassan avustajan on vastattava kolmessa.
LLM-pohjainen pisteytys
Säännöt eivät näe sisältöä. Nopea, lyhyt ja kohtelias vastaus, joka menee täysin ohi asian, saa 1,0 pistettä. Tarkempaa arviointia varten käytä mallia pisteyttämään jäljitykset substanssin perusteella: relevanssi, tarkkuus ja sävy, kukin asteikolla 1–5, yhdessä tunnistettujen ongelmien ja parannusehdotusten kanssa. Jälleen kerran strukturoitu tuloste Pydanticin kautta tekee pisteistä yhdisteltäviä vapaan muotoisen kommentoinnin sijaan.
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
Kehote välittää myös käytetyt työkalut ja keston: tuomari voi näin moittia agenttia vastaamisesta ilman katalogin konsultointia, mikä pelkän vastauksen lukeminen ei mahdollistaisi.
Pisteytysputki tuotannossa
Yhdistä nyt molemmat lähestymistavat räjäyttämättä budjettiasi. Jokaisen jäljityksen pisteyttäminen LLM:llä tuotantomäärillä kertoo inferenssilaskusi; pelkkien sääntöjen käyttö jättää sinut sokeaksi substanssille. Alla oleva putki käyttää suodatinta: kaikki jäljitykset käyvät läpi ohjelmallisen pisteytyksen, joka on nopeaa ja ilmaista, ja vain alle 0,7:n tuloksen saaneet menevät tuomarille. Tuomarin pisteet, kolmen 1–5-arvosanan summa, skaalataan jakamalla 15:llä välille 0–1, jotta ne pysyvät vertailukelpoisina ensimmäisen kanssa. Alle 0,5:n jäljitys siirtyy kriittisten hälytysten listalle.
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())
Raportti säilyttää minimipistemäärän ja otoksen kymmenestä huonoimmasta jäljityksestä: siitä tutkimus alkaa, ei koskaan keskiarvosta.
Laatu-dashboard
Yksittäinen piste ei merkitse mitään; sen kehityssuunta kertoo oleellista. Kirjoittamalla päivittäisen raportin JSONL-tiedostoon rakennat aikasarjan, jonka mikä tahansa visualisointityökalu voi lukea, ja voit automaattisesti verrata viimeisintä pistettä edelliseen. Yli 0,1:n pudotus laukaisee regressiohälytyksen – ja sen korrelointi päivän käyttöönottojen (deployments) kanssa osoittaa yleensä syyllisen minuuteissa.
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
Kahden peräkkäisen päivän vertaaminen on herkkää kohinalle: pienillä volyymeillä suosii liukuvaa keskiarvoa ennen kuin julistat regression, muuten jahtastat tilastollista harhaa.
Keskeiset asiat
- Trace grading pisteyttää automaattisesti jokaisen agenttisi suorituksen
- Ohjelmalliset säännöt (viive, virheet, pituus) ovat nopeita ja luotettavia
- LLM-pisteytys arvioi relevanssia, tarkkuutta ja sävyä
- Yhdistä molemmat: nopeat säännöt suodatukseen, LLM rajatapauksiin
- Seuraa pisteitä ajan myötä havaitaksesi regressiot
- Kriittiset hälytykset (pisteet < 0,5) vaativat tutkimusta