Skip to content
Guides9 min read

KI-Agenten evaluieren: Ein vollständiger Leitfaden zur menschlichen Annotation von Agenten-Traces

Erfahren Sie, wie Sie mit Potatos agentischen Annotationsfunktionen eine vollständige Evaluierungspipeline für KI-Agenten einrichten – von der Trace-Importierung bis zum Annotationsschema-Design.

Potato Team·
यह पृष्ठ अभी आपकी भाषा में उपलब्ध नहीं है। अंग्रेज़ी संस्करण दिखाया जा रहा है।

KI-Agenten evaluieren: Ein vollständiger Leitfaden zur menschlichen Annotation von Agenten-Traces

Automatische Metriken sagen Ihnen, wie oft ein Agent erfolgreich ist. Menschliche Evaluierung sagt Ihnen, warum er scheitert, wo er Fehler macht und wie man ihn verbessert. Dieser Leitfaden beschreibt die Einrichtung einer vollständigen menschlichen Evaluierungspipeline für KI-Agenten mit Potatos agentischen Annotationsfunktionen.

Wir werden einen ReAct-Agenten evaluieren, der Fragen durch Websuchen beantwortet. Am Ende dieses Leitfadens haben Sie:

  • Agenten-Traces in Potato importiert
  • Die Anzeige von Agenten-Traces konfiguriert
  • Sowohl übergreifende als auch schrittweise Annotationsschemata eingerichtet
  • Die Annotationsaufgabe durchgeführt
  • Strukturierte Evaluierungsergebnisse exportiert

Voraussetzungen

Installieren Sie Potato 2.3.0 oder höher:

bash
pip install --upgrade potato-annotation

Sie benötigen außerdem Agenten-Traces zur Evaluierung. Dieser Leitfaden verwendet ReAct-Traces, aber der gleiche Ansatz funktioniert für alle 12 unterstützten Formate.

Schritt 1: Ihre Agenten-Traces vorbereiten

Ein ReAct-Trace ist eine Abfolge von Thought-, Action- und Observation-Schritten. Hier ist ein minimales Beispiel. Erstellen Sie eine Datei unter data/traces.jsonl:

json
{
  "trace_id": "trace_001",
  "task": "What is the capital of Australia and what is its population?",
  "trace": [
    {"type": "thought", "content": "I need to find the capital of Australia and its population. Let me search for this."},
    {"type": "action", "content": "search", "action_input": "capital of Australia"},
    {"type": "observation", "content": "Canberra is the capital city of Australia. It was chosen as the capital in 1908 as a compromise between Sydney and Melbourne."},
    {"type": "thought", "content": "The capital is Canberra. Now I need to find its population."},
    {"type": "action", "content": "search", "action_input": "Canberra population 2025"},
    {"type": "observation", "content": "Canberra has a population of approximately 467,000 as of 2025, making it the eighth-largest city in Australia."},
    {"type": "thought", "content": "I now have both pieces of information. The capital of Australia is Canberra with a population of approximately 467,000."},
    {"type": "action", "content": "finish", "action_input": "The capital of Australia is Canberra, with a population of approximately 467,000 as of 2025."}
  ],
  "ground_truth": "Canberra, approximately 467,000"
}

Jede Zeile in der JSONL-Datei ist ein vollständiger Agenten-Trace. Das Feld trace enthält das schrittweise Protokoll. Das Feld task beschreibt die Aufgabe, die dem Agenten gestellt wurde.

Hinweise zum Trace-Format

Für OpenAI-Function-Calling-Traces sieht das Format anders aus:

json
{
  "trace_id": "oai_001",
  "task": "Find cheap flights from NYC to London",
  "messages": [
    {"role": "user", "content": "Find cheap flights from NYC to London"},
    {"role": "assistant", "content": null, "tool_calls": [{"function": {"name": "search_flights", "arguments": "{\"from\": \"NYC\", \"to\": \"LHR\"}"}}]},
    {"role": "tool", "name": "search_flights", "content": "{\"flights\": [{\"airline\": \"BA\", \"price\": 450}, {\"airline\": \"AA\", \"price\": 520}]}"},
    {"role": "assistant", "content": "I found flights from NYC to London. The cheapest is British Airways at $450."}
  ]
}

Potatos Konverter verarbeitet diese Unterschiede. Sie müssen lediglich den richtigen Konverternamen angeben.

Schritt 2: Die Projektkonfiguration erstellen

Erstellen Sie config.yaml:

yaml
task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task
 
# --- Agentic annotation settings ---
agentic:
  enabled: true
  trace_converter: react
  display_type: agent_trace
 
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    collapse_threshold: 400
    show_step_numbers: true
    show_timestamps: false
    render_json: true
    syntax_highlight: true

Dies weist Potato an:

  1. Traces aus data/traces.jsonl zu laden
  2. Den ReAct-Konverter zum Parsen des trace-Felds zu verwenden
  3. Traces mit dem Agenten-Trace-Display mit farbcodierten Schrittkarten anzuzeigen

Schritt 3: Ihre Annotationsschemata entwerfen

Agentenevaluierung benötigt typischerweise sowohl Trace-Ebene-Urteile (hat der Agent die Aufgabe erfüllt?) als auch Schritt-Ebene-Urteile (war jeder Schritt korrekt?). Lassen Sie uns beides hinzufügen.

Fügen Sie folgendes zu config.yaml hinzu:

yaml
annotation_schemes:
  # --- Trace-level schemas ---
 
  # 1. Task success (the most important metric)
  - annotation_type: radio
    name: task_success
    description: "Did the agent successfully complete the task?"
    labels:
      - "Success"
      - "Partial Success"
      - "Failure"
    label_requirement:
      required: true
    sequential_key_binding: true
 
  # 2. Answer correctness (if the task has a ground truth)
  - annotation_type: radio
    name: answer_correctness
    description: "Is the agent's final answer factually correct?"
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Cannot Determine"
    label_requirement:
      required: true
 
  # 3. Efficiency rating
  - annotation_type: likert
    name: efficiency
    description: "Did the agent use an efficient path to the answer?"
    min: 1
    max: 5
    labels:
      1: "Very Inefficient (many unnecessary steps)"
      3: "Average"
      5: "Optimal (no wasted steps)"
 
  # 4. Free-text notes
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations"
    label_requirement:
      required: false
 
  # --- Step-level schemas ---
 
  # 5. Per-step correctness
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    description: "Was this step correct and useful?"
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Unnecessary"
 
  # 6. Per-step error type (only shown when step is not correct)
  - annotation_type: per_turn_rating
    name: error_type
    target: agentic_steps
    description: "What type of error occurred?"
    rating_type: multiselect
    labels:
      - "Wrong tool/action"
      - "Wrong arguments"
      - "Hallucinated information"
      - "Reasoning error"
      - "Redundant step"
      - "Premature termination"
      - "Other"
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]

Dieses Schema-Design liefert Ihnen:

  • Eine binäre Erfolg/Misserfolg-Metrik für übergreifende Analysen
  • Eine Korrektheitsbewertung zur Evaluierung der Abschlussantwort
  • Eine Effizienzwertung zum Vergleich von Agenten-Strategien
  • Schrittweise Bewertungen, um genau zu identifizieren, wo Agenten Fehler machen
  • Eine bedingte Fehlertaxonomie, die nur erscheint, wenn ein Schritt ein Problem aufweist

Schritt 4: Ausgabe konfigurieren und Server starten

Fügen Sie Ausgabeeinstellungen zu config.yaml hinzu:

yaml
output_annotation_dir: "output/"
output_annotation_format: "jsonl"
 
# Optional: also export to Parquet for analysis
parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd

Vollständige config.yaml als Referenz:

yaml
task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task
 
agentic:
  enabled: true
  trace_converter: react
  display_type: agent_trace
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    collapse_threshold: 400
    show_step_numbers: true
    render_json: true
    syntax_highlight: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    description: "Did the agent successfully complete the task?"
    labels: ["Success", "Partial Success", "Failure"]
    label_requirement:
      required: true
    sequential_key_binding: true
 
  - annotation_type: radio
    name: answer_correctness
    description: "Is the agent's final answer factually correct?"
    labels: ["Correct", "Partially Correct", "Incorrect", "Cannot Determine"]
    label_requirement:
      required: true
 
  - annotation_type: likert
    name: efficiency
    description: "Did the agent use an efficient path?"
    min: 1
    max: 5
    labels:
      1: "Very Inefficient"
      3: "Average"
      5: "Optimal"
 
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations"
    label_requirement:
      required: false
 
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    description: "Was this step correct?"
    rating_type: radio
    labels: ["Correct", "Partially Correct", "Incorrect", "Unnecessary"]
 
  - annotation_type: per_turn_rating
    name: error_type
    target: agentic_steps
    description: "Error type"
    rating_type: multiselect
    labels:
      - "Wrong tool/action"
      - "Wrong arguments"
      - "Hallucinated information"
      - "Reasoning error"
      - "Redundant step"
      - "Premature termination"
      - "Other"
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"
 
parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd

Server starten:

bash
potato start config.yaml -p 8000

Öffnen Sie http://localhost:8000 in Ihrem Browser.

Schritt 5: Der Annotations-Workflow

Wenn ein Annotator einen Trace öffnet, sieht er:

  1. Aufgabenbeschreibung oben (die ursprüngliche Benutzeranfrage)
  2. Schrittkarten, die den vollständigen Agenten-Trace anzeigen, farbcodiert nach Typ:
    • Lila Karten für Gedanken/Überlegungen
    • Blaue Karten für Aktionen/Tool-Aufrufe
    • Grüne Karten für Beobachtungen/Ergebnisse
    • Rote Karten für Fehler
  3. Schrittweise Bewertungssteuerung neben jeder Schrittkarte
  4. Trace-Ebene-Schemata unterhalb der Trace-Anzeige

Der typische Workflow:

  1. Aufgabenbeschreibung lesen, um zu verstehen, was der Agent tun sollte
  2. Die Trace-Schritte durchgehen und jeden einzelnen bewerten
  3. Für jeden als „Teilweise korrekt" oder „Inkorrekt" bewerteten Schritt den/die Fehlertyp(en) auswählen
  4. Den gesamten Trace bewerten (Erfolg, Korrektheit, Effizienz)
  5. Bei Bedarf Anmerkungen hinzufügen
  6. Absenden und zum nächsten Trace übergehen

Tipps für Annotatoren

  • Eingeklappte Beobachtungen aufklappen, um zu prüfen, ob der Agent die Informationen korrekt verarbeitet hat
  • Die Abschlussantwort mit der Ground Truth vergleichen (falls vorhanden), bevor der Aufgabenerfolg bewertet wird
  • „Unnötige" Schritte getrennt von „Inkorrekten" bewerten -- ein unnötiger Schritt verschwendet Aufwand, führt aber keine Fehler ein
  • Die Schritt-Timeline in der Seitenleiste nutzen, um in langen Traces zu bestimmten Schritten zu springen

Schritt 6: Ergebnisse analysieren

Nach der Annotation können Sie die Ergebnisse programmgesteuert analysieren.

Grundlegende Analyse mit pandas

python
import pandas as pd
import json
 
# Load annotations
annotations = []
with open("output/annotations.jsonl") as f:
    for line in f:
        annotations.append(json.loads(line))
 
df = pd.DataFrame(annotations)
 
# Task success rate
success_counts = df.groupby("annotations").apply(
    lambda x: x.iloc[0]["annotations"]["task_success"]
).value_counts()
print("Task Success Distribution:")
print(success_counts)
 
# Average efficiency rating
efficiency_scores = [
    a["annotations"]["efficiency"]
    for a in annotations
    if "efficiency" in a["annotations"]
]
print(f"\nAverage Efficiency: {sum(efficiency_scores) / len(efficiency_scores):.2f}")

Schrittweise Fehleranalyse

python
# Collect all step-level errors
error_counts = {}
for ann in annotations:
    step_errors = ann["annotations"].get("error_type", {})
    for step_idx, errors in step_errors.items():
        for error in errors:
            error_counts[error] = error_counts.get(error, 0) + 1
 
print("Error Type Distribution:")
for error, count in sorted(error_counts.items(), key=lambda x: -x[1]):
    print(f"  {error}: {count}")

Analyse mit DuckDB (über Parquet)

python
import duckdb
 
# Overall success rate
result = duckdb.sql("""
    SELECT value, COUNT(*) as count
    FROM 'output/parquet/annotations.parquet'
    WHERE schema_name = 'task_success'
    GROUP BY value
    ORDER BY count DESC
""")
print(result)

Schritt 7: Skalierung

Für größere Evaluierungsprojekte (Hunderte oder Tausende von Traces) sollten Sie folgende Konfigurationen in Betracht ziehen:

Mehrere Annotatoren

Weisen Sie mehreren Annotatoren pro Trace zu, um die Übereinstimmung zwischen Annotatoren zu messen:

yaml
annotation_task_config:
  total_annotations_per_instance: 3
  assignment_strategy: random

Vorgefertigte Schemata verwenden

Für eine schnelle Einrichtung können Sie Potatos vorgefertigte Agentenevaluierungsschemata verwenden:

yaml
annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy
  - preset: agent_efficiency

Qualitätskontrolle

Aktivieren Sie Gold-Standard-Instanzen für die Qualitätsüberwachung:

yaml
phases:
  training:
    enabled: true
    data_file: "data/training_traces.jsonl"
    passing_criteria:
      min_correct: 4
      total_questions: 5

Anpassung für andere Agententypen

OpenAI Function Calling

yaml
agentic:
  enabled: true
  trace_converter: openai
  display_type: agent_trace

Anthropic Tool Use

yaml
agentic:
  enabled: true
  trace_converter: anthropic
  display_type: agent_trace

Multi-Agenten-Systeme (CrewAI/AutoGen)

yaml
agentic:
  enabled: true
  trace_converter: multi_agent
  display_type: agent_trace
  multi_agent:
    agent_converters:
      researcher: react
      writer: anthropic
      reviewer: openai

Web-Browsing-Agenten

Wechseln Sie für Web-Agenten zur Web-Agent-Anzeige:

yaml
agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
  web_agent_display:
    screenshot_max_width: 900
    overlay:
      enabled: true
    filmstrip:
      enabled: true

Siehe Web-Browsing-Agenten annotieren für einen speziellen Leitfaden.

Zusammenfassung

Die menschliche Evaluierung von KI-Agenten erfordert spezialisierte Werkzeuge. Potatos agentisches Annotationssystem bietet:

  • 12 Konverter zur Normalisierung von Traces aus beliebigen Frameworks
  • 3 Anzeigetypen, optimiert für Tool-Nutzung, Web-Browsing und konversationelle Agenten
  • Pro-Turn-Bewertungen für schrittweise Evaluierung
  • 9 vorgefertigte Schemata für häufige Evaluierungsdimensionen
  • Parquet-Export für effiziente nachgelagerte Analysen

Die wichtigste Erkenntnis ist, dass Agentenevaluierung nicht nur die Frage „Hat der Agent die richtige Antwort gefunden?" ist -- sondern „Hat der Agent bei jedem Schritt korrekt gearbeitet?". Schrittweise Annotationen decken Fehlermuster auf, die aggregierte Metriken übersehen.

Weiterführende Lektüre