Evaluation Suite

1. Wie der Abschluss einer Session erkannt wird.
2. Den HTTP-Vertrag, den der Evaluator implementieren muss.
3. Die Konfiguration des AgentEye-Servers.
4. Die Anzeige von Ergebnissen.
5. Fehlerbehebung.

​

Funktionsweise

ingest /events  ──▶  AgentEye  ──── POST /evaluate ────▶  Evaluator-Service
   (agent_end)        Server   ◀──── done | pending ────
                          │
                          │     GET /evaluate/{job_id} ─────▶
                          │     ◀──── done ──────────────
                          ▼
                     evaluations  (terminale Ergebnisse)

• Das Ergebnis direkt zurückgibt mit {"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}. Das Ergebnis wird an die Evaluierungszeitachse der Session angehängt. reasoning und summary sind optional.
• Verschiebt mit {"status":"pending", "job_id":"abc-123"}. AgentEye ruft dann GET {EVALUATOR_ENDPOINT}/evaluate/abc-123 ab, bis der Evaluator {"status":"done", ...} oder {"status":"error", "error":"..."} zurückgibt. Das Polling-Intervall ist pro Job konfigurierbar: Eine pending-Antwort kann next_poll_secs enthalten, um es zu überschreiben; andernfalls verwendet AgentEye den Wert default_poll_interval_secs aus GET /config; andernfalls fällt der Server auf EVALUATOR_POLLING_INTERVAL_SECS zurück (Standard: 10 s). Alle Werte werden auf [1 s, 1 h] begrenzt.

​

HTTP-Vertrag

• AgentEye-Server: Umgebungsvariable EVALUATOR_TOKEN
• Evaluator-Service: identisch konfiguriert (das agenteye-evaluator-SDK liest EVALUATOR_TOKEN per Konvention)

​

Routen, die der Evaluator bereitstellen muss

​

EvalRequest-Body, der vom Server gesendet wird

{
  "schema_version": "1",
  "session_id":     "session-abc123",
  "agent_id":       "planner",
  "environment":    "production",
  "started_at":     "2026-05-10T12:00:00Z",
  "ended_at":       "2026-05-10T12:05:00Z",
  "events": [
    { "id": 1234, "ts": "...", "event_type": "agent_start", "payload": { ... } },
    ...
  ]
}

​

Antwortstrukturen

{
  "status": "done",
  "scores": { "helpfulness": 0.85, "tool_efficiency": 0.6 },
  "reasoning": {
    "helpfulness": "answered the question directly with citations",
    "tool_efficiency": "called list_files three times when one would have done"
  },
  "summary": "strong answer quality, weak tool selection"
}

{ "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 }

{ "status": "error", "error": "model service unavailable" }

​

Einen Evaluator mit dem SDK schreiben

pip install agenteye-evaluator

import os
from agenteye_evaluator import Evaluator, EvalRequest, EvalResponse

app = Evaluator(token=os.environ["EVALUATOR_TOKEN"])

@app.evaluator
def run(req: EvalRequest) -> EvalResponse:
    # Inspect req.events (the full session transcript) and return scores.
    tool_calls = sum(1 for e in req.events if e.event_type == "tool_use")
    return EvalResponse(
        scores={"tool_calls": float(tool_calls)},
        reasoning={"tool_calls": f"{tool_calls} tool invocations in the transcript"},
        summary="tight tool loop" if tool_calls < 5 else "agent looped on tools",
    )

​

Einen Evaluator auf Kubernetes betreiben

​

1. Evaluator containerisieren

FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir agenteye-evaluator uvicorn
COPY my_evaluator.py .
RUN useradd --uid 10001 --create-home --shell /usr/sbin/nologin evaluator \
    && chown -R evaluator:evaluator /app
USER evaluator
EXPOSE 9000
CMD ["uvicorn", "my_evaluator:app", "--host", "0.0.0.0", "--port", "9000"]

​

2. Gemeinsamen Bearer-Token erstellen

kubectl -n agenteye create secret generic evaluator-token \
  --from-literal=token="$(openssl rand -hex 32)"

​

3. Beispiel-Manifeste anwenden

# Passen Sie zunächst deploy/examples/evaluator/deployment.yaml an,
# um `image:` auf Ihre Registry zu verweisen, dann:
kubectl apply -k deploy/examples/evaluator/

• Ein 2-Replikat-Deployment mit runAsNonRoot, schreibgeschütztem Root-Dateisystem, entfernten Capabilities sowie Liveness- und Readiness-Prüfungen auf /health
• Einen ClusterIP-Service auf Port 9000
• Eine secret.example.yaml-Vorlage (absichtlich aus der Kustomization ausgeschlossen; erstellen Sie das echte Secret außerhalb des Build-Prozesses, damit kein Token in Git landet)

​

4. AgentEye damit verbinden

EVALUATOR_ENDPOINT=http://evaluator:9000
EVALUATOR_TOKEN=<der oben generierte Wert>

​

Überprüfung

kubectl -n agenteye port-forward svc/evaluator 9000:9000
curl -s http://localhost:9000/health   # → {"status":"ok"}

​

AgentEye-Server konfigurieren

​

API-Referenz

​

Nach Score-Bereich filtern: score_filters

# helpfulness in [0.5, 0.8]
GET /evaluations?score_filters=helpfulness:0.5..0.8

# tool_efficiency höchstens 0.3 (keine Untergrenze)
GET /evaluations?score_filters=tool_efficiency:..0.3

# helpfulness >= 0.5 UND factuality >= 0.9
GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9..

​

Berechtigungen

​

Ergebnisse anzeigen

• /sessions/<id>: Ereignis-Zeitachse und eine rechte Seitenleiste mit den Scores der Session sowie etwaigen Fehlern aus dem Dispatch-Versuch. Wenn Ihr Schlüssel evaluations:trigger hat, erscheint neben der Export-Schaltfläche eine Neu bewerten-Schaltfläche — nützlich für Sessions, die nie agent_end ausgegeben haben, oder zum Aktualisieren von Scores nach dem Deployment eines neuen Evaluators. Das Dashboard fragt nach dem neuen Ergebnis und aktualisiert die rechte Seitenleiste, sobald es vorliegt.
• /sessions: Filterbares Sessions-Raster; die Score-Spalte zeigt den Evaluierungsstatus und die Scores jeder Session auf einen Blick.
• /dashboards: Gespeicherte Eval-Gesundheitsansichten (siehe Dashboards unten).

​

Dashboards

• Filter: dieselben Steuerelemente wie auf der Sessions-Seite: Umgebung, Status, Agent, ein rollierendes Zeitfenster und Score-Bereichsfilter (key:min..max).
• Eine Anzeigekonfiguration: welche Score-Schlüssel hervorgehoben werden sollen, die grünen/gelben/roten Gesundheitsschwellenwerte, welche Panels angezeigt werden und ob auf die neueste Evaluierung pro Session reduziert werden soll.

​

Fehlerbehebung