Suite d'évaluation

1. Comment la fin de session est détectée.
2. Le contrat HTTP que l’évaluateur doit implémenter.
3. La configuration du serveur AgentEye.
4. La consultation des résultats.
5. Le dépannage.

​

Fonctionnement

ingest /events  ──▶  AgentEye  ──── POST /evaluate ────▶  Service évaluateur
   (agent_end)        server   ◀──── done | pending ────
                          │
                          │     GET /evaluate/{job_id} ─────▶
                          │     ◀──── done ──────────────
                          ▼
                     evaluations  (résultats terminaux)

• Retourner le résultat directement avec {"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}. Le résultat est ajouté à la chronologie d’évaluation de la session. reasoning et summary sont facultatifs.
• Différer avec {"status":"pending", "job_id":"abc-123"}. AgentEye appelle alors GET {EVALUATOR_ENDPOINT}/evaluate/abc-123 jusqu’à ce que votre évaluateur retourne {"status":"done", ...} ou {"status":"error", "error":"..."}. La cadence d’interrogation est définie par tâche : une réponse pending peut inclure next_poll_secs pour la remplacer ; sinon AgentEye utilise la valeur default_poll_interval_secs de GET /config ; à défaut, le serveur revient à EVALUATOR_POLLING_INTERVAL_SECS (par défaut 10 s). Toutes les valeurs sont limitées à [1 s, 1 h].

​

Contrat HTTP

• Serveur AgentEye : variable d’environnement EVALUATOR_TOKEN
• Service d’évaluation : configuré de la même manière (le SDK agenteye-evaluator lit EVALUATOR_TOKEN par convention)

​

Routes que l’évaluateur doit exposer

​

Corps EvalRequest envoyé par le serveur

{
  "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": { ... } },
    ...
  ]
}

​

Formes de réponse

{
  "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" }

​

Écrire un évaluateur avec le SDK

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:
    # Inspectez req.events (la transcription complète de la session) et retournez des 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",
    )

​

Déployer un évaluateur sur Kubernetes

​

1. Conteneuriser votre évaluateur

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. Créer le jeton Bearer partagé

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

​

3. Appliquer les manifestes d’exemple

# Éditez d'abord deploy/examples/evaluator/deployment.yaml pour pointer
# `image:` vers votre registre, puis :
kubectl apply -k deploy/examples/evaluator/

• Un Deployment à 2 répliques avec runAsNonRoot, système de fichiers racine en lecture seule, toutes les capacités supprimées, liveness + readiness sur /health
• Un Service ClusterIP sur le port 9000
• Un modèle secret.example.yaml (intentionnellement exclu de la Kustomization ; créez le vrai secret hors bande afin qu’aucun jeton ne se retrouve dans git)

​

4. Connecter AgentEye au service

EVALUATOR_ENDPOINT=http://evaluator:9000
EVALUATOR_TOKEN=<la valeur générée ci-dessus>

​

Vérification

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

​

Configurer le serveur AgentEye

​

Référence API

​

Filtrage par plage de score : score_filters

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

# tool_efficiency au maximum 0.3 (pas de borne inférieure)
GET /evaluations?score_filters=tool_efficiency:..0.3

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

​

Permissions

​

Consulter les résultats

• /sessions/<id> : chronologie des événements + un panneau latéral droit affichant les scores de la session et toute erreur issue de la tentative de distribution. Si votre clé dispose de evaluations:trigger, un bouton re-evaluate apparaît à côté du bouton d’export, utile pour les sessions qui n’ont jamais émis agent_end, ou pour rafraîchir les scores après le déploiement d’un nouvel évaluateur. Le tableau de bord interroge le nouveau résultat et met à jour le panneau latéral droit lorsqu’il est disponible.
• /sessions : grille de sessions filtrable ; la colonne de score affiche le statut d’évaluation et les scores de chaque session en un coup d’œil.
• /dashboards : vues de santé d’évaluation sauvegardées (voir Dashboards ci-dessous).

​

Dashboards

• Les filtres : les mêmes contrôles que la page des sessions : environnement, statut, agent, une fenêtre temporelle glissante et des filtres de plage de score (key:min..max).
• Une configuration d’affichage : quelles clés de score mettre en avant, les seuils de santé vert/orange/rouge, quels panneaux afficher et si l’on doit réduire à la dernière évaluation par session.

​

Dépannage