Files
Support-Agent/docs/agents/enquete-a-la-demande.md
T
maximeandClaude Opus 5.5 446fde3192 Events: read-event skill to consult the base (D-085), cases renamed events E-xxx (D-086)
- read-event: map and index first, then the card of close events only,
  then their data with the reading tools; never all cards at once.
  Diagnostic agent, critiquer-lot and builder point to it; the index
  header too. Signature length: about 250 characters, a guideline.
- "Cas" becomes "event": events/E-xxx/event.md, skills new-event,
  review-event, anonymize-event.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 07:25:29 +01:00

18 KiB
Raw Blame History

Enquête à la demande : un agent qui explique un événement de mesure

  • Date : 2026-10-13.
  • Statut : exploratoire. Rien n'est construit ; ce document fixe une direction et un démarrage par étapes. Décision liée : D-042 (docs/decisions.md).
  • Place : une approche auxiliaire du rapport docs/agents/rapport-exploratoire.md (D-027), plus simple, qui ne le remplace pas. Les deux partagent le même cadre (§3).
  • Principe de travail : commencer simple, ne complexifier que si le besoin apparaît.

1. Objet

Le diagnostic actuel porte sur les états de la caméra (batterie, disque, 4G, température). Le cas d'usage suivant porte sur les données qu'elle mesure : positions et déplacements des cibles, état de la compensation, qualité des références. On monte d'un cran : il faut départager un mouvement réel de l'ouvrage d'un artefact de mesure.

Le problème. Le client voit toutes les données mais ne sait pas les interpréter. Lors d'un événement sur le terrain, il ne peut pas dire s'il est problématique ou anodin. Aucune méthode n'aide à ce diagnostic : il contacte le support, qui enquête à la main.

Le but. Répondre au client automatiquement, avec preuves et explications, pour qu'il n'ait plus à solliciter le support.

Le moyen. Quand un événement pose question, un agent (Claude, via l'API d'Anthropic) reçoit la question et enquête avec un harnais : connaissance métier, outils en lecture, cas résolus. Il rend un diagnostic dont chaque preuve est traçable.

Ce qui distingue cette approche du rapport exploratoire

Rapport exploratoire (D-027) Enquête à la demande (ce document)
Déclenchement Chaque jour, pour chaque station Un événement qui pose question
Unité de travail Une session par (agent, station, jour) Une session par question
Rôle de l'agent Annoter la couleur du jour, capter l'inconnu Expliquer un événement précis
Données États de la station (Energy d'abord) Données de mesure (déplacements), plus les états en contexte
Infrastructure Cron, SQL, flotte entière Un script lancé à la main au départ

Les docs AIMsight décrivent déjà ce processus : le support query workflow (§13 de AIMsight_agentic_support_project_context.md) et l'explainer d'événements (§4 de AIMsight_reference_quality_event_explainer_roadmap.md). La différence : l'agent mène l'enquête lui-même au lieu d'expliquer un dossier préparé d'avance.


2. Choix retenus

Question Choix Raison
Qui reçoit le diagnostic Le support d'abord (il relit, corrige et envoie), puis le client directement pour les classes sans enjeu pour l'ouvrage Asymétrie du risque : dire « anodin » à tort est plus grave qu'une fausse alerte (§5)
Qui déclenche l'enquête Le support à la main, puis un bouton client sur le site, puis une détection automatique Tester sur de vrais tickets sans toucher au site ; les critères automatiques viendront des tickets, pas d'un seuil inventé
Forme de l'agent Un enquêteur avec des outils typés (approche 2, §8) Il creuse ce qui est utile, et chaque preuve renvoie à un appel d'outil
Sources de données Pas encore connues (CSV, HDF5, images, SQL) : les outils sont définis par famille de preuves, pas par format Comme l'API indépendante de l'estimateur de la roadmap (§10)
Cadre technique Celui de D-027 : harnais maison, Tool Runner du SDK anthropic, agent en dossier déclaratif Un seul cadre pour les deux approches
Modèle Opus 5.5 (claude-opus-5-5), niveau d'effort fixé explicitement (son défaut est medium) À mesurer sur les premiers rejeux

3. Le harnais

L'agent est un dossier déclaratif, comme prévu par D-027 (emplacement proposé : agents/enquete/agent.md). Il a trois pièces.

3.1 La connaissance (prompt système, mis en cache)

  • Les règles communes : vocabulaire confirmed / strongly supported / consistent with / possible / insufficient evidence / not observed ; fait observé ≠ fait dérivé ≠ hypothèse ; aucun seuil inventé ; rien construit sur inlier binaire ; sigma0 jamais suffisant seul ; mode commun ≠ mouvement structurel (règles de CLAUDE.md).
  • La méthode, par sections ciblées des docs AIMsight, pas les fichiers entiers :
    • la chaîne de dépendance (§4 du contexte support) ;
    • les familles d'hypothèses (§12) ;
    • les classifications de l'explainer (§4.3 de la roadmap) ;
    • le workflow en 8 étapes (§13).
  • Des pointeurs vers docs/, qui reste la seule source : docs/domaine/colonnes-des-deplacements.md, puis les notes de domaine à venir.
  • Volume : de l'ordre de 30 à 60 k tokens, à mesurer. Mis en cache, ce bloc est relu à chaque tour pour 0,20 $ par million de tokens.

3.2 Les outils (lecture seule)

On commence petit. Chaque outil répond « source indisponible » quand la donnée manque ; l'agent le reporte dans ses inconnus au lieu de conclure. Les outils de calcul renvoient des valeurs, pas des verdicts : un seuil de décision ne s'invente pas (§9).

Outil Rôle
inventory(station, fenêtre) Ce qui existe : points, références, colonnes, sources, trous de mesure (étape 3 du workflow)
get_series(station, colonnes, fenêtre) Un résumé chiffré compact et un graphique en image. Un LLM lit mal des centaines de lignes de nombres, il lit bien un graphique
compare_before_after(station, colonnes, instant) Par colonne, avant et après l'instant : écart, persistance, retour à la normale (UC5 du contexte support)
common_mode(station, fenêtre) Part des cibles touchées, accord de signe, score de mode commun (famille Spatial response, §4.2 de la roadmap) : ce qui sépare l'ouvrage de la compensation
get_system_health(station, fenêtre) Les couleurs du jour déjà livrées (Energy, Storage, Cellular, Temperature) : le bas de la chaîne de dépendance, réutilisé tel quel depuis src/<domaine>/day_color.py
get_image(station, instant) La photo de la caméra, que l'agent regarde (l'API accepte une image dans un résultat d'outil). Brouillard, neige, végétation, cible masquée : ce qu'aucun script ne voit simplement. Seulement si une source d'images existe
submit_diagnosis(...) La fin obligatoire, au format du §5

Opus 5.5 refuse qu'on force l'appel d'un outil (tool_choice any ou tool). submit_diagnosis est donc appelé sur instruction, avec un schéma strict (strict: true).

Volontairement absents (comme dans D-027) : SQL libre, Bash, accès web, bac à sable de code (§8).

3.3 La base d'events

  • Un fichier par cas résolu : la question du client, les preuves, le brouillon de l'agent, le diagnostic final validé par le support, l'écart entre les deux. C'est la forme prévue par le contexte support (§13 étape 8, §17).
  • Au début, tous les events tiennent dans le prompt, en cache : pas d'outil de recherche. Un outil find_cases viendra quand il y en aura trop.
  • Premier cas : Barcelone (§15 de la roadmap, §16.1 du contexte support), rédigé d'après les docs comme cas documentaire, sans données.
  • La base se remplit seule : une enquête validée par le support devient un event (§5).

4. Déroulé d'une enquête

Lancement (déclenchement par le support)

python3 agents/enquete.py WEISSHORN 2026-10-02T08:00 --points target_06 --question ticket.txt
  • Le support donne la station, l'instant et les points : plus fiable que de les faire deviner à l'agent dans le texte du client. Le texte du client part tel quel dans le premier message.
  • Le code ajoute la fenêtre par défaut : de quelques jours avant l'événement jusqu'à l'heure de la question.
  • Borne dans le temps : l'enquête lit les données après l'événement (c'est la seule façon de savoir s'il est revenu à la normale), mais rien après l'heure de la question. Un ticket passé se rejoue donc à l'identique, ce qui permet de juger l'agent.

Les étapes demandées à l'agent (d'après le §13 du contexte support)

  1. Inventaire (inventory) : ce qui est disponible, ce qui manque, et ce qui, en manquant, limite le diagnostic.
  2. Le bas de la chaîne d'abord (get_system_health) : une station coupée ou une liaison tombée explique un trou ou un saut sans que l'ouvrage y soit pour rien.
  3. Les faits (compare_before_after, common_mode, get_series, get_image) : amplitude, persistance, retour à la normale, nombre de cibles touchées.
  4. Les hypothèses candidates, prises dans les familles du §12 et classées sur les seules preuves.
  5. La réfutation de l'hypothèse principale : chercher la preuve qui la contredirait. Exemple : on pense à un mouvement de l'ouvrage. Les références ont-elles bougé ? La transformation a-t-elle sauté ? Toutes les cibles ont-elles bougé ensemble ? Cette tentative est obligatoire et figure dans la sortie.
  6. submit_diagnosis. « Rien d'anormal » est une conclusion valable.

Garde-fous (tenus par le code, pas par le modèle)

  • Journal de session : chaque appel d'outil est enregistré avec ses entrées et sa sortie, sous un identifiant.
  • Preuves vérifiées : chaque preuve du diagnostic cite l'identifiant d'un appel du journal. Le code refuse un diagnostic qui cite un identifiant inexistant, ce qui empêche les faits inventés.
  • Budget : un plafond par enquête, en tokens et en appels. S'il est atteint, l'agent conclut avec ce qu'il a (insufficient evidence si besoin) plutôt que d'être coupé en plein raisonnement.

5. Sortie et relecture

Ce que rend submit_diagnosis (d'après §14-15 du contexte support)

Champ Contenu
classification Une liste fermée : mouvement de l'ouvrage, événement de compensation (caméra ou références), solution de références faible, parallaxe ou modèle inadapté, cible dégradée, problème système (acquisition, transport), rien d'anormal, indéterminé. Classes du §4.3 de la roadmap, complétées du bas de la chaîne
affected_layer La couche de la chaîne de dépendance
qualifier confirmed … insufficient evidence
evidence Les faits, chacun avec l'identifiant de l'appel d'outil qui le prouve
refutation Ce qui a été vérifié contre l'hypothèse principale, et le résultat
alternatives Les autres explications, et pourquoi elles ne sont pas écartées
unknowns Les preuves manquantes qui limitent la conclusion
next_check La vérification suivante la plus discriminante
client_draft Un brouillon de réponse au client : court, sans jargon ni mécanisme, comme la vue client

La règle d'asymétrie (tenue par le code)

Le brouillon ne peut dire « sans conséquence pour l'ouvrage » que si :

  • l'explication « artefact » (compensation, cible, système) est au moins strongly supported ;
  • et le mouvement de l'ouvrage a été réfuté explicitement.

Sinon, le code remplace la conclusion du brouillon par une formule neutre (« événement en cours d'analyse par notre support »). La règle sert dès le départ (le support ne recopie pas une fausse assurance) et délimitera plus tard ce qui part directement au client.

La relecture par le support

  • Un dossier par enquête (emplacement proposé : agents/enquetes/<date>_<station>/) : le journal des appels, le diagnostic en JSON, une page HTML de relecture (diagnostic, preuves avec leurs graphiques, brouillon client).
  • Le support relit, corrige le brouillon et l'envoie lui-même, puis remplit une courte validation : accepté tel quel, ou corrigé (en quoi), et le diagnostic final.
  • Une enquête validée devient un event de la base (§3.3), sans autre étape.
  • Mesures qui décident de la suite : le taux d'accord entre l'agent et le support (classification, qualificatif, brouillon envoyé tel quel ou réécrit), puis le temps gagné par ticket.
  • Langue, par défaut : la partie technique en anglais (termes AIMsight), le brouillon dans la langue du client.

6. Démarrage par étapes

Deux axes à ne pas confondre : qui déclenche (le support, puis le client, puis la détection automatique) et qui reçoit (le support, puis le client pour certaines classes). Chaque étape répond à une question, et sa réponse décide si la suivante est nécessaire.

  1. Le harnais sur les données existantes. Cas d'usage UC3 (« pourquoi pas de données entre X et Y ? ») rejoué sur les coupures connues : les 11 coupures de la liaison de NORDEND, les incidents isolés de WEISSHORN. Question : la tuyauterie tient-elle (preuves vérifiées, réfutation, page de relecture), et à quel coût ? N'attend pas les données de déplacement.
  2. Rejeu d'events de déplacement résolus, dès qu'un export contient un événement expliqué (Barcelone idéalement). On branche compare_before_after et common_mode sur les CSV. Question : l'agent retrouve-t-il le diagnostic de l'expert, sans sur-conclure ?
  3. Le support s'en sert sur ses vrais tickets. Question : quel taux d'accord, quel temps gagné ?
  4. Le bouton client sur le site : la demande arrive au support déjà enquêtée. Question : les clients s'en servent-ils, et pour quels événements ?
  5. Réponse directe au client pour les classes sans enjeu pour l'ouvrage, si l'accord mesuré le justifie. Ensuite seulement, la détection automatique, sur des critères tirés des tickets réels. C'est là que les deux approches se rejoignent : une surveillance quotidienne (D-027) qui repère un événement peut lancer une enquête.

7. Coût, risques, prérequis

Coût (hypothèse, à mesurer à l'étape 1)

Prix d'Opus 5.5 : 4 par million de tokens en entrée, 20 en sortie, 0,20 en lecture de cache, 5 en écriture de cache (1,25 × l'entrée, durée de vie de 5 minutes). Une image de 1280 × 720 coûte environ 1 200 tokens.

Hypothèse par enquête : 45 k tokens de connaissance, une dizaine de tours, 50 k tokens nouveaux (résultats d'outils, images), 20 k tokens de sortie (raisonnement compris). Les tickets étant espacés, le cache est froid au début de chaque enquête.

Poste Calcul Coût
Écriture du cache (connaissance) 45 k × 5 $/M 0,23 $
Écriture du cache (résultats d'outils, images) 50 k × 5 $/M 0,25 $
Lectures du cache 10 tours × ~60 k × 0,20 $/M 0,12 $
Sortie 20 k × 20 $/M 0,40 $
Par enquête ~1 (0,5 à 2)

Le volume suit celui des tickets : le coût n'est pas limitant face au temps d'un ingénieur support.

Risques

Risque Parade
Fausse assurance (« anodin » à tort) Règle d'asymétrie tenue par le code (§5) ; relecture par le support jusqu'à l'étape 5
Faits inventés Chaque preuve cite un appel du journal, vérifié par le code (§4)
Sur-conclusion sur des données incomplètes inventory en premier ; unknowns obligatoire ; insufficient evidence admis
Graphique mal lu Résumé chiffré à côté de l'image ; calculs déterministes dans les outils
Trop peu de cas pour juger Rejeu des tickets passés ; chaque enquête validée devient un event
Données client chez Anthropic Accepté (D-027) ; conditions de conservation à valider avec la direction

Prérequis

  • Étape 1 : une clé API Anthropic (la même que pour D-027).
  • Étape 2 : un export de déplacements avec un événement connu et son explication.
  • get_image : une source d'images, peut-être l'API REST de la caméra (attendue pour le dev container, D-038).

8. Options écartées

Option Raison
1. Dossier de preuves, puis rédaction (l'explainer de la roadmap, un seul appel au LLM) L'agent ne peut pas creuser (autre cible, autre période, image) ; le dossier doit tout prévoir d'avance. Il reste le premier message de l'enquête, en version réduite
3. Enquêteur avec un bac à sable de code Calculs non relus, risque de seuils inventés, difficile à auditer devant un client inquiet pour son ouvrage. Reste un recours si l'agent lit mal les séries
Réponse directe au client dès le départ Le risque de fausse assurance serait d'emblée chez le client
Détection automatique dès le départ Il faudrait fixer des critères sur les déplacements avant d'avoir vu un seul ticket
L'agent extrait station, instant et points du texte du client Source d'erreur évitable tant que le support lance l'enquête ; à revoir avec le bouton client, qui fournit ces champs
Recherche d'events (RAG) dès le départ Inutile tant que les events tiennent dans le prompt

9. Questions ouvertes

  1. Sources de données : lesquelles (CSV, HDF5, images, SQL), et quand ?
  2. Premier cas avec données : Barcelone ou un autre événement expliqué ?
  3. Liste des classifications : à valider avec l'expert, avec la façon de nommer chaque classe pour le client.
  4. Seuils des outils de calcul : compare_before_after et common_mode renvoient des valeurs ; d'où viendront les seuils qui disent « saut » ou « mode commun » (expert, docs AIMsight, cas résolus) ?
  5. Critère d'ouverture au client : quel taux d'accord avec le support, sur combien de tickets ?
  6. Page de relecture : son format, et la forme de la validation par le support.
  7. Volume de tickets : combien par semaine (coût total, cache froid ou non) ?
  8. Emplacement du code et des dossiers d'enquête : agents/enquete/ et agents/enquetes/ proposés ; versionner les dossiers d'enquête (données client, dépôt privé, D-014) ?

Annexe : références

  • docs/aimsight/AIMsight_agentic_support_project_context.md : §4 (chaîne de dépendance), §10 (règles épistémiques), §12 (familles d'hypothèses), §13 (support query workflow), §14-15 (format de réponse), §16-17 (cas de régression), §23 (cas d'usage UC1 à UC8).
  • docs/aimsight/AIMsight_reference_quality_event_explainer_roadmap.md : §4 (explainer, familles de preuves, classifications), §10 (API indépendante de l'estimateur), §15 (Barcelone).
  • docs/agents/rapport-exploratoire.md : le cadre commun (D-027).
  • docs/decisions.md : D-014 (dépôt privé), D-020 (destinataires en couches), D-027 (couche d'agents), D-038 (dev container), D-042 (cette direction).
  • API Claude (fonctionnalités citées) : Tool Runner du SDK anthropic, outils stricts (strict: true), images dans un résultat d'outil, prompt caching, task budgets.