> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Evaluierungszentrum

> Bewerten Sie Ihre Agenten quantitativ mit Testdatensätzen und automatisierter LLM-Bewertung.

Das Evaluierungszentrum ermöglicht es Ihnen, die Qualität von Agenten **vor** der Bereitstellung in der Produktion zu überprüfen. Erstellen Sie einen Datensatz mit Testfällen, führen Sie diese gegen jeden veröffentlichten Agenten aus, und erhalten Sie einen quantitativen Bericht mit Bestanden/Nicht-Bestanden-Verdikten pro Fall, Latenz und Token-Nutzung.

<Info>
  Entwickelt für die Überprüfung durch Unternehmenseinkauf — jedes Ergebnis ist nachverfolgbar, reproduzierbar und dauerhaft gespeichert.
</Info>

## Funktionsweise

Jede Evaluierungslauf führt eine **dreistufige Pipeline** für jeden Testfall aus:

<Steps>
  <Step title="Agent-Ausführung">
    Ein echter ReActAgent führt die Testfall-Eingabeaufforderung aus. Gleiche Engine wie Chat: gleiches Modell, gleiche Tools, gleiche Anweisungen. Kein Mocking, keine Abkürzungen.

    Erzeugt: **Antwort**, **Latenz**, **Token-Nutzung**.
  </Step>

  <Step title="LLM-Bewertung">
    Ein separates "Bewerter"-LLM (schnelles Modell) bewertet die Antwort gegen das erwartete Verhalten und Assertions.

    Eingabe: Eingabeaufforderung + erwartetes Verhalten + Assertions + Antwort. Ausgabe: `{ verdict: "pass"|"fail", reasoning: "..." }`.
  </Step>

  <Step title="Persistierung & Aggregation">
    Jedes Fallergebnis wird in der Datenbank gespeichert. Nach Abschluss aller Fälle: **Erfolgsquote**, **durchschnittliche Latenz**, **Gesamttokens** werden berechnet und an den Lauf angehängt.
  </Step>
</Steps>

### Wichtige Designentscheidungen

| Entscheidung                                | Grund                                                                                                                    |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Real ReActAgent** (kein Mock)             | Testet das tatsächliche Verhalten des Agenten, einschließlich Tool-Aufrufe und mehrstufiges Reasoning                    |
| **Separates Grader-LLM** (schnelles Modell) | Kostengünstig und schnell; das Agent-LLM hat bereits Token während der Ausführung verbraucht                             |
| **`asyncio.Semaphore(5)`**                  | Begrenzt die Parallelität auf 5, um zu vermeiden, dass der LLM-Anbieter mit Rate-Limit-Fehlern überlastet wird           |
| **Jeder Fall ist unabhängig**               | Keine Gesprächshistorie zwischen Fällen; jeder erhält eine neue Agent-Instanz                                            |
| **Ausführung im Hintergrund**               | Die Ausführung wird als asynchrone Aufgabe gestartet — die API gibt sofort zurück, das Frontend fragt alle 3 Sekunden ab |

## Arbeitsablauf

### 1. Datensatz erstellen

Navigieren Sie zu **Eval Center → Datasets** und klicken Sie auf **New Dataset**.

Ein Datensatz ist eine benannte Sammlung von Testfällen. Geben Sie ihm einen aussagekräftigen Namen (z. B. „Customer Support — Tier 1 Questions") und eine optionale Beschreibung.

### 2. Testfälle hinzufügen

Klicken Sie in Ihren Datensatz und fügen Sie Testfälle hinzu. Jeder Fall hat drei Felder:

| Feld                     | Erforderlich | Beschreibung                                                                                                         |
| ------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| **Prompt**               | Ja           | Die genaue Frage oder Anweisung, die an den Agenten gesendet wird                                                    |
| **Erwartetes Verhalten** | Ja           | Eine natürlichsprachige Beschreibung, wie eine korrekte Antwort aussieht                                             |
| **Assertions**           | Nein         | Eine Liste spezifischer Überprüfungen (z. B. „Antwort erwähnt die Rückgabepolitik", „Antwort ist unter 200 Wörtern") |

<Tip>
  **Gute Testfälle schreiben:**

  * **Prompt**: Seien Sie spezifisch. „Was ist unsere Rückgabepolitik für Enterprise-Pläne?" ist besser als „Erzählen Sie mir von Rückgaben."
  * **Erwartetes Verhalten**: Beschreiben Sie das *Ergebnis*, nicht die genaue Formulierung. „Erklärt das 30-Tage-Rückgabefenster und erwähnt die Ausnahme für Jahrespläne."
  * **Assertions**: Verwenden Sie diese für harte Anforderungen. Der Grader wird jede Assertion explizit überprüfen.
</Tip>

### 3. Starten Sie eine Bewertung

Gehen Sie zur Registerkarte **Eval Runs** und klicken Sie auf **New Evaluation**. Wählen Sie:

1. **Agent** — einen beliebigen Agent, den Sie besitzen
2. **Dataset** — einen beliebigen Datensatz mit mindestens einem Testfall

Klicken Sie auf **Start Evaluation**. Sie werden zur Ergebnisseite weitergeleitet.

### 4. Ergebnisse lesen

Die Ergebnisseite zeigt:

* **Header**: Name des Agenten, Name des Datensatzes, Statusabzeichen, Erfolgsquote, durchschnittliche Latenz, Gesamttoken
* **Fortschrittsbalken**: Füllt sich auf, wenn Fälle abgeschlossen werden (grün = Erfolgsanteil)
* **Ergebnistabelle**: Eine Zeile pro Testfall mit:
  * Eingabeaufforderung (gekürzt — zum Erweitern anklicken)
  * Urteil: **Bestanden** (grün), **Fehlgeschlagen** (rot) oder **Fehler** (orange)
  * Antwort des Agenten (gekürzt — zum Erweitern anklicken)
  * Begründung des Bewerters (warum es bestanden oder fehlgeschlagen ist)
  * Latenz (ms) und Token-Anzahl

<Warning>
  Während ein Durchlauf läuft (`pending` oder `running` Status), wird die Seite alle 3 Sekunden automatisch aktualisiert. Navigieren Sie nicht weg, wenn Sie Ergebnisse in Echtzeit sehen möchten.
</Warning>

## Was wird getestet

### Enthalten

* **Integrierte Werkzeuge**: calculator, web\_search, web\_fetch, python\_exec, file\_ops, etc.
* **Agent-Anweisungen**: Das Feld `extra_instructions` des Agenten wird weitergeleitet
* **Konfiguriertes Modell des Agenten**: Wenn der Agent eine benutzerdefinierte Modellkonfiguration hat, wird dieses Modell verwendet

### Nicht enthalten (absichtlich)

* **Konnektoren**: Externe HTTP-Konnektoren erfordern Live-Services von Drittanbietern — werden in der Evaluierung übersprungen, um instabile Tests zu vermeiden
* **MCP-Server**: Aus demselben Grund — externe Prozessabhängigkeiten
* **Gesprächsverlauf**: Jeder Fall läuft isoliert ohne vorherigen Kontext
* **Wissensdatenbanken**: KB-Abruefwerkzeuge werden im Evaluierungsmodus nicht geladen

<Info>
  Dies bedeutet, dass Evaluierungsergebnisse die **Reasoning- und Werkzeugnutzungsfähigkeit** des Agenten widerspiegeln, nicht seine Integration mit externen Services. Testen Sie Konnektoren separat über die Connector-Test-Funktion.
</Info>

## Der Grader

Der Grader ist ein LLM (das „schnelle" Modell des Systems), das vier Informationen erhält und ein strukturiertes JSON-Urteil zurückgibt:

**Systemaufforderung:**

> You are an impartial AI evaluator. Your job is to judge whether an AI agent's answer meets the expected behavior for a given prompt.
>
> Be strict but fair. A "pass" requires the answer to genuinely address the prompt according to the expected behavior. A "fail" means the answer is wrong, incomplete, off-topic, or misses key requirements.

**Benutzernachricht enthält:**

1. Die ursprüngliche Aufforderung
2. Das erwartete Verhalten
3. Die Liste der Assertions (oder „None specified")
4. Die tatsächliche Antwort des Agenten

**Ausgabeschema:**

```json theme={null}
{
  "verdict": "pass" | "fail",
  "reasoning": "Explanation of why the answer passes or fails..."
}
```

Der Grader verwendet `structured_llm_call` mit Function Calling, um das Schema durchzusetzen. Wenn der Grader selbst fehlschlägt (Netzwerkfehler, fehlerhafte Antwort), wird der Fall als `error` gekennzeichnet.

## Best Practices

### Datensatz-Design

* **Klein anfangen**: 5–10 Fälle, die die Kernfunktionen des Agenten abdecken
* **Edge Cases berücksichtigen**: Mindestens 2–3 adversarische oder außerhalb des Geltungsbereichs liegende Prompts einbeziehen
* **Spezifisch bei erwartetem Verhalten**: Vage Erwartungen führen zu inkonsistenter Bewertung
* **Assertions für harte Anforderungen verwenden**: „Muss den Preis erwähnen" ist zuverlässiger als zu hoffen, dass der Bewerter es erfasst

### Ergebnisse interpretieren

* **80%+ Erfolgsquote** ist ein guter Richtwert für einen gut konfigurierten Agenten
* **Niedrige Erfolgsquote mit hoher Latenz** deutet darauf hin, dass der Agent Schwierigkeiten mit mehrstufigem Reasoning hat
* **Fehlerstatus** bedeutet, dass der Agent oder die Bewertung abgestürzt ist — überprüfen Sie die Server-Logs auf Details
* **Bewertungsabweichungen**: Wenn Sie denken, dass die Bewertung falsch ist, lesen Sie deren Begründung. Möglicherweise müssen Sie Ihre Beschreibung des erwarteten Verhaltens verfeinern

### Wann neu bewerten

* Nach Änderung der Agent-Anweisungen
* Nach Wechsel des LLM-Modells des Agenten
* Nach Hinzufügen oder Entfernen von Tool-Kategorien
* Vor jeder Produktionsbereitstellung (CI/CD-Integration kommt in einer zukünftigen Version)