Trace grading: a végrehajtások pontozása
Ezen az oldalon
Trace grading: a végrehajtások pontozása
A nyomkövetés (tracing) rögzíti, mit tesz az ágensed. Ez elengedhetetlen, de önmagában nem elég: senki nem olvas el naponta tízezer naplót, és a problémák éppen azokban a bejegyzésekben bújnak meg, amelyeket sosem nyitsz meg. A trace grading (nyomkövetési osztályozás) tovább megy: automatikusan pontoz minden egyes végrehajtást, hogy felderítse a hibákat, mérje az időbeli minőséget, és táplálja a folyamatos fejlesztési ciklust.
A trace grading fogalma
Az ágensed által létrehozott minden egyes nyom (trace) tartalmazza a teljes végrehajtást: a felhasználói üzenetet, az eszközhívásokat, a közbenső válaszokat és a végső eredményt. A trace grading elemzi ezeket a nyomokat, és a te kritériumaid alapján pontszámokat rendel hozzá. Így a csak utólag consultált naplóból folyamatosan figyelt metrikává lépsz elő, és a „Hogy teljesít az ágens éppen most?“ kérdés többé nem találgatás.
Automatikus osztályozás szabályokkal
A legegyszerűbb szint programozott szabályokat használ az egyes nyomok pontozására. Minden szabály egy tökéletes 1,0-s pontszámból indul, és levonásokat alkalmaz az észlelt tényezők alapján. Egy tíz másodpercnél tovább tartó végrehajtás 0,2 pontot veszít – nem azért, mert az eredmény rossz, hanem mert a felhasználó valószínűleg feladta a várakozást. A tizenöt lépésnél több 0,3 pontba kerül: ez annak a jele, hogy az ágens körbe-körbe jár két eszköz között. Minden egyes eszközhiba 0,1 pontot von le. A kiváltott biztonsági korlátok (guardrails) figyelmeztetést generálnak büntetés nélkül – elvégezték a dolgukat –, de a tíz karakternél rövidebb válasz önmagában fél pontot ér, mert a hallgató ágens haszontalan ágens.
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,
)
A details szótár mindig kíséri a pontszámot: enélkül tudnád, hogy egy végrehajtás 0,5-öt kapott, de azt nem, hogy miért. Ezek a küszöbértékek a tieid, nem univerzális állandók: egy kutató ágens elvisel tizenöt lépést, míg egy pénztári asszisztensnek három alatt válaszolnia kell.
LLM-alapú osztályozás
A szabályok nem látják a tartalmat. Egy gyors, rövid, udvarias válasz, amely teljesen elkerüli a lényeget, 1,0 pontot kapna. A finomabb értékeléshez használj egy modellt a nyomok tartalmi pontozására: relevancia, pontosság és hangnem, mindegyik 1-től 5-ig, a feltárt problémák és a fejlesztési javaslatok mellett. Itt is a Pydantic-on keresztüli strukturált kimenet teszi aggregálhatóvá a pontszámokat a szabad szöveges kommentárok helyett.
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
A prompt tartalmazza a hívott eszközöket és az időtartamot is: így a bíró felelősségre vonhatja az ágenst, ha a katalógus megkérdezése nélkül válaszol, amit pusztán a válasz olvasása alapján nem tehetne meg.
Osztályozási folyamat gyártási környezetben
Most kombináld mindkét megközelítést anélkül, hogy felrobbantanád a költségvetésedet. Ha gyártási volumenben minden egyes nyomot LLM-mel pontoznál, az megszorozná a következtetési (inference) számládat; ha csak szabályokat használsz, vak maradsz a tartalomra. Az alábbi folyamat egy szűrőt alkalmaz: minden nyom átmegy a programozott osztályozáson, ami gyors és ingyenes, és csak azok kerülnek a bíró elé, amelyek 0,7 alatt teljesítenek. A bíró pontszáma, amely három 1–5 közötti értékelés összege, 0–1 közé skálázódik 15-tel való osztással, hogy összehasonlítható maradjon az elsővel. 0,5 alatt a nyom felkerül a kritikus figyelmeztetések listájára.
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())
A jelentés megtartja a minimális pontszámot és a tíz legrosszabb nyom mintáját: itt kezdődik a vizsgálat, sosem az átlagnál.
Minőségi irányítópult
Egyetlen pontszám önmagában semmit sem jelent; a pályája a mérvadó. A napi jelentés JSONL fájlba írásával olyan idősort építesz fel, amelyet bármely vizualizációs eszköz be tud olvasni, és automatikusan összehasonlíthatod a legfrissebb adatot az előzővel. A 0,1-nél nagyobb esés regressziós riasztást vált ki – és ha ezt összeveted a nap telepítéseivel, általában perceken belül rámutat a bűnösre.
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
Két egymást követő nap összehasonlítása továbbra is érzékeny a zajra: alacsony volumennél érdemes mozgóátlagot használni, mielőtt regressziót kiáltanál, különben statisztikai véletleneket kergetsz.
Főbb megállapítások
- A trace grading automatikusan pontozza az ágensed minden egyes végrehajtását
- A programozott szabályok (késleltetés, hibák, hossz) gyorsak és megbízhatóak
- Az LLM-alapú osztályozás a relevanciát, a pontosságot és a hangnemet értékeli
- Kombináld a kettőt: gyors szabályok a szűréshez, LLM a határesetekhez
- Kövesd nyomon a pontszámokat időben a regressziók észleléséhez
- A kritikus riasztásoknak (pontszám < 0,5) vizsgálatot kell kiváltaniuk