> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Audits — détection proactive d'améliorations > AgentEye Audits — documentation sur la détection proactive d'améliorations. Les audits sont des tâches récurrentes qui analysent vos journaux d'agent **à travers les sessions** pour identifier ce qui mérite d'être amélioré. Là où une alerte surveille en quasi-temps réel une métrique que vous connaissez déjà, un audit *enquête* : selon un calendrier que vous définissez, il effectue un contrôle de politiques déterministe sur la fenêtre temporelle, puis confie vos sessions à un **agent de fiabilité IA** — l'agent interroge les données lui-même, lit les transcriptions suspectes et (si besoin) exécute de petits scripts d'analyse, avant de rédiger des **recommandations d'amélioration** avec les preuves à l'appui. Utilisez les audits pour répondre à la question « que dois-je corriger ou améliorer dans mes agents ? » — et les alertes pour être notifié dès qu'un seuil précis est franchi. Chaque amélioration renvoie aux sessions et requêtes exactes qui la sous-tendent, et un seul clic crée une alerte préremplie pour intercepter les récurrences. L'interface du tableau de bord est accessible via **`//audits`** (barre latérale → *analyser* → *audits*), conditionnée par les permissions `audits:read` / `audits:write`. *** ## Déroulement d'une exécution Chaque exécution comporte deux couches : un socle déterministe et une investigation agentique. ### 1. Le contrôle de politiques (déterministe) Avant l'exécution de tout modèle, l'audit lance un ensemble de **contrôles SQL par politiques** sur la fenêtre : des requêtes agrégées délimitées qui signalent les patterns problématiques connus et indiquent *combien* d'événements / *quelles* sessions ont correspondu — jamais le texte correspondant lui-même. Le catalogue inclut : * **Fuites de secrets / identifiants** dans les charges utiles d'événements — clés d'accès AWS, clés API `sk-…`, clés privées PEM, tokens JWT / bearer et assignations de type `KEY=…`. * **Marqueurs d'injection de prompt** — « ignore previous instructions », « reveal your system prompt » et formulations similaires. * **Données personnelles (PII)** — numéros au format SSN (heuristique). * **Refus de permission d'outil** et **boucles de dépassement d'appels d'outils**. Les correspondances de politiques sont persistées en tant que résultats (type `policy`) qui **apparaissent toujours** (ils ne sont jamais écrêtés par le plafond par exécution), et sont transmis à l'agent IA comme pistes de départ. Cette couche ne nécessitant aucun modèle, un audit produit ses signaux de sécurité les plus importants même si l'agent IA est indisponible. ### 2. L'investigation agentique (IA) L'audit lance ensuite un **agent de fiabilité autonome** (le même service Claude Agent SDK qui alimente l'assistant du tableau de bord, avec un prompt spécifique aux audits). Compte tenu du **périmètre** de l'audit (agents sélectionnés × environnements) et de la **fenêtre temporelle**, l'agent : * exécute des requêtes SQL en lecture seule sur vos tables d'analytique, * lit quelques transcriptions de sessions représentatives, * rédige et exécute optionnellement de courts **scripts Python dans un sandbox isolé en pod** (sans réseau, sans accès au système de fichiers, secrets supprimés) pour les analyses que SQL ne peut pas exprimer — regroupement d'erreurs, calcul de distributions, balayage des charges utiles déjà récupérées, * et consigne chaque **amélioration** bien étayée qu'il découvre. Il explore plusieurs axes d'investigation — regroupement d'erreurs, dérive par rapport à une référence, échecs d'objectifs dans les transcriptions, mauvaise utilisation des outils, compromis qualité/coût et lacunes de couverture — selon la **sensibilité** de l'audit (faible / moyenne / élevée). Chaque amélioration **doit citer des preuves** : les identifiants de session que l'agent a réellement inspectés et/ou le SQL qu'il a exécuté. Le serveur vérifie que les sessions citées existent et **rejette toute amélioration sans preuve subsistante**, ainsi l'agent enquête sans jamais inventer. Chaque amélioration comporte : * une **recommandation** (la modification concrète à apporter — un ajustement de prompt, une correction de schéma d'outil, une politique de réessai, un garde-fou, une couverture d'évaluation accrue), * un **impact attendu** et une estimation de l'**effort** (faible / moyen / élevé), * une **magnitude** — `big` (un opérateur devrait être notifié), `medium` (à inclure dans le rapport d'exécution) ou `small` (contexte du tableau de bord), * une **empreinte** stable (dérivée de la catégorie et du périmètre du problème, *pas* des sessions de cette exécution) permettant de suivre le même problème d'une exécution à l'autre même si les preuves changent, * et, lorsqu'un observateur déterministe simple pourrait détecter une récurrence, une **alerte suggérée** créable en un seul clic. > **La couche IA est optionnelle mais recommandée.** Si aucun agent IA n'est configuré pour le pipeline d'audits, les exécutions se déroulent quand même, persistent les résultats de politiques, et signalent honnêtement « analyse indisponible » pour la couche agentique plutôt que de passer silencieusement. ### Modes d'échec Les améliorations sont classées dans le **catalogue de modes d'échec** durable de votre organisation (ou proposent un nouveau mode). Les modes confèrent aux patterns une identité stable à travers les exécutions et permettent un suivi des récurrences sur le long terme. ## Cycle de triage Sur la page d'un résultat (`/audits//findings/`) : | Action | Effet | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **acknowledge** | Garde le résultat visible mais divise sa priorité par deux. | | **resolve** | Le marque comme corrigé. Si le pattern réapparaît réellement par la suite, il se rouvre en tant que **new** — une régression est ainsi signalée clairement, sans être silencieusement fondue dans l'historique. | | **mute** / **dismiss** | Suppression durable : l'empreinte du pattern est mémorisée et ne remonte plus jamais, même entre les exécutions. Utilisez mute pour « connu, accepté » ; dismiss pour « non pertinent ». | | **reopen** | Lève la suppression / résolution et remet le pattern dans le classement. | Le bruit à faible signal est contrôlé par audit via un plafond de résultats par exécution (`top_k`) sur les améliorations agentiques. Les résultats de politiques contournent ce plafond (ils sont pertinents pour la sécurité et toujours affichés). Tout ce qui est écrêté par le plafond est comptabilisé dans les statistiques de l'exécution — rien n'est supprimé silencieusement. ## Planification * **Cadence** (`schedule_interval_secs`) : de toutes les heures à une fois par semaine ; **quotidien par défaut**. Les audits sont délibérément moins fréquents que les alertes — une investigation agentique analyse des fenêtres entières et s'exécute pendant plusieurs minutes. * **Fenêtre** : soit un lookback glissant fixe (p. ex. « chaque exécution analyse les 7 derniers jours »), soit **depuis la dernière exécution** (par défaut) — chaque exécution reprend là où la précédente réussie s'est terminée, avec un léger chevauchement pour ne jamais manquer les événements en limite. * La prochaine exécution est planifiée un intervalle complet après la **fin** de la précédente, de sorte qu'une exécution lente n'empile jamais une seconde exécution concurrente du même audit. * **Exécuter maintenant** sur la page de l'audit la rend immédiatement due. ## Sélection du modèle Lors de la création d'un audit, vous pouvez choisir le modèle utilisé par l'investigation parmi la **liste des modèles configurés par votre opérateur** pour le service d'agent. Avec un seul modèle configuré, le sélecteur l'affiche en légende ; avec plusieurs, vous choisissez. Laisser ce champ vide utilise le modèle par défaut configuré. ## Notifications Lorsqu'une exécution remonte de **nouveaux** résultats, l'audit notifie les canaux configurés de votre organisation — la même porte `alerts.enabled_channels` et les mêmes paramètres qu'utilise le pipeline d'alertes : * **Slack** — un résumé des nouveaux éléments significatifs (`big`) avec un lien direct. * **Email** — un **rapport d'audit** structuré listant les nouvelles améliorations (par gravité décroissante, recommandations par élément, lien direct), envoyé lorsque l'audit dispose d'un canal **email** associé et qu'il y a au moins un nouveau résultat. Les résultats récurrents mais connus ne génèrent pas de nouvelle notification. ## Référence de configuration Les définitions d'audit sont gérées dans le tableau de bord (`/audits/new`) ou via l'API. Les paramètres par audit incluent la cadence et la fenêtre de planification, le périmètre (`{"environments": [...], "agent_ids": [...]}`), la sensibilité (`low` / `medium` / `high`), les canaux de notification, le plafond de résultats par exécution (`top_k`) et le modèle (via `llm_budget.model`). Les paramètres serveur au niveau opérateur (délais d'expiration, sandbox, URL du service d'agent) sont documentés dans [deployment.md](/fr/agenteye/deployment). ## API Tous les endpoints sont limités à l'organisation et suivent l'authentification standard par clé bearer (voir [api-keys.md](/fr/agenteye/api-keys)). | Endpoint | Permission | Objet | | ------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------- | | `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | Lister / créer des définitions d'audit. | | `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Consulter, modifier, supprimer un audit. | | `POST /audits/:id/run` | `audits:write` | Rendre l'audit immédiatement dû. | | `GET /audits/:id/runs` | `audits:read` | Historique des exécutions (fenêtre, statut, statistiques, nombre de résultats). | | `GET /audits/findings` | `audits:read` | Résultats à l'échelle de l'organisation, filtrables par `audit_id`, `status` ; triés par priorité. | | `GET /audits/findings/:fid` | `audits:read` | Détail complet d'un résultat (recommandation, preuves, priorité). | | `POST /audits/findings/:fid/status` | `audits:write` | Triage : `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | Pour les cas « l'audit s'est exécuté mais n'a rien trouvé », « le sandbox de code est désactivé » et « l'email d'audit n'a pas été délivré », consultez [troubleshooting.md](/fr/agenteye/troubleshooting#audits).