Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Trace grading: a végrehajtások pontozása

23. lecke 25 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Trace grading: a végrehajtások pontozása
  2. A trace grading fogalma
  3. Automatikus osztályozás szabályokkal
  4. LLM-alapú osztályozás
  5. Osztályozási folyamat gyártási környezetben
  6. Minőségi irányítópult
  7. Főbb megállapítások

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