failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/fr/agenteye/api-keys.mdx

@@ -0,0 +1,280 @@
+---
+title: "Clés API"
+description: "Les clés API contrôlent qui et ce qui peut atteindre votre serveur d'observabilité Failproof AI, afin qu'un collecteur puisse envoyer des événements sans jamais obtenir de droits de lecture ou d'administration."
+---
+
+
+Les clés API contrôlent qui et ce qui peut atteindre votre serveur d'observabilité Failproof AI, afin qu'un collecteur puisse envoyer des événements sans jamais obtenir de droits de lecture ou d'administration. Chaque clé porte une ou plusieurs permissions, et chaque permission conditionne l'accès à des routes spécifiques du serveur ; vous n'accordez que celles dont un service a besoin. La plupart des déploiements créent seulement trois types de clés.
+
+## Les 3 clés dont la plupart des déploiements ont besoin
+
+| Clé | Permissions | Utilisée par |
+|---|---|---|
+| Clé collecteur | `events:add` | L'`agenteye-collector` sur chaque machine agent, pour envoyer des événements. |
+| Clé de lecture tableau de bord | `events:read`, `keys:read` | Un opérateur en lecture seule ou une intégration qui interroge les données sans les modifier. |
+| Clé admin d'amorçage | toutes les permissions | L'opérateur qui démarre l'instance pour la première fois (et le tableau de bord). Initialisée depuis la variable d'environnement `ADMIN_KEY`. Voir [Clé admin d'amorçage](#bootstrap-admin-key). |
+
+Commencez ici. Ne consultez le catalogue complet des permissions ci-dessous que lorsque vous avez besoin d'une clé personnalisée à portée restreinte. Voir aussi [Disposition recommandée des clés](#recommended-key-layout) et [Créer des clés](#creating-keys).
+
+---
+
+## Permissions
+
+Le serveur applique un catalogue fixe de permissions ; chacune conditionne l'accès à des routes HTTP spécifiques. Une **clé admin** les possède toutes ; une clé à portée restreinte possède le sous-ensemble que vous accordez à la création. Les chaînes de permission inconnues sont rejetées lors de la création d'une clé.
+
+> **Remarque :** Deux permissions valides sont réservées aux humains/tableau de bord et ne peuvent pas être accordées à une clé API : `orgs:admin` (administration de l'instance, réservée aux opérateurs) et `keys:update`. Toute requête vers `POST /keys` ou `PATCH /keys/:id` qui tente d'accorder l'une ou l'autre est rejetée avec HTTP 422. Voir la ligne `keys:update` ci-dessous pour comprendre pourquoi une clé porteuse peut créer des clés mais jamais les modifier.
+
+### Ingestion et interrogation d'événements
+
+| Permission | Routes HTTP | Ce qu'elle autorise |
+|---|---|---|
+| `events:add` | `POST /events` | Ingérer des lots d'événements depuis un collecteur. La seule permission dont un collecteur a besoin. |
+| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Interroger les événements, lister les environnements connus, lister les identifiants de modèles présents dans les données (utilisés par la vue Modèles et les filtres de modèles), calculer l'agrégat de latence qui alimente la carte thermique / bande de percentiles, et exporter une session en JSONL. Les endpoints de facettes partagés de la barre de filtres `GET /events/environments` et `GET /events/agent_ids` sont accessibles avec **soit** `events:read` **soit** `evaluations:read`, de sorte que la page des sessions (conditionnée par `evaluations:read`) réutilise la même facette par organisation. `GET /events/models` n'en fait pas partie : elle requiert `events:read`, donc un principal ne détenant que `evaluations:read` reçoit un 403. |
+
+### Sessions et évaluations
+
+| Permission | Routes HTTP | Ce qu'elle autorise |
+|---|---|---|
+| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Lister les sessions, lire les résultats d'évaluation, l'état de santé agrégé des évaluations utilisé par les tableaux de bord, et l'état de la file d'attente du worker d'évaluation. |
+| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Mettre manuellement en file d'attente une réévaluation pour une session terminée. |
+
+### Tableaux de bord
+
+| Permission | Routes HTTP | Ce qu'elle autorise |
+|---|---|---|
+| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Lister les tableaux de bord, en charger un, et lire ses tuiles. |
+| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Créer et modifier des tableaux de bord, ajouter / modifier / supprimer des tuiles, et réorganiser la grille de tuiles. |
+| `dashboards:delete` | `DELETE /dashboards/:id` | Supprimer un tableau de bord entier (la suppression au niveau des tuiles relève de `dashboards:write`). |
+
+### Requêtes enregistrées (compositeur SQL)
+
+| Permission | Routes HTTP | Ce qu'elle autorise |
+|---|---|---|
+| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Lister les requêtes enregistrées, en charger une, et inspecter le schéma en lecture seule ciblé par le compositeur. |
+| `queries:write` | `POST /queries`, `PUT /queries/:id` | Créer et modifier des requêtes enregistrées. Le SQL est toujours acheminé via le même rôle en lecture seule et les mêmes vérifications SQL protégées qu'un appel `queries:run`. |
+| `queries:delete` | `DELETE /queries/:id` | Supprimer une requête enregistrée. |
+| `queries:run` | `POST /queries/run` | Exécuter du SQL enregistré ou ad hoc contre le rôle en lecture seule utilisé par le compositeur. |
+
+### Assistant IA
+
+| Permission | Routes HTTP | Ce qu'elle autorise |
+|---|---|---|
+| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Interagir avec l'assistant IA et gérer ses propres conversations (privées). Requise sur l'**utilisateur** pour voir le volet assistant ; la propre clé de l'assistant est `dashboard-assistant` et est initialisée séparément (voir ci-dessous). |
+
+### Clés API
+
+| Permission | Routes HTTP | Ce qu'elle autorise |
+|---|---|---|
+| `keys:create` | `POST /keys` | Créer une nouvelle clé API à portée restreinte. N'accorde **pas** la modification des permissions d'une clé existante (c'est `keys:update`). |
+| `keys:read` | `GET /keys` | Lister les clés existantes. Les secrets ne sont jamais retournés par cet endpoint. |
+| `keys:update` | `PATCH /keys/:id` | Modifier les permissions d'une clé existante. Permission **réservée aux humains/tableau de bord** ; elle ne peut pas être assignée à une clé API (une clé porteuse peut créer des clés mais jamais les modifier). |
+| `keys:disable` | `POST /keys/:id/disable` | Révoquer une clé. Les clés protégées (`admin`, `dashboard-assistant`) ne peuvent pas être désactivées ; faites-les pivoter via la variable d'environnement + redémarrage. |
+| `keys:regenerate` | `POST /keys/:id/regenerate` | Régénérer le secret d'une clé. Les clés protégées ne peuvent pas être régénérées via cette route. |
+
+### Utilisateurs du tableau de bord
+
+| Permission | Routes HTTP | Ce qu'elle autorise |
+|---|---|---|
+| `users:create` | `POST /users`, `GET /users/defaults` | Inviter un nouvel utilisateur du tableau de bord (envoie un e-mail + connexion par mot de passe à usage unique (OTP)) et lire l'ensemble de permissions par défaut configuré dans le tableau de bord utilisé pour pré-remplir le formulaire d'invitation. |
+| `users:read` | `GET /users`, `GET /users/:id` | Lister les utilisateurs et charger un enregistrement utilisateur individuel. |
+| `users:update` | `PUT /users/:id` | Modifier les permissions d'un utilisateur. Les mises à jour envoient un e-mail de notification de changement de permissions à l'utilisateur concerné et prennent effet à sa prochaine requête, sans reconnexion nécessaire. |
+| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Désactiver un utilisateur (révoque ses sessions immédiatement) et réactiver un utilisateur précédemment désactivé. |
+
+Ces permissions alimentent la page **Utilisateurs** du tableau de bord, où les portées accordées à chaque membre s'affichent sous forme de puces :
+
+![La page Utilisateurs : une carte par utilisateur du tableau de bord avec son e-mail, les permissions accordées et les contrôles de modification/désactivation](/agenteye/images/users.png)
+
+### Paramètres opérationnels
+
+| Permission | Routes HTTP | Ce qu'elle autorise |
+|---|---|---|
+| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Afficher les paramètres opérationnels gérés par le tableau de bord et leurs métadonnées ; lister les remplacements de fenêtre de contexte par modèle ; et résoudre la fenêtre effective pour un modèle. |
+| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Modifier les paramètres opérationnels et ajouter, modifier ou supprimer les remplacements de fenêtre de contexte par modèle. Les modifications s'appliquent aux nouveaux événements sans redémarrage du serveur. |
+
+![La page Paramètres : paramètres opérationnels gérés par le tableau de bord tels que les connexions autorisées et les durées de vie des sessions/OTP, modifiables sans redémarrage](/agenteye/images/settings.png)
+
+### Alertes et incidents
+
+| Permission | Routes HTTP | Ce qu'elle autorise |
+|---|---|---|
+| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Afficher les définitions d'alertes configurées. |
+| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Créer, modifier, supprimer et tester des définitions d'alertes. |
+| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Afficher les incidents et leur historique de triage. |
+| `incidents:write` | `POST /alerts/:id/incidents` | Ouvrir manuellement un incident sur une alerte existante. |
+| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Acquitter, assigner, résoudre et commenter des incidents. |
+
+### Audits
+
+| Permission | Routes HTTP | Ce qu'elle autorise |
+|---|---|---|
+| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Afficher les définitions d'audit, l'historique d'exécution et les résultats. |
+| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Créer, modifier, supprimer et exécuter des audits ; trier les résultats (acquitter / mettre en sourdine / ignorer / résoudre / rouvrir / assigner). |
+
+> **Remarque :** Pour donner à une clé l'accès à la surface d'audit, accordez-lui explicitement `audits:*`. Voir [Notes de mise à jour et de compatibilité ascendante](#upgrade-and-backward-compatibility-notes) pour savoir comment les bénéficiaires existants ont été migrés lors du déploiement des Audits.
+
+> L'endpoint du sélecteur de destinataires `GET /alerts/recipients` (qui liste les e-mails des membres qu'un éditeur d'alertes peut notifier) est accessible par un détenteur de **soit** `alerts:read` **soit** `alerts:write`, de sorte que les éditeurs d'alertes peuvent remplir le sélecteur sans se voir accorder `users:read`.
+
+> Un lecteur de tableaux de bord a besoin des deux permissions `dashboards:read` (pour charger les vues enregistrées) et `evaluations:read` (les métriques de santé sont calculées à partir des données d'évaluation). Accordez `dashboards:write` pour permettre à un utilisateur de créer ou de modifier des tableaux de bord, et `dashboards:delete` pour les supprimer.
+
+> `/health` et `/auth/*` (demande OTP, vérification OTP, vérification de session, déconnexion) sont non authentifiés par conception ; il s'agit du flux de connexion et de la sonde de disponibilité. `GET /access-granters` nécessite une clé valide mais aucune permission spécifique, de sorte que tout utilisateur connecté peut voir quels administrateurs contacter pour les changements d'accès.
+
+---
+
+## Ensembles de permissions
+
+Les ensembles de permissions vous permettent d'appliquer un rôle nommé au lieu de sélectionner manuellement des tokens individuels à chaque fois. Plutôt que de sélectionner une douzaine de permissions une par une pour chaque nouvel utilisateur du tableau de bord ou clé API, vous choisissez un ensemble, et tous ceux qui y sont assignés bénéficient d'une attribution cohérente et vérifiable. La modification d'un ensemble personnalisé réapplique le nouvel accès à chaque utilisateur qui y est déjà assigné, de sorte qu'un changement de rôle est une seule modification plutôt qu'une mise à jour de chaque membre.
+
+Chaque organisation est initialisée avec trois ensembles intégrés :
+
+| Ensemble | Permissions | Destiné à |
+|---|---|---|
+| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Accès en lecture seule sur toutes les surfaces opérationnelles. |
+| `standard` | tout ce qui est dans `read-only`, plus `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Lecture seule plus les actions quotidiennes de l'équipe de permanence : exécuter des requêtes, réévaluer des sessions, acquitter des incidents et utiliser l'assistant IA. |
+| `admin` | toutes les permissions assignables | Contrôle total de l'organisation. |
+
+Les trois ensembles intégrés sont **immuables** ; leurs noms ont toujours la même signification, donc `read-only`, `standard` et `admin` peuvent être référencés en toute sécurité dans les politiques et l'onboarding. Un opérateur peut créer des **ensembles personnalisés** supplémentaires pour modéliser des rôles spécifiques à votre organisation (par exemple, un rôle « auteur de tableau de bord » ou un rôle « collecteur uniquement »).
+
+Les ensembles sont exposés dans le tableau de bord et gérés via l'API sur `GET /permission-sets` (liste, conditionnée par `users:read`) et `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (créer, modifier, supprimer un ensemble personnalisé, conditionné par `settings:write`). La suppression ou la modification d'un ensemble intégré est refusée.
+
+L'appartenance à un ensemble est ce qui sous-tend deux autres fonctionnalités :
+
+- **`DEFAULT_USER_PERMISSIONS`** (l'accès présélectionné lorsqu'un administrateur ouvre **+ nouvel utilisateur**) correspond par défaut à l'ensemble `standard`.
+- **L'indicateur `--set`** sur `agenteye-orgctl` (gestion des membres opérateurs) démarre un membre à partir d'un ensemble nommé, que vous affinez ensuite avec `--add` / `--remove`.
+
+> **Remarque :** Lorsqu'un ensemble inclut une permission non assignable à une clé (par exemple un ensemble personnalisé portant `keys:update`), l'initialisation d'une clé à partir de cet ensemble supprime les tokens non assignables ; le serveur rejetterait sinon la clé avec HTTP 422. Les utilisateurs du tableau de bord ne sont pas soumis à cette restriction.
+
+---
+
+## Clé admin d'amorçage
+
+La clé admin est l'unique identifiant racine qui permet à un opérateur de démarrer les accès depuis zéro : avec elle, vous pouvez créer toutes les autres clés à portée restreinte, inviter les premiers utilisateurs du tableau de bord et configurer l'instance avant qu'aucune autre clé n'existe. C'est la seule clé que vous ne créez pas via l'API des clés ; elle est provisionnée depuis l'environnement pour que le serveur soit accessible au premier démarrage.
+
+Définissez la variable d'environnement `ADMIN_KEY` sur le serveur. À chaque démarrage, le serveur insère ou met à jour cette valeur en tant que clé admin avec toutes les permissions.
+
+Pour la faire pivoter : modifiez `ADMIN_KEY` avec un nouveau secret et redémarrez le serveur.
+
+---
+
+## Portée organisationnelle
+
+**Les organisations elles-mêmes sont créées et gérées hors bande par un opérateur, et non via cette API des clés.** Le cycle de vie des organisations et des membres (créer / renommer / supprimer / purger une organisation ; ajouter / mettre à jour / supprimer un membre) se fait avec l'interface CLI **`agenteye-orgctl`** ; il n'existe ni API HTTP ni bouton de tableau de bord pour cela. Ce qui *reste* inchangé : **les clés API par organisation sont toujours créées dans le tableau de bord (ou via cette API des clés)** par les membres de l'organisation.
+
+Dans un déploiement multi-organisations, chaque clé créée par un membre d'une organisation (via cette API des clés ou la page **Clés** du tableau de bord) appartient à **une seule organisation** et ne peut lire ou écrire que les données de cette organisation ; l'organisation est inscrite dans la clé à la création et appliquée à chaque requête. Les deux clés d'amorçage constituent la seule exception : la clé `admin` (initialisée depuis `ADMIN_KEY`) et la clé `dashboard-assistant` (initialisée depuis `AGENT_API_KEY`) ont une **portée d'instance** (elles ne portent aucune organisation). Le tableau de bord s'authentifie avec la clé `admin` afin de pouvoir traiter les requêtes par organisation au nom des membres connectés. Les déploiements mono-tenant n'ont pas à se préoccuper de cela ; toutes les clés appartiennent à l'organisation `default` intégrée.
+
+---
+
+## Créer des clés
+
+Utilisez la clé admin (ou toute clé avec la permission `keys:create`) pour créer des clés supplémentaires à portée restreinte.
+
+### Clé collecteur (ingestion uniquement)
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "prod-collector",
+    "key": "your-collector-secret",
+    "permissions": ["events:add"]
+  }'
+```
+
+### Clé tableau de bord (lecture seule)
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "dashboard",
+    "key": "your-dashboard-secret",
+    "permissions": ["events:read", "keys:read"]
+  }'
+```
+
+Lorsque vous créez une clé via l'API HTTP, vous fournissez vous-même la valeur `key` ; choisissez un secret fort et stockez-le de manière sécurisée. (Le tableau de bord fonctionne différemment : il génère un secret fort pour vous et le montre une seule fois à la création ; voir [Gestion des clés dans le tableau de bord](#key-management-in-the-dashboard).) La réponse confirme que la clé a été créée :
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "prod-collector",
+  "permissions": ["events:add"],
+  "created_at": "2026-04-01T12:00:00Z"
+}
+```
+
+---
+
+## Lister les clés
+
+```bash
+curl -s http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+Les secrets des clés ne sont pas retournés dans les réponses de liste, seulement les identifiants, noms et permissions.
+
+---
+
+## Désactiver une clé
+
+La désactivation révoque l'accès immédiatement sans supprimer l'enregistrement de la clé.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/disable \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+---
+
+## Régénérer une clé
+
+Génère un nouveau secret pour une clé existante. L'ancien secret est invalidé immédiatement.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/regenerate \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+La réponse inclut le nouveau secret en clair, **affiché une seule fois**.
+
+---
+
+## Gestion des clés dans le tableau de bord
+
+La page **Clés** du tableau de bord fournit une interface utilisateur pour toutes les opérations ci-dessus. Vous avez besoin d'une clé avec la permission `keys:read` pour afficher la liste, et `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` pour les actions de création / modification / désactivation / régénération respectivement. La modification des permissions d'une clé (`keys:update`) est distincte de sa création (`keys:create`), ce qui vous permet d'accorder à un opérateur la possibilité de créer des clés sans pouvoir modifier la portée des clés existantes, ou inversement. La clé admin couvre tout cela.
+
+Lorsque vous créez une clé depuis le tableau de bord, vous ne fournissez pas le secret ; le tableau de bord génère un secret fort pour vous et l'affiche **une seule fois** à la création. Copiez-le immédiatement et stockez-le de manière sécurisée ; il ne sera plus jamais affiché, exactement comme lors d'une régénération. Vous pouvez toujours choisir les permissions de la clé directement, ou les initialiser depuis un ensemble de permissions (voir ci-dessous).
+
+![La page Clés API : une carte par clé affichant son nom, les permissions accordées et la date de création, avec les actions de régénération et de désactivation ; les clés protégées comme `admin` sont marquées](/agenteye/images/api-keys.png)
+
+---
+
+## Disposition recommandée des clés
+
+| Clé | Permissions | Utilisée par |
+|---|---|---|
+| `admin` (amorçage via la variable d'environnement `ADMIN_KEY`) | toutes | Ops/configuration, et le tableau de bord (s'authentifie avec `ADMIN_KEY`, traite les requêtes des utilisateurs avec des vérifications de permissions) |
+| Clé collecteur par hôte | `events:add` | Collecteur sur chaque machine agent |
+| `dashboard-assistant` (amorçage via la variable d'environnement `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Assistant IA, initialisé automatiquement, **protégé** ; ne peut pas être modifié via l'API |
+| Clé de télémétrie de l'assistant (optionnelle) | `events:add` | Auto-instrumentation de l'assistant IA, si activée |
+
+> **Remarque :** La clé de l'assistant est **initialisée automatiquement** par le serveur depuis la variable d'environnement `AGENT_API_KEY` (le même secret que l'agent présente comme `AGENTEYE_API_KEY`) ; il n'y a pas d'étape manuelle de création de clé ni de clé admin impliquée. Ses permissions sont figées dans le code source afin que la portée ne puisse pas être élargie par une mauvaise configuration : lecture sur les événements / évaluations / tableaux de bord, plus écriture sur les tableaux de bord et lecture / écriture / exécution des requêtes pour le flux de création « Demander à l'IA d'écrire une requête ». Tout SQL passe toujours par le même rôle en lecture seule et le même chemin SQL protégé qu'une requête écrite par un utilisateur, donc cela élargit la *surface de création*, pas la surface des données ; les opérations destructives (`queries:delete`, `dashboards:delete`) restent délibérément absentes de la clé de l'assistant. Comme la clé `admin`, elle est **protégée** : elle ne peut pas être désactivée ou régénérée via l'API des clés, seulement renouvelée en modifiant `AGENT_API_KEY` et en redémarrant. Les *utilisateurs* du tableau de bord ont en outre besoin de la permission `agent:use` pour voir et utiliser l'assistant. Si vous activez l'auto-instrumentation, donnez à l'assistant une clé séparée avec uniquement `events:add`.
+
+---
+
+## Notes de mise à jour et de compatibilité ascendante
+
+Ces notes ne sont nécessaires que si vous mettez à niveau une instance existante ; les nouveaux déploiements peuvent les ignorer.
+
+> Lors du déploiement des Audits, les bénéficiaires existants ont été élargis selon les mêmes formes de rôle que pour les alertes : chaque utilisateur et ensemble de permissions détenant `alerts:read` a obtenu `audits:read`, et chaque détenteur de `alerts:write` a obtenu `audits:write`. Les clés API existantes n'ont **pas** été élargies. Accordez explicitement `audits:*` à une clé si elle a besoin de la surface d'audit.
+
+> Les attributions stockées du token hérité `alerts:ack` sont interprétées comme `incidents:ack` afin que les équipes de permanence conservent leur accès sans devoir recréer leurs clés. Le token n'est plus assignable depuis l'éditeur d'utilisateurs du tableau de bord ; la matrice propose désormais `incidents:ack` à la place.
+
+---
+
+## Étapes suivantes
+
+- [SDK Python](/fr/agenteye/python-sdk) : comment votre code d'agent s'authentifie lors de l'envoi d'événements.
+- [Sécurité](/fr/agenteye/security) : comment fonctionnent la connexion, le contrôle d'accès et l'isolation des données par organisation.

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

@@ -0,0 +1,63 @@
+---
+title: "Assistant IA"
+description: "Posez une question sur vos données d'agent en langage naturel et obtenez une réponse qui renvoie directement aux preuves."
+---
+
+
+Posez une question sur vos données d'agent en langage naturel et obtenez une réponse qui renvoie directement aux preuves. Pas de SQL à écrire, pas de tableaux de bord à parcourir — l'assistant **Failproof AI Observability** est le moyen le plus rapide pour n'importe quel membre de votre équipe d'obtenir des réponses sur vos agents.
+
+![L'assistant Failproof AI Observability répondant à une question en langage naturel dans le tableau de bord, affichant un tableau d'activité des agents en direct, une répartition de l'utilisation des modèles par agent, et des conclusions rédigées, avec les requêtes exécutées affichées en ligne](/agenteye/images/assistant.png)
+*Posez votre question en langage naturel et obtenez une réponse construite à partir de vos propres données. Ici, l'assistant décompose quels agents sont les plus actifs et quels modèles ils utilisent, et affiche les requêtes exécutées pour que vous puissiez vérifier chaque chiffre.*
+
+Rien à apprendre. Ouvrez le chat, tapez ce que vous voulez savoir et suivez les liens qu'il vous renvoie :
+
+```
+You:  which sessions errored today?
+AI:   5 sessions errored today, newest first. Each one is linked:
+      • checkout-agent   14:02   tool timeout
+      • billing-agent    11:47   unhandled error
+      • ...and 3 more
+
+You:  summarize this session          (asked while viewing a run)
+AI:   This run took 12 steps across 3 tools and failed near the end when a
+      payment tool returned an error. It scored low on your "resolved" eval.
+      Links: the session, the failing event, and that evaluation.
+```
+
+## Posez la question, accédez directement à la preuve
+
+Vous arrêtez de deviner et vous arrêtez d'écrire des requêtes. Posez une question comme « comment évolue la qualité en prod cette semaine ? », « quelles sessions ont échoué aujourd'hui ? » ou « résume cette session », et vous obtenez une réponse directe en quelques secondes plutôt que de construire une requête et de la lire vous-même.
+
+Chaque réponse est accompagnée de ses justificatifs. L'assistant renvoie vers les sessions exactes, les requêtes sauvegardées et les tableaux de bord qu'il a utilisés pour formuler la réponse, afin que vous puissiez cliquer et confirmer plutôt que de le croire sur parole. Il est également **conscient du contexte de la page** : posez une question sur « cette session » pendant que vous la consultez et il sait déjà de quelle exécution vous parlez. Rouvrez une conversation antérieure depuis le sélecteur d'historique et reprenez là où vous en étiez.
+
+## Transformez une bonne réponse en requête sauvegardée ou en tableau de bord
+
+Lorsqu'une réponse mérite d'être conservée, demandez à l'assistant de la sauvegarder. Il rédige le SQL pour une requête sauvegardée, ou assemble un tableau de bord à partir de ces requêtes, puis vous présente une carte **Approuver / Rejeter**. Rien n'est écrit tant que vous ne cliquez pas sur Approuver, ce qui vous offre la rapidité du « il suffit de demander » tout en gardant le dernier mot.
+
+Sur la page **Queries**, il va encore plus loin et devient un auteur SQL : décrivez la requête souhaitée (« afficher le taux d'erreur par agent sur les 7 derniers jours ») et il diffuse le SQL directement dans l'éditeur, en ouvrant une vue diff afin que vous puissiez **Accepter** ou **Rejeter** la modification avant qu'elle ne soit appliquée.
+
+![La page Queries d'Observability et son éditeur SQL](/agenteye/images/query-lab.png)
+*La page Queries : cet éditeur est l'endroit où l'assistant diffuse un brouillon de requête en lecture seule que vous acceptez ou rejetez.*
+
+La création de SQL par cette méthode utilise la permission `queries:run`, la même que celle du bouton **Run** de l'éditeur. Le chat partout ailleurs nécessite `agent:use`.
+
+## Accessible à toute l'équipe en toute sécurité
+
+Vous pouvez ouvrir l'assistant à tous sans vous inquiéter de ce qu'il pourrait toucher :
+
+- **Il ne lit que ce que vous pouvez déjà voir.** Les réponses sont limitées à vos propres permissions de lecture, donc il n'élargit jamais votre surface de données.
+- **Chaque écriture attend votre confirmation.** Les requêtes sauvegardées et les tableaux de bord ne sont créés qu'après votre clic explicite sur Approuver, et aucun paramètre ne désactive cette validation.
+- **Il ne peut jamais rien supprimer.** Aucun outil de suppression n'est exposé et l'assistant ne détient aucune permission de suppression. Les suppressions restent entre vos mains, dans le tableau de bord.
+- **Il reste dans votre organisation.** L'assistant ne voit que l'organisation que vous consultez actuellement.
+- **Vos questions vous appartiennent.** Les invites et les réponses sont stockées dans votre propre base de données Observability ; l'analytique produit n'enregistre que les métadonnées d'utilisation, jamais le texte de vos invites.
+
+## Où le trouver
+
+L'assistant est présent sur le bord droit de chaque page sous votre organisation (`/<org-slug>/...`). Cliquez sur le rail ou appuyez sur `⌘J` / `Ctrl+J` pour l'ouvrir en panneau de chat complet, et faites glisser son bord pour le redimensionner ; votre largeur est mémorisée entre les rechargements. Vous avez besoin de la permission **`agent:use`** pour l'utiliser, sinon le rail est grisé. S'il n'a pas encore été activé pour votre déploiement (une connexion LLM est requise), vous verrez un rail désactivé à la place d'un chat fonctionnel.
+
+## Voir aussi
+
+- [CLI et agents](/fr/agenteye/cli-and-agents)
+- [Queries](/fr/agenteye/queries)
+- [Tableaux de bord](/fr/agenteye/dashboards)
+- [Suite d'évaluation](/fr/agenteye/evaluation-suite)

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

@@ -0,0 +1,54 @@
+---
+title: "Audits : votre analyste de fiabilité automatique"
+description: "Failproof AI Observability détecte les défaillances pour lesquelles vous n'avez jamais défini de règle et vous remet une liste de priorités classées, étayées par des preuves, indiquant précisément quoi corriger."
+---
+
+
+Failproof AI Observability détecte les défaillances pour lesquelles vous n'avez jamais défini de règle et vous remet une liste de priorités classées, étayées par des preuves, indiquant précisément quoi corriger. C'est comme avoir un analyste qui parcourt vos logs chaque nuit et vous dépose un résumé sur le bureau chaque matin.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/C5nHKGQIqZQ?autoplay=1&mute=1&loop=1&playlist=C5nHKGQIqZQ&rel=0&playsinline=1" title="Voir : Identifiez automatiquement où votre agent échoue (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Un tour d'horizon en deux minutes : d'une exécution planifiée à une correction sur laquelle vous pouvez agir.*
+
+![La page Audits : des tâches récurrentes qui analysent vos sessions à la recherche de schémas d'échec, chacune avec une planification et une sensibilité](/agenteye/images/audits.png)
+*Chaque audit est une tâche récurrente qui fouille vos sessions et rédige des recommandations classées et étayées par des preuves.*
+
+## Arrêtez de deviner quoi corriger ensuite
+
+Les alertes détectent les problèmes que vous savez déjà surveiller. Les audits détectent ceux que vous ne connaissez pas encore. Selon un calendrier que vous définissez, un audit parcourt l'ensemble de vos sessions d'agent pour identifier les schémas qui méritent d'être corrigés — vous passez ainsi votre temps à agir sur les résultats plutôt qu'à faire défiler des logs en espérant les repérer vous-même.
+
+Une seule exécution s'attaque aux modes de défaillance qui brisent réellement les agents en production :
+
+- **Clusters d'erreurs** : la même défaillance qui se répète sous une cause racine commune.
+- **Dérive par rapport à une référence** : un comportement qui s'écarte discrètement d'une fenêtre connue comme saine.
+- **Échec d'objectif dans les transcriptions** : des exécutions techniquement terminées mais qui n'ont jamais accompli la tâche.
+- **Mauvaise utilisation des outils** : le mauvais outil, de mauvais arguments, ou des boucles qui consomment des appels inutilement.
+- **Compromis qualité/coût** : là où vous surpayez pour des résultats que vous pourriez obtenir moins cher.
+- **Lacunes de couverture** : des comportements qu'aucune évaluation ni alerte ne surveille.
+
+Vous choisissez l'intensité de l'analyse avec un simple paramètre de **sensibilité** (faible, moyenne ou élevée), de sorte qu'un agent de staging bruyant et un agent de production verrouillé peuvent chacun être calibrés sur le signal souhaité.
+
+## Chaque recommandation est accompagnée de preuves
+
+Vous n'avez jamais à accepter un résultat sur parole. Chaque recommandation cite les sessions exactes dont elle provient ainsi que le SQL qui l'a fait remonter, afin que vous puissiez consulter les preuves et confirmer le problème en un clic plutôt que de reconstituer une affirmation à rebours.
+
+Lorsqu'un résultat concerne un identifiant secret exposé, il va encore plus loin en reliant les événements individuels qu'il a détectés. Cliquez sur l'un d'eux et vous atterrissez sur ce moment précis dans la session, déjà sélectionné — et non en haut d'une longue transcription à faire défiler. Le lien nomme l'événement ; il ne copie jamais le secret détecté dans le résultat, de sorte que la lecture d'un résultat n'est pas un second endroit où votre identifiant est consigné. Si un événement n'est plus disponible parce que la session a dépassé votre fenêtre de rétention, la page l'indique clairement plutôt que de vous laisser vous demander si vous avez cliqué au mauvais endroit.
+
+C'est aussi ce qui garantit l'honnêteté des audits. Le serveur vérifie que chaque session citée existe réellement et **rejette toute recommandation dont les preuves ne tiennent pas**, de sorte que l'audit enquête sans jamais inventer. Ce qui figure sur votre liste est réel, reproductible et classé par importance, avec les gains les plus significatifs en tête.
+
+## Transformer une correction en garde-fou
+
+Corriger un problème ne représente que la moitié du bénéfice. L'autre moitié consiste à s'assurer qu'il ne peut pas revenir discrètement. Chaque résultat comporte **un raccourci en un clic qui crée une alerte de récurrence**, préremplie avec un déclencheur de départ raisonnable que vous pouvez ajuster. Fermez le résultat, activez l'alerte, et la prochaine fois que ce schéma réapparaît, vous êtes notifié au lieu de le redécouvrir lors d'un futur audit.
+
+## Où le trouver
+
+Les audits se trouvent dans le tableau de bord à **`/<org-slug>/audits`** (barre latérale vers *analyze* puis *audits*). La consultation des exécutions et des résultats nécessite **`audits:read`** ; la création, la modification et le triage des audits nécessitent **`audits:write`**. Définissez la portée et la cadence d'un audit, puis cliquez sur **Run now** si vous souhaitez obtenir des résultats immédiatement sans attendre le prochain passage planifié.
+
+## Voir aussi
+
+- [Alerts](/fr/agenteye/alerts) : soyez notifié dès qu'un seuil que vous connaissez déjà est franchi.
+- [Evaluations](/fr/agenteye/evaluations) : notez chaque exécution afin que les régressions de qualité remontent d'elles-mêmes.
+- [Error tracking](/fr/agenteye/error-tracking) : regroupez et suivez les erreurs que vos agents génèrent.
+- [Incidents](/fr/agenteye/incidents) : suivez un problème détecté par un audit jusqu'à sa résolution.

package/.next/standalone/docs-old/fr/agenteye/cli-and-agents.mdx

@@ -0,0 +1,79 @@
+---
+title: "CLI"
+description: "Tout votre déploiement Failproof AI Observability, à portée d'une seule commande."
+---
+
+Tout votre déploiement Failproof AI Observability, à portée d'une seule commande. Vérifiez la production, créez une clé API ou acquittez un incident sans quitter votre terminal, puis scriptez n'importe quelle opération dans votre CI, ou laissez un agent de code s'en charger en langage naturel.
+
+```bash
+pipx install agenteye
+agenteye login --email vous@exemple.com      # un code à 6 chiffres arrive dans votre boîte mail
+agenteye --json sessions --since 24h         # toutes les exécutions d'agents des dernières 24h, les plus récentes en premier
+```
+
+*Le CLI `agenteye` communique avec votre tableau de bord. C'est un outil distinct du collecteur, qui achemine les événements vers le serveur.*
+
+## Tout votre déploiement, une seule commande suffit
+
+Fini de jongler entre les onglets pour répondre à une simple question. Le CLI `agenteye` lit vos données et administre votre organisation depuis un seul binaire : une vérification qui nécessitait auparavant de naviguer dans le tableau de bord devient une ligne que vous pouvez relancer, mettre en alias ou coller dans un runbook. Quatre surfaces sont à votre disposition :
+
+- **Lire vos données :** `sessions`, `events`, `evals` et `errors`, filtrés par plage horaire, agent et environnement.
+- **Gérer votre organisation :** `keys`, `users`, `settings`, `alerts` et `incidents`.
+- **Lancer des analyses :** requêtes SQL enregistrées et un runner `query` ad hoc sur vos données d'événements.
+- **Interroger l'assistant :** `agent ask` accède au même analyste en lecture seule que celui disponible dans le tableau de bord.
+
+Installez-le une fois avec `pipx`, connectez-vous via un code à 6 chiffres reçu par e-mail, et vous êtes prêt. La session dure environ une journée ; relancez `agenteye login` à son expiration. Utilisez-le pour contrôler la production, provisionner une clé ou trier un incident actif, sans jamais ouvrir un navigateur :
+
+```bash
+agenteye errors --since 24h --aggregate      # ce qui est en erreur, regroupé par type
+agenteye incidents list --state firing       # ce qui est en feu en ce moment
+agenteye keys create ci --add events:add     # une clé qui ne peut qu'envoyer des événements, secret affiché une seule fois
+```
+
+Un point important à retenir : les options globales comme `--json` se placent avant la commande. `agenteye --json sessions` est correct ; `agenteye sessions --json` ne l'est pas.
+
+## Scriptez-le, intégrez-le dans votre CI
+
+Chaque commande accepte `--json`, et cela change tout. Le JSON brut part sur stdout tandis que les messages de statut et les avertissements destinés à l'humain vont sur stderr — une capture avec `--json` s'envoie donc directement dans `jq` sans ligne parasite à éliminer. C'est ce qui rend le CLI aussi efficace pour vous à l'invite de commande que pour un agent de code qui parse les sorties :
+
+```bash
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+```
+
+Il est conçu pour fonctionner sans surveillance. Les confirmations interactives sont automatiquement ignorées lorsqu'aucun terminal n'est attaché, rien ne bloque donc dans un pipeline, et chaque commande retourne un code de sortie explicite : `0` succès, `4` non connecté, `5` permission manquante (le message la précise, par exemple `alerts:write`), `3` tableau de bord inaccessible. Un script peut brancher sur un `4` pour se réauthentifier, ou sur un `5` pour vous indiquer exactement ce qu'il faut demander à un administrateur — au lieu d'échouer silencieusement.
+
+## Laissez un agent de code piloter le CLI en langage naturel
+
+Mieux encore, vous ne devriez pas avoir à retenir tous ces drapeaux. La **compétence CLI** est un petit dossier Agent Skill nommé `agenteye-cli` qui apprend à un agent de code tel que Claude Code ou Codex à piloter le CLI à partir de requêtes en langage naturel. Demandez « est-ce que quelque chose est cassé aujourd'hui ? » et l'agent choisit la commande, l'exécute en votre nom et répond en prose.
+
+Pour Claude Code, déposez le dossier `agenteye-cli` dans `~/.claude/skills/` et il est découvert automatiquement. Failproof AI Observability fournit le dossier ; il n'y a rien de supplémentaire à installer, car il se contente de piloter le CLI que vous avez déjà installé. Connectez-vous vous-même au préalable : la compétence ne peut pas effectuer à votre place la connexion par code reçu par e-mail.
+
+Comme l'agent exécute le CLI en votre nom, il peut tout faire dans les limites de votre session — lectures et écritures comprises : créer des clés, modifier des paramètres, résoudre des incidents. La confirmation interactive du CLI ne se déclenche pas pour un agent, c'est pourquoi la compétence est conçue pour indiquer la commande exacte et attendre votre accord avant tout changement. Vous êtes l'étape de confirmation.
+
+```text
+vous   Pourquoi la session run-001 a-t-elle échoué ?
+
+agent  Exécution : agenteye --json events --session-id run-001 --all
+       Le checkout-agent a rencontré une TimeoutError lors de son troisième appel d'outil.
+```
+
+Les lectures restent instantanées, et chaque écriture marque une pause pour vous :
+
+```text
+vous   Donne à CI une clé qui ne peut qu'envoyer des événements.
+
+agent  Ceci va créer une clé API. Je vais exécuter :
+         agenteye keys create ci --add events:add
+       Confirmer ?
+
+vous   oui
+
+agent  Fait. Clé "ci" créée avec events:add uniquement. Le secret est affiché une seule fois, enregistrez-le maintenant.
+```
+
+## En relation
+
+- [Référence CLI](/fr/agenteye/cli) : toutes les commandes, options et structures JSON.
+- [Recettes CLI pour agents](/fr/agenteye/cli-recipes) : patterns `jq` prêts à l'emploi et gestion des codes de sortie.
+- [Compétence agent CLI](/fr/agenteye/cli-skill) : installation et utilisation de la compétence `agenteye-cli`.
+- [Assistant IA](/fr/agenteye/assistant) : l'analyste intégré au tableau de bord que `agent ask` interroge.