Salt la conținutul principal
Română— Alege o limbă
Meniu

Evaluarea urmelor: notarea execuțiilor

Lecția 23 din 25 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Evaluarea urmelor: notarea execuțiilor
  2. Conceptul de evaluare a urmelor
  3. Notarea automată prin reguli
  4. Evaluarea bazată pe LLM
  5. Fluxul de evaluare în producție
  6. Panoul de control al calității
  7. Puncte cheie

Evaluarea urmelor: notarea execuțiilor

Urmărirea (tracing) înregistrează acțiunile agentului dumneavoastră. Acest lucru este esențial, dar insuficient: nimeni nu citește zece mii de urme zilnic, iar problemele se ascund tocmai în cele pe care nu le deschideți niciodată. Evaluarea urmelor (trace grading) merge mai departe: notează automat fiecare execuție pentru a detecta problemele, a măsura calitatea în timp și a alimenta un ciclu continuu de îmbunătățire.

Conceptul de evaluare a urmelor

Fiecare urmă generată de agentul dumneavoastră conține execuția completă: mesajul utilizatorului, apelurile către instrumente, răspunsurile intermediare și răspunsul final. Evaluarea urmelor analizează aceste date și atribuie note pe baza criteriilor dumneavoastră. Treceți de la un jurnal consultat post-factum la o metrică monitorizată continuu, iar întrebarea „Cum performează agentul chiar acum?“ încetează să mai fie o ghicitoare.

Notarea automată prin reguli

Nivelul cel mai simplu utilizează reguli programatice pentru a nota fiecare urmă. Fiecare regulă pornește de la un scor perfect de 1.0 și scade puncte în funcție de ceea ce observă. O execuție care durează mai mult de zece secunde pierde 0.2 puncte, nu pentru că rezultatul este greșit, ci deoarece utilizatorul probabil a renunțat. Mai mult de cincisprezece interacțiuni (turns) costă 0.3 puncte: acesta este semnul distinctiv al unui agent care se învârte în cerc între două instrumente. Fiecare eroare de instrument scade 0.1 puncte. Gardurile de siguranță (guardrails) activate sunt semnalate fără penalizare – și-au făcut treaba – dar un răspuns mai scurt de zece caractere costă singur jumătate de punct, deoarece un agent tăcut este un agent inutil.

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,
    )

Dicționarul details însoțește întotdeauna nota: fără el, ați ști că o execuție a obținut 0.5, dar nu și de ce. Aceste praguri vă aparțin, nu sunt constante universale; un agent de cercetare tolerează cincisprezece interacțiuni, în timp ce un asistent de checkout trebuie să răspundă în trei.

Evaluarea bazată pe LLM

Regulile nu văd conținutul. Un răspuns rapid, scurt și politicos, care ratează complet subiectul, va obține nota 1.0. Pentru o evaluare mai fină, utilizați un model pentru a nota urmele în funcție de substanță: relevanță, acuratețe și ton, fiecare de la 1 la 5, împreună cu problemele identificate și sugestiile de îmbunătățire. Din nou, ieșirea structurată prin Pydantic face notele agregabile, în loc să producă comentarii în formă liberă.

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

Prompt-ul transmite, de asemenea, instrumentele apelate și durata: astfel, evaluatorul poate imputa agentului faptul că a răspuns fără a consulta catalogul, lucru pe care simpla citire a răspunsului nu l-ar permite.

Fluxul de evaluare în producție

Combinați acum ambele abordări fără a vă exploata bugetul. Notarea fiecărei urme cu un LLM la volum de producție vă multiplică factura de inferență; utilizarea exclusivă a regulilor vă lasă orb în fața substanței. Fluxul de mai jos aplică un filtru: toate urmele trec prin evaluarea programatică, care este rapidă și gratuită, iar doar cele care scad sub 0.7 merg la evaluatorul LLM. Nota evaluatorului, suma a trei calificative de la 1 la 5, este scalată la 0–1 prin împărțirea la 15 pentru a rămâne comparabilă cu prima. Sub 0.5, urma se alătură listei de alerte critice.

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())

Raportul păstrează nota minimă și un eșantion al celor mai slabe zece urme: aici începe o investigație, niciodată la media generală.

Panoul de control al calității

O singură notă nu înseamnă nimic; traiectoria sa este cea care informează. Scriind raportul zilnic într-un fișier JSONL, construiți o serie temporală pe care orice instrument de vizualizare o poate citi, permițând compararea automată a ultimului punct cu cel anterior. O scădere de peste 0.1 declanșează o alertă de regresie – iar corelarea acesteia cu implementările (deployments) zilei indică de obicei vinovatul în câteva minute.

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

Compararea a două zile consecutive rămâne sensibilă la zgomot: la volume mici, preferați o medie mobilă înainte de a striga „regresie“, altfel veți urmări o anomalie statistică.

Puncte cheie

  • Evaluarea urmelor notează automat fiecare execuție a agentului dumneavoastră
  • Regulile programatice (latență, erori, lungime) sunt rapide și fiabile
  • Evaluarea prin LLM analizează relevanța, acuratețea și tonul
  • Combinați ambele: reguli rapide pentru filtrare, LLM pentru cazurile limită
  • Urmăriți notele în timp pentru a detecta regresii
  • Alertele critice (notă < 0.5) trebuie să declanșeze o investigație