Suite d'évaluation

Remarque : Vous définissez vous-même les dimensions de notation. Votre évaluateur peut retourner les clés numériques de son choix ; Observability stocke, suit les tendances et affiche tout ce que vous renvoyez.

​

En bref

1. Écrivez un évaluateur. Déployez un petit service HTTP qui lit la transcription d’une session et retourne des scores. Observability inclut une référence fonctionnelle que vous pouvez copier. Voir Écrire un évaluateur avec le SDK.
2. Pointez Observability vers ce service. Définissez EVALUATOR_ENDPOINT (et un EVALUATOR_TOKEN partagé) sur le processus serveur.
3. Regardez les scores arriver. Chaque session terminée est notée automatiquement ; les résultats apparaissent sur la page de détail de la session, la grille des sessions et les tableaux de bord sauvegardés.

​

Fonctionnement

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

​

Contrat HTTP

• Serveur Observability : variable d’environnement EVALUATOR_TOKEN
• Service d’évaluation : configuré de la même façon (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": { ... } },
    ...
  ]
}

​

Formats 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

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

​

Exécuter votre évaluateur

​

Configurer le serveur

​

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 plus 0.3 (sans 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

​

Consultation des résultats

• /sessions/<id> : chronologie des événements + un rail droit affichant les scores de la session et toute erreur de la tentative de dispatch. Si votre clé possè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 actualiser les scores après le déploiement d’un nouvel évaluateur. Le tableau de bord interroge le nouveau résultat et met à jour le rail droit à son arrivée.
• /sessions : grille de sessions filtrables ; la colonne de score montre le statut d’évaluation et les scores de chaque session en un coup d’œil.
• /dashboards : vues de santé d’évaluation sauvegardées (voir Tableaux de bord ci-dessous).

​

Tableaux de bord

• Des 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 s’il faut réduire à la dernière évaluation par session.

​

Résolution des problèmes

​

Prochaines étapes

• Compétence d’agent évaluateur : demandez à un agent de codage de concevoir vos dimensions à partir de sessions réelles et de créer ce service pour vous.
• SDK Python : émettez les événements agent_end qui déclenchent la notation.
• Clés API : les permissions evaluations:read et evaluations:trigger.
• Audits : l’autre fonctionnalité de contrôle qualité automatisé d’Observability, pour la revue basée sur des politiques.