Ocjena tragova: bodovanje izvršavanja
Na ovoj stranici
Ocjena tragova: bodovanje izvršavanja
Praćenje (tracing) bilježi što tvoj agent radi. To je nužno, ali nije dovoljno: nitko ne čita deset tisuća tragova dnevno, a problemi se kriju upravo u onima koje nikad ne otvoriš. Ocjena tragova ide korak dalje: automatski boduje svako izvršavanje kako bi otkrila probleme, mjerila kvalitetu tijekom vremena i napajala petlju kontinuiranog poboljšanja.
Koncept ocjene tragova
Svaki trag koji tvoj agent proizvede sadrži cijelo izvršavanje: korisničku poruku, pozive alata, međuresponze i konačni odgovor. Ocjena tragova analizira te tragove i dodjeljuje bodove na temelju tvojih kriterija. Prelaziš s dnevnika koji konzultiraš naknadno na metrika koju pratiš kontinuirano, a pitanje „Kako agent trenutno radi?“ prestaje biti nagađanje.
Automatsko bodovanje pravilima
Najjednostavnija razina koristi programirana pravila za bodovanje svakog traga. Svako pravilo kreće od savršenog rezultata 1,0 i oduzima bodove na temelju onoga što detektira. Izvršavanje koje traje dulje od deset sekundi gubi 0,2 boda, ne zato što je rezultat pogrešan, već zato što je korisnik vjerojatno odustao. Više od petnaest okretaja košta 0,3 boda: to je potpis agenta koji se vrti u krug između dva alata. Svaka pogreška alata oduzima 0,1 boda. Aktivirane zaštitne ograde (guardrails) se označuju bez kazne – one su odradile svoj posao – ali odgovor kraći od deset znakova sam po sebi košta pola boda, jer je šutljivi agent beskoristan 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,
)
Rječnik details uvijek prati bod: bez njega bi znao da je izvršavanje osvojilo 0,5, ali ne i zašto. Ti pragovi su tvoji, nisu univerzalne konstante – istraživački agent tolerira petnaest okretaja gdje asistent za naplatu mora odgovoriti u tri.
Bodovanje pomoću LLM-a
Pravila ne vide sadržaj. Brz, kratak, ljubazan odgovor koji potpuno promašuje poantu dobit će 1,0. Za precizniju evaluaciju upotrijebi model za bodovanje tragova prema suštini: relevantnost, točnost i ton, svaki od 1 do 5, uz identificirane probleme i prijedloge za poboljšanje. Ponovno, strukturirani izlaz putem Pydantica čini bodove agregabilnima umjesto da proizvodi komentar slobodnog oblika.
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
Upit također prosljeđuje pozvane alate i trajanje: sudac tako može zamjeriti agentu što je odgovorio bez konzultiranja kataloga, što samo čitanje odgovora ne bi omogućilo.
Cjevovod za ocjenjivanje u produkciji
Sada spoji oba pristupa bez probijanja budžeta. Bodovanje svakog traga LLM-om pri produkcijskom volumenu umnožava tvoj račun za inferenciju; korištenje samo pravila ostavlja te slijepim za suštinu. Cjevovod u nastavku primjenjuje filtar: svi tragovi prolaze kroz programsko bodovanje, koje je brzo i besplatno, a samo oni ispod 0,7 idu sucu. Sucov bod, zbroj tri ocjene od 1–5, skalira se na 0–1 dijeljenjem s 15 kako bi ostao usporediv s prvim. Ispod 0,5, trag ulazi u popis kritičnih upozorenja.
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())
Izvještaj zadržava minimalni bod i uzorak od deset najgorih tragova: tu počinje istraga, nikad s prosjekom.
Nadzorna ploča kvalitete
Jedan bod ništa ne znači; njegova putanja informira. Zapisivanjem dnevnog izvještaja u JSONL datoteku gradiš vremenski niz koji bilo koji alat za vizualizaciju može pročitati, a možeš automatski usporediti najnoviju točku s prethodnom. Pad veći od 0,1 pokreće upozorenje o regresiji – a povezivanje toga s tvojim današnjim implementacijama obično u roku od nekoliko minuta upućuje na krivca.
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
Usporedba dva uzastopna dana ostaje osjetljiva na šum: pri malom volumenu, prije nego što proglasiš regresiju, preferiraj pomični prosjek, inače ćeš juriti statistički šum.
Ključne točke
- Ocjena tragova automatski boduje svako izvršavanje tvog agenta
- Programirana pravila (kašnjenje, pogreške, duljina) su brza i pouzdana
- LLM bodovanje evaluira relevantnost, točnost i ton
- Kombiniraj oboje: brza pravila za filtriranje, LLM za granične slučajeve
- Prati bodove tijekom vremena za otkrivanje regresija
- Kritična upozorenja (bod < 0,5) moraju pokrenuti istragu