failproofai 1.0.1-beta.1 → 1.0.2-beta.0

package/.next/standalone/docs-old/fr/agenteye/evaluation-suite.mdx

@@ -0,0 +1,401 @@
+---
+title: "Suite d'évaluation"
+description: "Failproof AI Observability peut noter automatiquement chaque exécution d'agent terminée pour en évaluer la qualité : vous fournissez un petit service de notation, et Observability s'occupe du reste."
+---
+
+
+Failproof AI Observability peut noter automatiquement chaque exécution d'agent terminée pour en évaluer la qualité : vous fournissez un petit service de notation, et Observability s'occupe du reste. Utilisez-le pour suivre les dimensions qui vous importent (utilité, efficacité des outils, factualité, sécurité — vous choisissez), détecter les régressions tôt et comparer des agents ou des environnements en un coup d'œil. La notation est optionnelle : le pipeline ne fait rien tant que vous n'avez pas défini `EVALUATOR_ENDPOINT` sur le serveur.
+
+> **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](#writing-an-evaluator-with-the-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.
+
+![Vue de détail d'une session avec le résumé de l'évaluation, les barres de score par dimension et le texte de justification dans le rail droit](/agenteye/images/session-detail.png)
+
+*Une fois un évaluateur configuré, chaque exécution terminée est notée et les résultats apparaissent dans le rail droit de la session : le résumé en haut, puis les barres de score par dimension avec leur justification.*
+
+---
+
+## Fonctionnement
+
+```mermaid
+flowchart LR
+    ING["ingest /events<br/>agent_end"] --> SRV["Observability server"]
+    SRV -->|"POST /evaluate"| EV["Evaluator service"]
+    EV -->|"done or pending"| SRV
+    SRV -->|"poll GET /evaluate/{job_id}"| EV
+    EV -->|"done"| SRV
+    SRV --> RES["evaluations<br/>terminal results"]
+```
+
+Lorsque le SDK Observability émet un événement `agent_end` pour une session, le serveur
+planifie une évaluation. Il envoie ensuite en POST la transcription complète des événements à votre
+service d'évaluation, qui peut alors :
+
+- **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].
+
+Les sessions qui n'émettent jamais `agent_end` (par exemple, un processus d'agent planté)
+peuvent également être traitées : le `GET /config` de l'évaluateur peut retourner
+`{"inactivity_timeout_secs": 1800}`, et Observability évaluera toute session
+restée inactive pendant ce délai. Définissez le champ à `null` ou omettez-le pour
+désactiver ce comportement de secours.
+
+Le pipeline est entièrement sans effet lorsque `EVALUATOR_ENDPOINT` n'est pas défini.
+
+Une session peut accumuler **plusieurs évaluations terminales dans le temps** : chaque
+événement `agent_end` (et chaque réévaluation manuelle depuis le tableau de bord) ajoute
+une nouvelle ligne d'évaluation. C'est la méthode recommandée pour évaluer une conversation
+reprise : un utilisateur termine un agent, revient plus tard, envoie de nouveaux événements,
+termine à nouveau l'agent, et une seconde évaluation s'exécute sur la transcription complète mise à jour.
+Le tableau de bord affiche l'évaluation la plus récente comme titre principal et les évaluations
+précédentes sous forme de chronologie rétractable. Pendant qu'une évaluation est en cours pour
+une session, les événements `agent_end` supplémentaires pour cette session sont ignorés ; le
+suivant, une fois l'évaluation en cours terminée, mettra en file d'attente une nouvelle évaluation
+comme d'habitude.
+
+Le mécanisme de secours par inactivité se réengage également sur les sessions reprises : si
+de nouveaux événements arrivent après une évaluation terminale précédente et que la session
+reste ensuite inactive au-delà de `inactivity_timeout_secs`, une nouvelle évaluation est mise
+en file d'attente.
+
+Les échecs transitoires (5xx, 429, délais d'expiration, erreurs réseau) font l'objet de nouvelles
+tentatives avec backoff exponentiel jusqu'à `EVALUATOR_MAX_ATTEMPTS` ; les réponses 4xx sont
+terminales. Observability fonctionne en toute sécurité avec plusieurs instances de serveur à
+échelle horizontale ; le travail est partitionné de sorte qu'une même session ne soit jamais
+traitée deux fois simultanément.
+
+---
+
+## Contrat HTTP
+
+Toutes les routes authentifiées utilisent **l'authentification par jeton bearer**. La même valeur doit être
+configurée des deux côtés :
+
+- 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)
+
+Si `EVALUATOR_TOKEN` n'est pas défini, le serveur n'envoie pas d'en-tête `Authorization` ; l'évaluateur
+peut alors accepter des requêtes anonymes, ce qui convient à un réseau purement interne
+mais est déconseillé sur l'internet public.
+
+### Routes que l'évaluateur doit exposer
+
+| Route | Corps / paramètres | Réponse |
+|---|---|---|
+| `GET /health` | aucun | `{"status":"ok"}` (ouvert, sans authentification) |
+| `GET /config` | aucun | `{"inactivity_timeout_secs": <int> \| null, "default_poll_interval_secs": <int> \| omitted}` |
+| `POST /evaluate` | JSON `EvalRequest` | `{"status":"done", ...}` ou `{"status":"pending", "job_id":"..."}` |
+| `GET /evaluate/{id}` | aucun | même format de réponse que `/evaluate` |
+
+### Corps `EvalRequest` envoyé par le serveur
+
+```json
+{
+  "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
+
+**Synchrone (done) :**
+
+```json
+{
+  "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"
+}
+```
+
+`reasoning` (une map de justification par score) et `summary` (un récit global
+en un paragraphe) sont tous deux optionnels. Les clés de `reasoning` doivent
+correspondre aux clés de `scores` ; le tableau de bord affiche chaque entrée en ligne sous
+sa barre de score. Les anciens évaluateurs qui ne retournent que `scores` continuent de
+fonctionner sans modification ; `reasoning` et `summary` sont simplement lus comme null et
+les affordances d'interface correspondantes sont omises.
+
+**Asynchrone (différé) :**
+
+```json
+{ "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 }
+```
+
+`next_poll_secs` est optionnel ; s'il est omis, le serveur se rabat sur le
+`default_poll_interval_secs` de l'évaluateur depuis `/config`, puis sur sa propre
+variable d'environnement `EVALUATOR_POLLING_INTERVAL_SECS`.
+
+**Erreur terminale côté évaluateur :**
+
+```json
+{ "status": "error", "error": "model service unavailable" }
+```
+
+Le serveur traite tout autre corps 2xx comme une erreur de protocole et enregistre une
+`error` terminale pour la session.
+
+---
+
+## Écrire un évaluateur avec le SDK
+
+Vous n'avez pas à implémenter le contrat HTTP manuellement. Le package Python
+`agenteye-evaluator` vous fournit un wrapper FastAPI typé qui gère l'authentification,
+le routage et les formats requête/réponse à votre place.
+
+Failproof AI Observability inclut également un **évaluateur de référence fonctionnel** qui
+note `helpfulness`, `tool_efficiency` et `factuality` à partir de la forme de la transcription.
+Copiez-le comme point de départ et remplacez-y votre propre logique : un juge LLM, un moteur de règles,
+ou tout ce qui correspond à vos critères de qualité.
+
+Évaluateur minimal :
+
+```python
+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",
+    )
+```
+
+L'instance `app` s'exécute sous n'importe quel serveur ASGI, donc `uvicorn module:app` suffit à la démarrer.
+
+Pour les évaluateurs qui ont besoin de différer un traitement coûteux, retournez `JobPending`
+à la place et enregistrez un handler `@app.job_lookup` ; le serveur Observability interroge
+`GET /evaluate/{job_id}` jusqu'à ce que vous retourniez un statut terminal ou que le plafond
+`EVALUATOR_MAX_POLL_DURATION_SECS` (défaut : 1 h) soit atteint.
+
+La référence complète de l'API, le pattern asynchrone et le schéma des événements sont documentés dans
+le README du SDK `agenteye-evaluator`.
+
+---
+
+## Exécuter votre évaluateur
+
+L'évaluateur est **votre service** — Failproof AI Observability ne fournit pas d'évaluateur
+par défaut, vous devez donc le créer et l'exécuter là où vous déployez vos propres services.
+Il s'exécute sous n'importe quel serveur ASGI (par exemple `uvicorn my_evaluator:app`) ; exposez
+les routes `/health`, `/config` et `/evaluate` du
+[contrat HTTP](#http-contract), puis pointez le serveur vers ce service (voir
+[Configurer le serveur](#configuring-the-server)).
+
+Une fois l'évaluateur accessible, `GET /health` retourne `{"status":"ok"}`. Après
+l'exécution complète d'un agent, `GET /evaluations` sur le serveur retourne une ligne avec
+`status: "done"` et les scores produits par votre évaluateur.
+
+---
+
+## Configurer le serveur
+
+À définir sur le processus serveur :
+
+| Variable d'env. | Signification |
+|---|---|
+| `EVALUATOR_ENDPOINT` | URL de base de votre évaluateur (`http://evaluator:9000`). Non défini = pipeline désactivé. |
+| `EVALUATOR_TOKEN` | Jeton bearer. Doit correspondre à la valeur configurée sur le service d'évaluation. |
+| `EVALUATOR_WORKERS` | Tâches de travail par instance de serveur (défaut : 2). |
+| `EVALUATOR_CLAIM_BATCH` | Lignes réclamées par tick de travail (défaut : 4). Les lots sont traités **en parallèle** ; la concurrence effective sur votre endpoint d'évaluation est `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. |
+| `EVALUATOR_POLL_IDLE_SECS` | Durée de veille d'un worker entre les tentatives de dispatch lorsqu'aucune évaluation n'est due (défaut : 2 s). |
+| `EVALUATOR_POLLING_INTERVAL_SECS` | Dernier recours pour la cadence de `GET /evaluate/{id}` lorsque ni `next_poll_secs` par réponse ni `default_poll_interval_secs` de l'évaluateur ne sont définis (défaut : 10 s). |
+| `EVALUATOR_REQUEST_TIMEOUT_MS` | Délai d'expiration par requête (défaut : 30000). |
+| `EVALUATOR_MAX_ATTEMPTS` | Après ce nombre d'échecs transitoires, le résultat est enregistré comme `error` terminal (défaut : 5). |
+| `EVALUATOR_CONFIG_REFRESH_SECS` | Cadence de `GET /config` (défaut : 300). |
+| `EVALUATOR_MAX_POLL_DURATION_SECS` | Durée maximale en temps réel pendant laquelle une session peut rester dans la file de polling avant d'être terminée en `timeout` (défaut : 3600 s). Protège contre un évaluateur qui retourne indéfiniment `pending`. |
+
+Pour activer la notation automatique, définissez `EVALUATOR_ENDPOINT` et
+`EVALUATOR_TOKEN` sur le serveur, puis redémarrez-le pour prendre en compte les modifications. Avec
+`EVALUATOR_ENDPOINT` non défini, le pipeline reste sans effet.
+
+Les paramètres de réglage ci-dessus sont optionnels ; définissez les variables d'environnement
+correspondantes sur le serveur uniquement si vous avez besoin de remplacer les valeurs par défaut.
+
+---
+
+## Référence API
+
+| Méthode | Chemin | Permission requise | Objectif |
+|---|---|---|---|
+| `GET` | `/evaluations` | `evaluations:read` | Interroger les résultats terminaux. Supporte `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` vaut 50 par défaut et est plafonné à 200 (contrairement à `/events`, plafonné à 1000). `environment` accepte une liste séparée par des virgules (ex. `environment=prod,staging`) ; les valeurs uniques fonctionnent toujours. Avec `latest_per_session=true`, la réponse contient au plus une ligne par `session_id` (la plus récente par `completed_at`), utilisée par la page de liste des sessions pour réduire la chronologie d'évaluation d'une session à son titre actuel. Vaut false par défaut (retourne l'historique complet). |
+| `GET` | `/evaluations/aggregate` | `evaluations:read` | Bilan de santé d'évaluation agrégé pour une tranche filtrée : nombre total, répartition done/error/timeout, statistiques par clé de score (count/avg/min/max/p50 sur les clés `scores` arbitraires) et chronologie par tranches de temps. Accepte les **mêmes paramètres de filtre que `/evaluations`** plus `featured_keys` (CSV de clés de score à suivre) et `latest_per_session`. Alimente la fonctionnalité Tableaux de bord ; les métriques sont exactes sur l'ensemble correspondant, sans échantillonnage. |
+| `GET` | `/evaluations/environments` | `evaluations:read` | Valeurs d'environnement distinctes de la table `evaluations`. Utilisé pour alimenter les menus déroulants de filtre limités aux données accessibles en lecture d'évaluation. |
+| `GET` | `/evaluation-jobs` | `evaluations:read` | Visibilité sur les évaluations en cours. Filtrage par `status` (`pending`/`polling`). |
+| `GET` | `/events` | `events:read` | Diffuser les événements bruts d'une session. Supporte `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` et `order`. `order` vaut `desc` (plus récent en premier, par défaut) ou `asc` (plus ancien en premier) ; une valeur non reconnue se rabat sur `desc`. Pagination par curseur via le `next_cursor` de la réponse (un identifiant d'événement) : passez-le en tant que `cursor` pour obtenir la page suivante ; avec `asc` la page suivante correspond aux événements après cet identifiant, avec `desc` aux événements avant. `limit` vaut 50 par défaut et est plafonné à 1000. |
+| `GET` | `/sessions/:session_id/export` | `events:read` | Retourne le corps JSON exact que l'évaluateur recevrait pour cette session, servi comme pièce jointe téléchargeable nommée `session-<id>.json`. Utile pour rejouer des sessions de production via `agenteye-evaluator` pour des tests hors ligne. Les octets sont identiques à ceux envoyés par le pipeline d'évaluation. |
+| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Met en file d'attente une nouvelle évaluation pour une session ; s'exécute qu'une évaluation précédente existe ou non. Le nouveau résultat est **ajouté** à la chronologie d'évaluation de la session plutôt que d'écraser le précédent, de sorte que les scores antérieurs restent visibles en historique. Retourne `202` lors de la mise en file d'attente, `404` pour une session inconnue, `409` si une évaluation est déjà en cours. À utiliser après le déploiement d'un nouvel évaluateur, ou pour des sessions qui n'ont jamais émis `agent_end`. |
+
+### Filtrage par plage de score : `score_filters`
+
+`GET /evaluations` accepte un paramètre optionnel `score_filters` qui
+restreint les résultats par valeurs numériques dans l'objet `scores`. Le
+paramètre est une liste séparée par des virgules d'entrées `key:min..max` ; chaque
+borne peut être omise. Plusieurs entrées se combinent avec un ET logique. Les lignes
+où la clé nommée est absente ou non numérique sont exclues. Une requête peut
+contenir au maximum 20 entrées de filtre ; au-delà, HTTP 400 est retourné.
+
+Exemples :
+```text
+# 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..
+```
+
+Chaque objet de réponse `/evaluations` possède ces champs :
+
+| Champ | Type | Notes |
+|---|---|---|
+| `evaluation_id` | string (UUID) | L'identifiant canonique de cette évaluation terminale. Chaque évaluation terminale reçoit un nouvel UUID ; une seule session peut en contenir plusieurs. |
+| `id` | string (UUID) | Alias de compatibilité ascendante portant la même valeur que `evaluation_id`. |
+| `session_id` | string | La session contre laquelle cette évaluation a été exécutée. Une session peut avoir plusieurs évaluations dans sa chronologie. |
+| `agent_id` | string | Identifie l'agent qui a produit la session. |
+| `environment` | string | Libellé d'environnement copié depuis la session. |
+| `status` | enum | L'une des valeurs `"done"`, `"error"`, `"timeout"`. |
+| `scores` | object \| null | Scores retournés par votre évaluateur. |
+| `reasoning` | object \| null | Map de justification optionnelle par score retournée par votre évaluateur. Les clés correspondent généralement à celles de `scores`. Le tableau de bord affiche chaque entrée sous sa barre de score. |
+| `summary` | string \| null | Récit global optionnel en un paragraphe retourné par votre évaluateur. Le tableau de bord l'affiche au-dessus de la répartition par score comme titre de l'évaluation. |
+| `error` | string \| null | Renseigné uniquement pour `"error"` / `"timeout"`. |
+| `attempt_count` | integer | Nombre de tentatives de dispatch (≥ 1). |
+| `duration_ms` | integer \| null | Durée de la dernière tentative. |
+| `completed_at` | string (ISO 8601 UTC) | Moment où le résultat terminal a été enregistré. Les résultats sont ordonnés par `completed_at` (plus récent en premier). |
+| `created_at` | string (ISO 8601 UTC) | Porte le même horodatage que `completed_at` (sémantique d'écriture unique). |
+
+---
+
+## Permissions
+
+| Permission | Accorde |
+|---|---|
+| `evaluations:read` | Lister les résultats d'évaluation, afficher les scores dans le tableau de bord et charger les métriques de santé du tableau de bord. |
+| `evaluations:trigger` | Mettre manuellement en file d'attente une évaluation pour une session via `POST /sessions/:session_id/re-evaluate` ou le bouton de réévaluation du tableau de bord. |
+| `dashboards:read` | Consulter les tableaux de bord sauvegardés (nécessite également `evaluations:read` pour charger leurs métriques). |
+| `dashboards:write` | Créer et modifier des tableaux de bord. |
+| `dashboards:delete` | Supprimer des tableaux de bord. |
+
+L'administrateur bootstrap (`ADMIN_KEY`, `ADMIN_EMAIL`) reçoit automatiquement toutes ces 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](#dashboards) ci-dessous).
+
+![La grille Sessions avec des pastilles de statut d'évaluation par session et des badges de score colorés (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png)
+
+*La grille des sessions affiche le statut d'évaluation et les scores de chaque exécution en un coup d'œil ; les badges rouge/orange/vert font ressortir les scores faibles.*
+
+---
+
+## Tableaux de bord
+
+La page **Tableaux de bord** (`/dashboards`) vous permet de sauvegarder une combinaison de filtres
+d'évaluation sous forme de vue nommée et réutilisable, et de surveiller la santé de cette tranche
+d'évaluations en un coup d'œil. Les tableaux de bord sont **partagés au sein de toute votre organisation** ;
+toute personne disposant de `dashboards:read` voit le même ensemble.
+
+Chaque tableau de bord épingle :
+
+- **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.
+
+Chaque carte affiche le nombre de sessions correspondantes, une répartition done/error/timeout,
+la moyenne de chaque score mis en avant et une petite sparkline de tendance. Ouvrir un tableau de bord
+affiche les panneaux en plein écran ; **« ouvrir dans les sessions »** vous conduit vers la
+page des sessions pré-filtrée sur exactement cette tranche. Les métriques sont calculées
+côté serveur sur l'ensemble correspondant (via `GET /evaluations/aggregate`), les chiffres sont donc
+exacts plutôt qu'échantillonnés.
+
+![Un tableau de bord de santé d'évaluation avec des barres de score moyen par dimension d'évaluateur, une répartition outil ok/erreur, les meilleurs outils et une tendance d'événements par heure](/agenteye/images/dashboard-quality.png)
+
+**Permissions :** la consultation nécessite à la fois `dashboards:read` et `evaluations:read` ;
+la création et la modification nécessitent `dashboards:write` ; la suppression nécessite `dashboards:delete`.
+L'administrateur bootstrap reçoit toutes ces permissions automatiquement.
+
+---
+
+## Résolution des problèmes
+
+**Des sessions existent mais aucune évaluation n'est créée.** Vérifiez que `EVALUATOR_ENDPOINT`
+est défini sur le processus serveur, que le serveur et l'évaluateur partagent la même valeur
+`EVALUATOR_TOKEN` et que l'endpoint `/health` de l'évaluateur est accessible depuis le serveur.
+Sans `EVALUATOR_ENDPOINT` défini, le pipeline est sans effet.
+
+**Les évaluations en cours s'accumulent.** Interrogez `GET /evaluation-jobs` pour voir la file
+en cours. Inspectez `attempt_count`, `next_attempt_at` et `last_error` sur chaque ligne.
+Causes courantes : service d'évaluation inaccessible ou retournant des erreurs 5xx (réessayées avec backoff),
+`EVALUATOR_TOKEN` incorrect (401 est terminal), ou un évaluateur asynchrone qui retourne `pending`
+indéfiniment (voir ci-dessous).
+
+**Des sessions sont terminées mais sans évaluation terminale.** Interrogez
+`GET /evaluation-jobs?status=polling` ; le résultat est peut-être encore en cours.
+Si une tâche est bloquée en `pending`, le serveur a du mal à joindre l'évaluateur ;
+vérifiez que l'évaluateur est opérationnel et que `EVALUATOR_TOKEN` correspond.
+
+**`HTTP 401 from evaluator: invalid bearer token`.** Le `EVALUATOR_TOKEN`
+sur le serveur ne correspond pas à la valeur configurée sur le service d'évaluation.
+Ils doivent être identiques.
+
+**L'évaluateur asynchrone retourne `pending` indéfiniment.** Le serveur interroge
+`GET /evaluate/{job_id}` jusqu'à ce que l'évaluateur retourne `done` ou `error`, ou
+jusqu'à ce que le plafond `EVALUATOR_MAX_POLL_DURATION_SECS` (défaut : 1 h) soit atteint.
+Passé ce délai, l'évaluation est enregistrée comme `timeout` et retirée de la file en cours.
+Augmentez `EVALUATOR_MAX_POLL_DURATION_SECS` si votre évaluateur a légitimement besoin
+de plus de temps que la valeur par défaut.
+
+---
+
+## Prochaines étapes
+
+- [Compétence d'agent évaluateur](/fr/agenteye/evaluator-skill) : demandez à un agent de codage de concevoir vos dimensions à partir de sessions réelles et de créer ce service pour vous.
+- [SDK Python](/fr/agenteye/python-sdk) : émettez les événements `agent_end` qui déclenchent la notation.
+- [Clés API](/fr/agenteye/api-keys) : les permissions `evaluations:read` et `evaluations:trigger`.
+- [Audits](/fr/agenteye/audits) : l'autre fonctionnalité de contrôle qualité automatisé d'Observability, pour la revue basée sur des politiques.

package/.next/standalone/docs-old/fr/agenteye/evaluations.mdx

@@ -0,0 +1,50 @@
+---
+title: "Évaluations"
+description: "Les problèmes de qualité viennent à vous, au lieu d'en entendre parler dans une réclamation utilisateur."
+---
+
+Les problèmes de qualité viennent à vous, au lieu d'en entendre parler dans une réclamation utilisateur. Connectez votre propre service de scoring une seule fois et Failproof AI Observability note chaque exécution terminée automatiquement — ainsi, une baisse d'utilité ou une hausse des hallucinations apparaît d'elle-même, avant qu'un client ne le ressente.
+
+![La grille des sessions avec une colonne de scores : chaque exécution porte un badge d'état d'évaluation et des indicateurs codés par couleur pour l'utilité, la factualité et l'efficacité des outils](/agenteye/images/sessions-list.png)
+
+*Chaque exécution dans la grille des sessions affiche ses scores ; les badges rouges, ambrés et verts font ressortir les exécutions faibles sans que vous ayez à ouvrir une seule transcription.*
+
+## Arrêtez de contrôler manuellement les exécutions
+
+Vous vérifiez encore quelques exécutions au hasard en espérant que le reste est correct. Désormais, chaque session terminée est scorée au moment où elle se termine, selon les dimensions qui vous importent : utilité, efficacité des outils, factualité, sécurité, quel que soit votre seuil de qualité. Vous définissez les clés de score ; Failproof AI Observability stocke, suit les tendances et affiche tout ce que votre évaluateur renvoie. Aucune exécution ne passe sans être scorée, et vous n'apprendrez plus une régression via un ticket de support.
+
+Les scores apparaissent dans la grille des sessions à **`/<org-slug>/sessions`** (barre latérale → *observe* → *sessions*), avec un groupe de badges par ligne. Vous voulez uniquement les exécutions en dessous du seuil ? Filtrez la grille par plage de scores — par exemple, une utilité inférieure à 0,5 — pour afficher exactement les exécutions qui méritent d'être lues. La consultation des scores nécessite la permission `evaluations:read`.
+
+## Comprendre pourquoi une exécution a obtenu un score faible
+
+Un chiffre vous indique qu'une exécution était faible ; la page de session vous explique pourquoi. Ouvrez n'importe quelle exécution et le panneau de droite commence par le résumé principal, puis affiche une barre par dimension avec le raisonnement de votre évaluateur sous chacune — ainsi, vous passez de « cette exécution a obtenu 0,4 en factualité » à l'affirmation exacte qui était incorrecte en quelques secondes.
+
+![Le panneau droit d'une session : le résumé de l'évaluation en haut, puis des barres de score par dimension avec une ligne de raisonnement pour chacune, à côté de la chronologie complète des événements](/agenteye/images/session-detail.png)
+
+*La vue détaillée d'une session : résumé, barres de score par dimension et le raisonnement derrière chaque score, juste à côté de la chronologie des événements de l'exécution.*
+
+Vous avez déployé un évaluateur plus précis, ou vous regardez une exécution qui a planté avant d'être scorée ? Un bouton **re-evaluate** (conditionné par `evaluations:trigger`) rescote la session sur place et ajoute le nouveau résultat à sa chronologie, de sorte que les scores antérieurs restent visibles comme historique. Vous le trouverez à **`/<org-slug>/sessions/<session-id>`**.
+
+## Suivre l'évolution de la qualité sur l'ensemble du parc
+
+Une exécution avec un score faible est du bruit ; toute une cohorte qui glisse est un signal. Les tableaux de bord sauvegardés transforment vos scores en une tendance que vous pouvez surveiller d'un coup d'œil : utilité moyenne cette semaine par rapport à la semaine dernière, par agent, par environnement.
+
+![Un tableau de bord qualité : barres de score moyen par dimension d'évaluation accompagnées d'une tendance dans le temps](/agenteye/images/dashboard-quality.png)
+
+*Un tableau de bord qualité sauvegardé suit les clés de score que vous mettez en avant, afin qu'une dérive progressive soit évidente bien avant de devenir un incident.*
+
+Les tableaux de bord se trouvent à **`/<org-slug>/dashboards`** (barre latérale → *analyze* → *dashboards*), sont partagés dans toute votre organisation, et chaque carte regroupe les sessions correspondantes : leur nombre, la moyenne de chaque score mis en avant et un graphique sparkline de tendance. « Open in sessions » vous amène directement aux exécutions pré-filtrées derrière n'importe quel chiffre. La consultation nécessite `dashboards:read` ainsi que `evaluations:read`.
+
+## Connecter un évaluateur une seule fois
+
+Le scoring est optionnel et reste complètement désactivé jusqu'à ce que vous pointiez Failproof AI Observability vers un scorer. Vous déployez un petit service HTTP (Observability fournit une référence fonctionnelle que vous pouvez copier), définissez deux valeurs sur votre serveur, et chaque exécution à partir de ce moment est scorée pour vous. Le guide complet, le contrat de scoring et le SDK se trouvent dans le guide approfondi.
+
+Vous ne savez pas quelles dimensions valent la peine d'être scorées ? La [compétence d'agent évaluateur](/fr/agenteye/evaluator-skill) fait travailler votre agent de code pour les déterminer à partir de vos propres sessions, puis construire et déployer le service.
+
+## Liens connexes
+
+- [Suite d'évaluation](/fr/agenteye/evaluation-suite) : connecter votre évaluateur, le contrat de scoring et le SDK.
+- [Compétence d'agent évaluateur](/fr/agenteye/evaluator-skill) : laissez un agent de code choisir vos dimensions de score et construire l'évaluateur.
+- [Sessions](/fr/agenteye/sessions) : la grille exécution par exécution où les scores apparaissent.
+- [Tableaux de bord](/fr/agenteye/dashboards) : sauvegardez et partagez les tendances de qualité dans votre organisation.
+- [Audits](/fr/agenteye/audits) : l'autre fonctionnalité de qualité automatique d'Observability, pour les investigations inter-sessions.

package/.next/standalone/docs-old/fr/agenteye/evaluator-skill.mdx

@@ -0,0 +1,167 @@
+---
+title: "Compétence d'agent évaluateur Failproof AI Observability"
+description: "Passez de « je pense que notre agent est parfois mauvais » à un service de scoring déployé, votre agent de codage se chargeant à la fois de la conception et de la construction."
+---
+
+
+Passez de *« je pense que notre agent est parfois mauvais »* à un service de scoring déployé, votre agent de codage se chargeant à la fois de la conception et de la construction. La **compétence évaluateur Failproof AI Observability** (`agenteye-evaluator`) est une *Agent Skill* : un petit dossier d'instructions qu'un agent de codage tel que Claude Code ou Codex charge à la demande. Elle apprend à l'agent à déterminer quelles dimensions de qualité méritent d'être suivies pour *votre* agent, puis à écrire, tester et déployer le [service évaluateur](/fr/agenteye/evaluation-suite) qui les note.
+
+Il ne s'agit **pas** d'un scoring hébergé, d'un registre vers lequel vous téléversez du contenu, ni d'un système de plugins. Votre évaluateur reste votre propre service HTTP sur votre propre infrastructure, exactement comme décrit dans le guide [Evaluation suite](/fr/agenteye/evaluation-suite). La compétence apprend simplement à votre agent à le construire correctement — tout ce qu'elle fait, vous pourriez le faire vous-même en écrivant le même code.
+
+---
+
+## La partie difficile, c'est de décider quoi noter
+
+La surface du SDK est réduite — un décorateur et deux modèles — et un agent peut l'écrire à partir du seul [contrat](/fr/agenteye/evaluation-suite#http-contract). Ce n'est pas là que les évaluateurs échouent. Ils échouent parce qu'ils mesurent la mauvaise chose, et un évaluateur qui mesure la mauvaise chose est pire qu'aucun : il produit un tableau de bord que tout le monde apprend à ignorer.
+
+L'essentiel de la compétence concerne donc ce qui précède tout code. Elle fait interviewer l'agent (*« décrivez une exécution qui s'est bien passée ; maintenant une qui s'est mal passée »*), puis lui fait parcourir vos vraies sessions via la [CLI `agenteye`](/fr/agenteye/cli) et les lire de bout en bout. Ces deux sources divergent généralement, et l'écart est justement le point central : ce que vous avez l'intention de mesurer par rapport à ce que vos transcriptions peuvent réellement étayer. Une dimension ne survit que si elle est **calculable** à partir des événements et **discriminante** — si elle donne 0,9 à la fois sur votre bonne exécution et sur la mauvaise, elle n'enseigne rien et est supprimée.
+
+Ce qui en ressort est une proposition de 2 à 4 dimensions avec le raisonnement associé, que vous devez valider avant qu'une seule ligne ne soit écrite.
+
+```mermaid
+flowchart TD
+    YOU["vous : 'je veux des évals pour mon bot de support'"] --> AGENT["agent de codage (Claude Code / Codex)<br/>charge la compétence agenteye-evaluator"]
+    AGENT -->|"interview : à quoi ressemble le bon vs le mauvais ?"| YOU
+    AGENT -->|"agenteye --json sessions / events"| DATA["vos vraies sessions<br/>ce qui se passe réellement"]
+    DATA --> DIMS["2-4 dimensions, vous validez"]
+    DIMS --> SVC["votre service évaluateur<br/>SDK agenteye-evaluator"]
+    SVC --> SCORES["les scores apparaissent dans le tableau de bord<br/>et agenteye evals"]
+```
+
+---
+
+## Relation avec les autres composants d'évaluation
+
+Quatre pages couvrent le scoring, et se relaient dans l'ordre :
+
+| Page | Ce que c'est | À utiliser quand |
+|---|---|---|
+| **[Evaluations](/fr/agenteye/evaluations)** | La fonctionnalité : scores sur la grille de sessions, tableaux de bord, réévaluation | Vous voulez savoir ce que le scoring automatique vous apporte |
+| **[Evaluation suite](/fr/agenteye/evaluation-suite)** | Le contrat HTTP, le SDK, les variables d'environnement serveur | Vous implémentez ou déboguez vous-même l'évaluateur |
+| **Compétence évaluateur** (ce doc) | Une entrée en langage naturel pour concevoir *et* construire le scorer | Vous voulez passer de « je veux des évals » à un service opérationnel |
+| **[CLI skill](/fr/agenteye/cli-skill)** | Une entrée en langage naturel sur la CLI `agenteye` | Vous voulez *lire* les scores que vous avez déjà |
+| **[Python SDK skill](/fr/agenteye/python-sdk-skill)** | Une entrée en langage naturel pour instrumenter votre agent | Votre agent n'émet pas encore de sessions — il n'y a rien à noter |
+
+### Par rapport à la CLI skill : construire versus lire
+
+Les deux compétences sont délibérément sans chevauchement, et les installer toutes les deux est la configuration habituelle — l'agent choisit entre elles en fonction de ce que vous demandez :
+
+- **`agenteye-evaluator`** (ce doc) construit ce qui *produit* les scores. Sa mission se termine quand les scores arrivent pour la première fois.
+- **[`agenteye-cli`](/fr/agenteye/cli-skill)** lit les scores déjà existants (`agenteye evals`). *« La qualité a-t-elle baissé cette semaine ? »* est sa question, pas celle de cette compétence.
+
+---
+
+## Prérequis
+
+1. **La CLI `agenteye` installée et connectée** (`pipx install agenteye`, puis `agenteye login`). La compétence s'appuie dessus à deux reprises : pour récupérer les vraies sessions sur lesquelles elle se base lors de la conception, et pour confirmer que vos scores sont bien arrivés à la fin. Votre connexion nécessite `events:read`, plus `evaluations:read` pour cette vérification finale. Comme avec la CLI skill, elle **ne peut pas** compléter la connexion par code à usage unique envoyé par e-mail à votre place.
+2. **Un endroit où héberger l'évaluateur.** Il est construit dans une image et exécuté en tant que service de longue durée, il a donc besoin d'un vrai dépôt, pas d'un fichier temporaire. Les évaluateurs vivent souvent dans leur propre dépôt, séparé de l'agent évalué — la compétence cherche un dépôt existant et demande avant d'en créer un nouveau.
+3. **La roue SDK `agenteye-evaluator`** — lisez la section suivante avant que votre agent commence à taper des commandes `pip`.
+
+---
+
+## Où l'obtenir
+
+La compétence est publiée dans la collection publique de compétences de Failproof AI :
+
+**[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator)
+
+Le dépôt est public et la compétence n'a pas besoin de ses propres identifiants — elle pilote uniquement la CLI `agenteye` avec la session *sur laquelle vous êtes connecté*, et écrit du code dans *votre* dépôt. Notez qu'elle est livrée dans son propre dossier et n'est **pas** incluse dans le package `pipx install agenteye`, donc ne la cherchez pas là.
+
+## Installer la compétence
+
+Le chemin le plus rapide passe par la CLI [`skills`](https://skills.sh), qui récupère le dossier et le place là où votre agent le cherche :
+
+```bash
+# Claude Code, ce projet uniquement
+npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code
+
+# tous les projets (installe dans ~/.claude/skills/)
+npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy
+
+# Codex à la place
+npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex
+```
+
+Puis gérez-la comme n'importe quelle autre compétence :
+
+```bash
+npx skills list -a claude-code           # ce qui est installé
+npx skills update agenteye-evaluator     # récupérer la dernière version
+npx skills remove agenteye-evaluator     # la supprimer
+```
+
+Vous préférez installer manuellement ? Une Agent Skill est juste un dossier contenant un `SKILL.md` (plus des références optionnelles), donc la copier fonctionne aussi :
+
+- **Claude Code** : placez le dossier `agenteye-evaluator/` dans `~/.claude/skills/` (tous les projets) ou `<votre-dépôt>/.claude/skills/` (ce dépôt uniquement). Claude Code le découvre automatiquement — vérifiez avec la liste `/skills`, ou demandez simplement des évals.
+- **Codex (OpenAI)** : Codex lit le même `SKILL.md`. Le fichier `agents/openai.yaml` fourni définit `allow_implicit_invocation: true`, donc Codex sélectionne automatiquement la compétence quand une tâche correspond ; sinon invoquez-la explicitement avec `$agenteye-evaluator`.
+
+---
+
+## Le SDK n'est pas sur PyPI public
+
+> **Avertissement :** Lisez ceci avant de laisser un agent installer le SDK.
+
+La compétence est publique ; le SDK qu'elle pilote ne l'est pas. `agenteye-evaluator` est livré uniquement comme artefact de version privée, et contrairement à `agenteye`, le nom est **non revendiqué sur PyPI public** — donc un simple `pip install agenteye-evaluator` pourrait installer le package d'un inconnu dans le service qui lit vos transcriptions de production. C'est un problème de chaîne d'approvisionnement, pas une faute de frappe.
+
+La compétence le sait et parcourt à la place une liste d'installation par priorité, s'arrêtant à la première qui s'applique : la source du monodépôt si vous êtes dans le dépôt AgentEye, sinon la roue de version privée depuis GitHub Releases (nécessite un accès), et si aucune n'est accessible, elle **s'arrête et vous indique de demander la roue à votre contact Failproof AI** plutôt que d'improviser.
+
+Donc si votre agent propose un simple `pip install agenteye-evaluator` depuis PyPI public, c'est le signe que la compétence n'a jamais été chargée. Arrêtez-vous et vérifiez qu'elle est bien installée.
+
+---
+
+## Ce que vous pouvez lui demander
+
+Un vrai aller-retour commence par une demande vague et se termine par une conception validée, pas par du code :
+
+```text
+vous  ▸ Je veux des évals pour notre bot de support. Je pense qu'il est parfois mauvais.
+
+agent ▸ Avant d'écrire quoi que ce soit : décrivez une exécution qui s'est bien
+        passée, et une qui s'est mal passée.
+
+vous  ▸ Bien : il répond à partir de la documentation. Mal : il invente des choses,
+        ou abandonne et dit « contactez le support ».
+
+agent ▸ Exécution : agenteye --json sessions --status error --since 7d
+        Lecture de 5 sessions, dont deux que vous qualifieriez de mauvaises.
+
+        Vos mots évoquent la factualité et le décrochage. Les transcriptions
+        confirment le décrochage (2 sur 5 se terminent par un transfert au support,
+        clairement visible dans model_response.content), mais la factualité
+        nécessite une vérité terrain que vos événements ne contiennent pas.
+
+        Je mesurerais donc trois choses :
+          - deflection      règles, peu coûteux, distingue vos deux exécutions
+          - tool_efficiency règles, détecte la boucle de réessai dans run-004
+          - groundedness    juge LLM : chaque affirmation est-elle dans les docs récupérés ?
+
+        « factualité » nécessiterait une vérité terrain que nous n'avons pas ;
+        groundedness est ce que vos transcriptions peuvent réellement étayer.
+        D'accord avec ces trois noms ? Les renommer plus tard divise l'historique.
+
+vous  ▸ oui
+
+agent ▸ Pas d'évaluateur dans ce dépôt. Dois-je en créer un ici, ou en avez-vous
+        un ailleurs ?
+```
+
+À partir de là, il écrit d'abord les dimensions basées sur des règles (gratuites, instantanées, déterministes), les teste contre une vraie session capturée incluant les sessions vides et inachevées qui font planter les évaluateurs naïfs, et n'utilise un juge LLM que pour la dimension subjective. Il connaît les [limites du dispatcher](/fr/agenteye/evaluation-suite#configuring-the-server) — un délai de requête de 30s et 8 appels simultanés dans tout le déploiement — donc si le juge ne s'y adapte pas de manière fiable, il passe en asynchrone avec `JobPending` plutôt que de laisser votre juge être annulé et réessayé cinq fois au quintuple du coût.
+
+Ensuite il déploie, définit les deux variables d'environnement serveur, et confirme avec `agenteye --json evals --session-id <id>` que les scores sont bien arrivés. L'arrivée des scores est la seule preuve.
+
+---
+
+## Ce à quoi faire attention
+
+- **Les noms de dimensions sont quasi permanents.** Les clés de score sont des chaînes arbitraires et la plateforme suit les tendances de tout ce que vous envoyez, ce qui signifie que rien en aval ne corrige un mauvais choix. Renommer plus tard divise l'historique : les anciennes sessions conservent l'ancienne clé et la tendance se brise. C'est pourquoi la compétence obtient une validation explicite avant d'écrire du code — prenez cette invite au sérieux.
+- **Les fixtures sont de vraies transcriptions de production.** Concevoir à partir de vraies sessions signifie les télécharger sur le disque, et elles peuvent contenir des données clients. La compétence demande avant de les committer dans git ; en cas de doute, gardez `fixtures/` hors du dépôt et faites récupérer les siennes à chaque développeur.
+- **L'agent écrit et déploie un service qui lit chaque transcription.** Il agit en votre nom, limité par les permissions de votre connexion CLI, mais examinez l'évaluateur comme n'importe quel autre code qui touche des données de production.
+
+---
+
+## Prochaines étapes
+
+- **[Evaluation suite](/fr/agenteye/evaluation-suite)** : le contrat HTTP, le SDK et les variables d'environnement serveur que la compétence configure.
+- **[Evaluations](/fr/agenteye/evaluations)** : là où les scores s'affichent une fois qu'ils arrivent.
+- **[CLI skill](/fr/agenteye/cli-skill)** : la compétence jumelle, pour lire les résultats plutôt que construire le scorer.
+- **[CLI](/fr/agenteye/cli)** : la référence des commandes derrière les données de session sur lesquelles la compétence se base.