Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Trace-Bewertung: Bewertung von Ausführungen

Lektion 23 von 25 Aktualisiert am 29. Juli 2026 Entwickler
Auf dieser Seite
  1. Trace-Bewertung: Bewertung von Ausführungen
  2. Das Konzept der Trace-Bewertung
  3. Automatische Bewertung mit Regeln
  4. LLM-basierte Bewertung
  5. Bewertungs-Pipeline in der Produktion
  6. Qualitäts-Dashboard
  7. Kernaussagen

Trace-Bewertung: Bewertung von Ausführungen

Traces erfassen, was Ihr Agent tut. Das ist essenziell, reicht aber nicht aus: Niemand liest täglich zehntausend Traces, und Probleme verstecken sich genau in denen, die Sie nie öffnen. Trace-Bewertung geht einen Schritt weiter: Sie bewertet jede Ausführung automatisch, um Probleme zu erkennen, die Qualität über die Zeit zu messen und einen kontinuierlichen Verbesserungszyklus anzustoßen.

Das Konzept der Trace-Bewertung

Jeder Trace, den Ihr Agent erzeugt, enthält die vollständige Ausführung: die Benutzeranfrage, Tool-Aufrufe, Zwischenergebnisse und die finale Antwort. Die Trace-Bewertung analysiert diese Traces und weist ihnen Punkte basierend auf Ihren Kriterien zu. Sie wechseln von einem Protokoll, das Sie nachträglich konsultieren, zu einer Metrik, die Sie kontinuierlich überwachen, und die Frage „Wie performt der Agent gerade?” hört auf, eine Vermutung zu sein.

Automatische Bewertung mit Regeln

Die einfachste Ebene verwendet programmatische Regeln, um jeden Trace zu bewerten. Jede Regel startet bei einer perfekten Punktzahl von 1,0 und zieht Punkte ab, basierend auf dem, was sie beobachtet. Eine Ausführung, die länger als zehn Sekunden dauert, verliert 0,2 Punkte, nicht weil das Ergebnis falsch ist, sondern weil der Benutzer wahrscheinlich aufgegeben hat. Mehr als fünfzehn Runden kosten 0,3 Punkte: Das ist das Zeichen dafür, dass ein Agent zwischen zwei Tools im Kreis läuft. Jeder Tool-Fehler zieht 0,1 Punkte ab. Ausgelöste Guardrails werden markiert, ohne dass Punkte abgezogen werden – sie haben ihre Arbeit getan –, aber eine Antwort, die kürzer als zehn Zeichen ist, kostet allein einen halben Punkt, da ein stummer Agent ein nutzloser Agent ist.

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

Das details-Diktum begleitet die Punktzahl immer: Ohne es wüssten Sie zwar, dass eine Ausführung 0,5 Punkte erreicht hat, aber nicht warum. Diese Schwellenwerte sind Ihre eigenen, keine universellen Konstanten – ein Forschungsagent toleriert fünfzehn Runden, wo ein Kassenassistent innerhalb von drei Antworten antworten muss.

LLM-basierte Bewertung

Regeln sehen keinen Inhalt. Eine schnelle, kurze, höfliche Antwort, die den Punkt völlig verfehlt, würde 1,0 Punkte erhalten. Für eine feinere Evaluation verwenden Sie ein Modell, um Traces nach Substanz zu bewerten: Relevanz, Genauigkeit und Ton, jeweils von 1 bis 5, zusammen mit identifizierten Problemen und Verbesserungsvorschlägen. Auch hier macht strukturierte Ausgabe über Pydantic die Punktzahlen aggregierbar, anstatt freiformiger Kommentare zu erzeugen.

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

Der Prompt überträgt auch die aufgerufenen Tools und die Dauer: Der Richter kann den Agenten also dafür bestrafen, dass er ohne Konsultation des Katalogs antwortet, was die reine Lektüre der Antwort allein nicht erlauben würde.

Bewertungs-Pipeline in der Produktion

Kombinieren Sie nun beide Ansätze, ohne Ihr Budget zu sprengen. Die Bewertung jedes Traces mit einem LLM in Produktionsvolumen vervielfacht Ihre Inferenzkosten; der Einsatz nur von Regeln lässt Sie im Bezug auf die Substanz blind. Die folgende Pipeline wendet einen Filter an: Alle Traces durchlaufen die programmatische Bewertung, die schnell und kostenlos ist, und nur diejenigen, die unter 0,7 liegen, gehen zum Richter. Die Punktzahl des Richters, die Summe aus drei Bewertungen von 1–5, wird durch 15 geteilt, um auf 0–1 skaliert zu werden und mit der ersten vergleichbar zu bleiben. Unter 0,5 gehört der Trace zur Liste der kritischen Warnungen.

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

Der Bericht behält die minimale Punktzahl und eine Auswahl der zehn schlechtesten Traces bei: Dort beginnt eine Untersuchung, niemals mit dem Durchschnitt.

Qualitäts-Dashboard

Eine einzelne Punktzahl bedeutet nichts; ihre Entwicklung informiert. Indem Sie den täglichen Bericht in eine JSONL-Datei schreiben, erstellen Sie eine Zeitreihe, die jedes Visualisierungstool lesen kann, und Sie können den neuesten Punkt automatisch mit dem vorherigen vergleichen. Ein Rückgang von mehr als 0,1 löst eine Regression-Warnung aus – und die Korrelation mit Ihren täglichen Bereitstellungen zeigt in der Regel innerhalb weniger Minuten den Übeltäter.

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

Der Vergleich von zwei aufeinanderfolgenden Tagen bleibt empfindlich gegenüber Rauschen: Bei geringem Volumen bevorzugen Sie einen gleitenden Durchschnitt, bevor Sie eine Regression beklagen, sonst jagen Sie einem statistischen Ausreißer hinterher.

Kernaussagen

  • Trace-Bewertung bewertet automatisch jede Ausführung Ihres Agents
  • Programmatische Regeln (Latenz, Fehler, Länge) sind schnell und zuverlässig
  • LLM-Bewertung evaluiert Relevanz, Genauigkeit und Ton
  • Kombinieren Sie beide: Schnelle Regeln zum Filtern, LLM für Grenzfälle
  • Verfolgen Sie Punktzahlen über die Zeit, um Regressionen zu erkennen
  • Kritische Warnungen (Punktzahl < 0,5) müssen eine Untersuchung auslösen