Files
Support-Agent/docs/agents/rapport-exploratoire.md
maximeandClaude Opus 5.5 c3e9eef4e4 Move the VERMONT CSVs into data/VERMONT
New data will be added per station without mixing with the working set.
All scripts now default to data/VERMONT/; docs and D-029 follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 09:10:35 +02:00

20 KiB
Raw Permalink Blame History

Cadre d'agents de diagnostic : rapport exploratoire

  • Date : 2026-10-12.
  • Statut : exploratoire. Rien n'est construit ; ce rapport fixe une direction et une première étape. Décision liée : D-027 (docs/decisions.md).
  • Principe de travail : commencer simple, ne complexifier que si le besoin apparaît. Le corps du rapport décrit le socle ; les règles détaillées proposées pendant le brainstorm sont rangées en annexe A, comme pistes à revoir étape par étape pendant la réalisation.

1. Objet

Aujourd'hui, le diagnostic (domaine Energy) est fait par des scripts déterministes : DAILY_BATTERY_STATE et DAILY_BATTERY_TREND, combinées en une couleur par jour. Ils sont justes « dans la majorité des cas » (D-005), mais ils ne voient que ce que leurs règles décrivent.

L'idée explorée : ajouter des agents qui utilisent l'intelligence interprétative d'un LLM pour capter une palette plus large de problèmes. Chaque agent a accès aux données qui le concernent, à ses instructions et à sa base de connaissance métier. Exemple : un agent tourne chaque jour, lit les nouvelles données, les interprète, puis notifie le client ou le support selon ses conclusions.

Ce rapport décrit le cadre qui accueillera ces agents : l'infrastructure nécessaire et les choix stratégiques.

Ce que l'agent doit capter que les scripts ne captent pas

Deux missions, retenues par l'utilisateur :

  1. Les anomalies inconnues : des formes qu'aucune règle ne décrit (dérive lente, palier, comportement inhabituel). L'agent voit que « ça ne ressemble pas à d'habitude ».
  2. Les cas limites des règles : les jours où une règle est muette (UNKNOWN), probablement fausse, ou endormie par l'accoutumance (point ouvert de MOVING_AVERAGE_7_DAYS_DROP).

Hors objectif pour l'instant : croiser les métriques et les domaines, ou expliquer le contexte (météo, saison). L'agent le fera peut-être en passant, mais on ne le jugera pas là-dessus.

Ce qui change dans le projet

D-003 refusait tout LLM et écartait explicitement l'agent de synthèse prévu par les docs AIMsight. Ce rapport le remplace en partie :

  • la couche déterministe ne change pas : pas de LLM, bibliothèque standard, embarquable, couleur du jour reproductible ;
  • une couche d'agents s'ajoute côté serveur. Un LLM ne tourne pas sur l'embarqué solaire d'une station.

Les docs AIMsight décrivaient déjà cette organisation : analyseurs déterministes, puis faits, puis couche de raisonnement (§18 de AIMsight_agentic_support_project_context.md), et le support comme mécanisme de découverte de nouvelles règles (§21).


2. Choix retenus

Question Choix Raison
Rôle de l'agent face aux scripts Un mélange : il interprète les faits des règles, explore avec ses outils (de façon traçable) et propose des règles candidates Les scripts restent le socle ; l'agent élargit
Qui l'agent notifie Le client et le support Choix de l'utilisateur
Données envoyées à une API externe Oui (API Claude d'Anthropic) Modèle de pointe, sans infrastructure GPU
Découpage des agents (par domaine, station, rôle…) Ouvert : trop tôt pour décider Le cadre ne le fige pas (§4)
Taille de la flotte Moins de 50 stations Le coût du modèle n'est pas limitant (§7)
Accès aux données Requêtes SQL sur la base des stations Pas d'export manuel ; tout l'historique est accessible
Hébergement Harnais maison sur un serveur AIMsight (approche A, §3) Le plus simple et le plus contrôlable à cette échelle

3. Architecture d'ensemble

Station (embarqué) ──mesures──▶ Base SQL de la plateforme
                                     │  lecture seule
 Couche déterministe (inchangée, bibliothèque standard, embarquable)
   DAILY_BATTERY_STATE, DAILY_BATTERY_TREND… ──▶ faits + couleur du jour
                                     │
 Couche agents (nouveau, serveur AIMsight, Python + API Claude)
   runner quotidien ──▶ une session par (agent, station, jour)
   outils en lecture ──▶ interprétation ──▶ conclusions structurées
                                     │
 Journal des conclusions
   ├──▶ notifications client / support
   └──▶ règles candidates ──▶ revue humaine ──▶ nouveau script

Deux règles structurantes :

  • L'agent annote, il ne réécrit pas. Le verdict déterministe (couleur du jour) n'est jamais modifié par l'agent. Son avis est une notification séparée, marquée « agent », qui peut contredire le verdict (« la couleur est Green, mais… »). Ainsi la couleur reste reproductible et traçable, et l'avis de l'agent forme une couche à part, qu'on peut évaluer.
  • Boucle de découverte. Quand l'agent signale à répétition une même forme d'anomalie, elle devient une règle candidate. Un humain l'examine, puis la code en script déterministe. À terme, l'agent rend les scripts plus complets.

Hébergement retenu : un harnais maison (approche A)

Un script Python appelle l'API Messages de Claude avec le Tool Runner du SDK anthropic, qui gère la boucle de l'agent. Les outils sont nos fonctions Python ; la base SQL n'est jamais exposée à l'extérieur. Une seule dépendance nouvelle (anthropic), de l'ordre de quelques centaines de lignes de code.

Les deux autres approches étudiées sont en §8 (options écartées). Si la définition d'un agent reste un dossier déclaratif (§4), elle est portable vers Managed Agents : on pourra migrer si l'orchestration maison devient pénible.


4. Anatomie d'un agent

Un agent est un dossier déclaratif, lu par le runner. Le découpage reste ouvert : la station (ou le domaine) qu'un agent couvre est un paramètre d'exécution, pas une structure du cadre. On peut donc essayer plusieurs découpages sans rien reconstruire.

agents/                 emplacement proposé, à fixer au pilote
  _commun.md            règles de tous les agents : traçabilité, vocabulaire
                        (consistent with…), fait ≠ hypothèse, lecture seule,
                        interdiction d'inventer un seuil de validité
  energy/
    agent.md            en-tête : modèle, périmètre (métriques), outils
                        autorisés, fichiers de connaissance
                        corps : mission et méthode de l'agent

Base de connaissance : des pointeurs, pas des copies. agent.md liste les fichiers de docs/ à charger (notes de domaine, fiches des règles, cas annotés, guide), qui restent la seule source. Pour Energy, cela représente environ 56 Ko, soit 15 à 20 k tokens. Tout tient dans le prompt système, mis en cache : les sessions suivantes du même jour le relisent presque gratuitement. Pas de recherche documentaire (RAG) ni de base vectorielle : inutile à cette taille.

Règles non négociables : celles du projet (CLAUDE.md) s'appliquent aux agents. Chaque conclusion est traçable, avec le vocabulaire confirmed / strongly supported / consistent with / possible / insufficient evidence / not observed. Pas de pseudo-probabilités, lecture seule, aucun seuil inventé.

Outils

Typés, tous en lecture sauf notify. On commence avec trois outils ; les autres s'ajoutent quand le besoin apparaît.

Outil Rôle Quand
get_series(station, métrique, début, fin) Séries horaires, sur une fenêtre bornée, jamais au-delà du jour J Étape 1 (CSV), puis SQL à l'étape 2
run_rule(règle, station, fenêtre) Les analyses déterministes existantes et leurs faits Étape 1
notify(...) La seule action : écrire une conclusion dans le journal Étape 1 (fichier), puis table SQL
code_execution + appel programmatique de get_series L'agent écrit du Python qui lit les séries dans un bac à sable et calcule (statistiques, comparaison au passé). Seul le résultat entre dans son contexte Si l'agent lit mal les nombres bruts
plot(station, métriques, fenêtre) Une image du graphique, que l'agent regarde (Claude lit les graphiques) Si l'image aide à repérer l'inhabituel
get_station_meta(station) Alimentation (solaire ou secteur), installation, configuration Avec l'accès SQL
get_history(station, jours) Les conclusions passées de l'agent et les retours du support Quand l'agent tourne chaque jour (étape 2)

Raison de code_execution : un LLM lit mal un long tableau de nombres. Mieux vaut lui donner du calcul et une image qu'un tableau de 720 lignes. Le bac à sable tourne chez Anthropic, donc les séries y transitent, ce qui est cohérent avec l'accord pour une API externe. Si cela gêne un jour, on le remplace par un bac à sable local sans changer le reste.

Volontairement absents :

  • SQL libre : on ne pourrait ni l'auditer ni le borner ;
  • Bash et accès web ;
  • mémoire libre de l'agent : l'historique des conclusions suffit pour commencer.

5. Exécution et notification (socle)

  • Une session par (agent, station, jour), indépendante des autres. Le premier message est préparé par le code : station, jour J, faits déterministes du jour.
  • Causalité garantie par les outils : une session du jour J ne lit aucune donnée postérieure à J. On peut donc rejouer le passé comme s'il était en direct. C'est la base de l'évaluation.
  • Chaque session se termine par une conclusion, y compris « rien à signaler », qui compte dans l'évaluation.
  • Chaque preuve citée renvoie à un appel d'outil réel de la session, ce qui empêche les faits inventés.

Le détail (journal, déduplication, contrôles de notify, politique de destinataire, affichage sur le site) est en annexe A, à reprendre étape par étape.


6. Démarrage par étapes

Chaque étape répond à une question, et sa réponse décide si l'étape suivante est nécessaire.

Étape 1 : pilote manuel sur l'historique de VERMONT

  • Périmètre : un agent (Energy), une station (VERMONT), les CSV de data/VERMONT/. Pas de SQL, de cron ni de site.
  • Lancement : à la main, sur un jour ou une plage rejouée, par exemple python3 agents/run.py energy VERMONT 2026-09-01 2026-10-09.
  • Outils : get_series, run_rule, notify (qui écrit dans un fichier journal).
  • Question : l'agent apporte-t-il quelque chose que les règles n'ont pas, à quel coût, avec combien de fausses alertes ? Par exemple : voit-il venir les coupures du 27/09 plus tôt que la couleur du jour ? Signale-t-il les jours UNKNOWN ou l'accoutumance ?
  • Évaluation : relecture humaine du journal, jour par jour, face aux cas annotés par l'expert (docs/energy/domaine/cas-annotes-par-l-expert.md) et à la couleur du jour. Pas de cadre de test automatique (D-008).
  • Mesures : coût par session (tokens réels), nombre de conclusions jugées pertinentes, fausses ou déjà connues.

Étape 2 : branchement réel, support seulement

Requêtes SQL, toutes les stations, cron quotidien, journal en table, notifications au support seulement, en rodage. Question posée : quel est le taux de fausses alertes en conditions réelles ?

Étape 3 : ouverture au client

Une fois le taux de fausses alertes de l'étape 2 jugé acceptable, les notifications client sont ouvertes, avec une politique de destinataire à définir (piste en annexe A).

Étape 4 : élargissement

Selon les besoins : autres domaines (acquisition, transport, déplacements), découpage des agents, boucle des règles candidates, et passage à Managed Agents si l'orchestration maison devient pénible.


7. Coût, risques, prérequis

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

Prix d'Opus 5.5 (claude-opus-5-5, modèle par défaut) : 4 par million de tokens en entrée, 20 en sortie, 0,20 $ en lecture de cache.

Hypothèse par session : 20 k tokens de prompt système en cache, environ 5 tours, ~100 k tokens d'entrée cumulés dont ~80 % lus en cache, ~10 k tokens de sortie (raisonnement compris).

Poste Calcul Coût
Entrée non cachée 20 k × 4 $/M 0,08 $
Lecture de cache 80 k × 0,20 $/M 0,02 $
Sortie 10 k × 20 $/M 0,20 $
Par session ~0,30 (fourchette 0,1 à 0,5)
  • Rejouer six mois de VERMONT (~180 sessions) : **~55 ** (20 à 90 ).
  • En régime établi, 50 stations × 30 jours = 1500 sessions : **~450 par mois et par agent** (150 à 750).

Sonnet 5.5 (claude-sonnet-5-5, 2 et 10 par million) coûte deux fois moins cher. Il peut être comparé sur le même rejeu : c'est une décision à prendre sur mesure, pas a priori.

Risques

Risque Parade
Faits inventés par l'agent Chaque preuve renvoie à un appel d'outil ; relecture humaine à l'étape 1
Lassitude face aux fausses alertes Le support reçoit seul les notifications tant que le taux n'est pas mesuré (étape 2)
Dérive du coût Budget de tokens par session ; coût mesuré à chaque étape
Changement de modèle Identifiant du modèle fixé ; rejeu de VERMONT avant tout changement
Données envoyées chez Anthropic Accepté ; conditions de conservation des données à vérifier avec la direction

Prérequis

  • Étape 1 : un compte et une clé API Anthropic.
  • Étape 2 : un accès SQL en lecture seule à la base des stations, et un serveur pour héberger le runner et le cron.

8. Options écartées

Option Raison
B. Managed Agents (Anthropic héberge la boucle, la planification par scheduled deployments et la mémoire par memory stores) Service en bêta. La base SQL devrait être joignable depuis Anthropic (l'exposer via une API, ou faire tourner un worker auto-hébergé). Reste la cible si l'orchestration maison devient pénible : la définition en dossier est portable.
C. Claude Agent SDK (harnais de Claude Code sur notre serveur) C'est un harnais de codage. Avec Bash, la surface d'action est large et difficile à auditer, ce qui convient mal à un agent qui notifie des clients.
Modèle open-weights hébergé chez AIMsight Inutile : l'API externe est acceptée. Il serait moins capable et demanderait un serveur GPU.
LLM sur la station Trop lourd pour un système embarqué solaire.
L'agent corrige lui-même la couleur du jour On perdrait la reproductibilité et la traçabilité du verdict déterministe.
Agent « explorateur libre » seul (sans les faits des règles) Moins traçable et moins reproductible, avec un risque de seuils inventés. L'exploration reste permise, mais encadrée et à côté des faits.
SQL libre, Bash, accès web pour l'agent Non auditable, non borné, inutile pour la mission.
RAG / base vectorielle pour la connaissance Inutile : la connaissance d'un domaine tient dans le prompt (~20 k tokens).

9. Questions ouvertes

  1. Découpage des agents : par domaine, par station, par rôle ? À décider quand un deuxième agent sera envisagé (étape 4).
  2. Politique de destinataire précise : qui reçoit quoi, à partir de quel niveau de certitude ? À définir sur mesure, avant l'étape 3.
  3. Affichage côté site : où et comment les notifications de l'agent apparaissent (maquettes maquettes/user/ et maquettes/support/). À voir avec l'équipe du site.
  4. Choix du modèle : Opus 5.5 par défaut ; comparaison éventuelle avec Sonnet 5.5 sur le rejeu de VERMONT.
  5. Relecture : qui relit les conclusions de l'agent pendant le pilote et le rodage (l'expert, le support) ?
  6. Conditions de conservation des données chez Anthropic : à valider avec la direction.
  7. Emplacement du code d'agent dans le dépôt (proposé : agents/ à la racine, séparé de src/<domaine>/, qui reste sans LLM).

Annexe A : pistes détaillées, à revoir étape par étape

Règles proposées pendant le brainstorm. L'utilisateur en approuve l'idée générale, mais pas chaque détail : elles sont à reprendre au moment de construire l'étape concernée, et à n'adopter que si le besoin apparaît.

A.1 Exécution

  • Cron vers 01:00 UTC, après la clôture du jour UTC (la couleur du jour se fige à minuit UTC).
  • Sessions en parallèle ; l'échec de l'une ne bloque pas les autres.
  • Le premier message contient aussi les conclusions encore ouvertes pour la station.
  • Budget de tokens par session (task budget de l'API).
  • Si l'API échoue : une ligne « agent non exécuté » dans le journal, pour qu'un silence ne passe jamais pour un « rien à signaler ».
  • Effort du modèle fixé explicitement (le défaut d'Opus 5.5 est medium) ; gérer l'arrêt refusal de l'API.
  • Programmatic tool calling : incompatible avec strict: true sur l'outil appelé depuis le bac à sable.

A.2 Journal des conclusions (table SQL)

Champs envisagés :

  • agent, version (hash git du dossier de l'agent), modèle, station, jour ;
  • type : anomalie inconnue, cas limite de règle ou rien ;
  • niveau de certitude (vocabulaire du projet) ;
  • preuves : chacune renvoie à un appel d'outil (identifiant, entrées, extrait du résultat) ;
  • ce qui reste non établi ; règle candidate éventuelle (description) ;
  • verdict déterministe du jour (couleur), pour comparer ;
  • statut : ouverte, en cours, résolue ;
  • transcription complète de la session (audit) ;
  • retour du support : pertinent, faux positif, déjà connu.

Déduplication : une anomalie qui dure met à jour sa conclusion ouverte au lieu de notifier chaque jour. L'agent voit les conclusions ouvertes (via get_history) et dit si c'est nouveau, une suite, ou résolu.

A.3 Contrôles de notify (par le code, pas par le modèle)

Le runner refuse l'appel et renvoie l'erreur à l'agent pour qu'il corrige, dans quatre cas :

  • une preuve ne correspond à aucun appel d'outil réel de la session ;
  • le niveau de certitude est hors vocabulaire ;
  • le destinataire n'est pas permis par la politique ;
  • le message destiné au client contient du jargon : côté client, pas de tension brute ni de mécanisme (cf. maquettes client).

A.4 Politique de destinataire (proposition)

  • Support : tout, avec le détail technique, y compris le niveau possible.
  • Client : seulement une anomalie inconnue de niveau strongly supported au moins, avec un message simple.
  • Cas limites de règle : au support seulement. Si l'agent écrivait au client « la couleur est verte, mais… », le client recevrait deux messages contradictoires. Le support tranche, puis écrit au client ou corrige la règle.

A.5 Affichage sur le site

  • Client : une carte « Agent » dans la section Diagnostic de la page System Summary, distincte de la couleur Energy (maquettes/user/).
  • Support : une entrée dans la section Status de la page Home (maquettes/support/).

A.6 Mise en service

  • Rodage : pendant les premières semaines de l'étape 3, les notifications destinées au client sont écrites dans le journal (« aurait été envoyé ») et vues par le support seul, avant l'ouverture réelle.

Annexe B : références

  • docs/aimsight/AIMsight_agentic_support_project_context.md :
    • §10 : règles épistémiques ;
    • §14-15 : format de réponse ;
    • §18 : architecture (analyseurs, faits, raisonnement) ;
    • §21 : boucle de découverte des règles ;
    • §27 : anti-patterns, dont « laisser le LLM inventer des seuils de validité ».
  • docs/decisions.md : D-003 (pas de LLM, remplacée en partie), D-005 (analyses imparfaites combinées), D-008 (pas de tests automatisés), D-020 (couleur du jour), D-027 (cette direction).
  • API Claude (fonctionnalités citées) :
    • Messages API et Tool Runner (SDK anthropic) ;
    • programmatic tool calling avec code_execution ;
    • prompt caching et task budgets ;
    • Managed Agents : scheduled deployments, memory stores.