Files
Support-Agent/API/docs/2026-11-05-support-api-design.md
T
maximeandClaude Opus 5.5 8ba75b92fa API: support page with two Claude API clients, support and analyst (D-133)
Self-contained sub-project API/: a local support page where Marc pastes a
client's mail; a support agent and an analyst agent stay alive for the session
and produce a slide PDF that answers the client's question. Tools, detectors,
knowledge and Typst brand are copied (API/PROVENANCE.md). First real case:
Crissier (LENZSPITZE), workflow validated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 12:58:39 +01:00

15 KiB
Raw Blame History

Support par l'API Claude : design

  • Date : 2026-11-05
  • Statut : brouillon, à valider par Marc
  • Portée : premier prototype opérationnel ; pas de design visuel peaufiné.

1. Intention

Le projet a beaucoup exploré : détecteurs, étiquettes, agents Claude Code. Marc veut passer à l'opérationnel et faire du « AI as software » sur l'API Claude, avec ses crédits API, tracé dans LangSmith.

Le premier usage, c'est le support au client. Un client (souvent un installateur, comme celui qui travaille pour Renault) paie le support. Il ne comprend pas ses courbes : du bruit, beaucoup d'anomalies. Il doit souvent lui-même rendre compte à quelqu'un. Aujourd'hui, Marc lui répond à la main : /support <STATION> puis /presentation dans Claude Code, avec trois présentations PDF pour le cas Renault. Ça prend du temps. Le diagnostic, lui, est déjà là, grâce aux détecteurs et à l'analyste ; il reste à en faire une réponse.

On suppose des détecteurs fiables et un analyste performant : ce sont les deux seuls ingrédients du diagnostic. Le diagnostic analytique (détecteurs) reste sans LLM.

Succès : à partir du mail d'un client, une séance produit un PDF que Marc envoie tel quel, juste, clair, pas trop technique, qui répond à la question et à rien d'autre. On y converge par essais successifs : le prompt et la forme du rapport s'affinent de séance en séance.

2. Buts, non-buts, anti-buts

Buts (v1)

  • Une page web locale support, lancée par un script Python comme labeling/labeling.py.
  • Deux clients API, support et analyste, vivants pendant toute la séance.
  • Une seule sortie : un PDF dans la forme des présentations AIMsight, ciblé sur la question du mail.
  • Marc peut dialoguer avec chacun des deux, et redemander des versions du PDF.
  • Le coût de la séance est visible ; chaque appel est tracé dans LangSmith.
  • Tout vit dans API/, extractible tel quel vers un autre projet.

Non-buts (plus tard, peut-être)

  • Connexion aux boîtes mail, suivi des conversations, gestion de dossiers clients.
  • Saisie vocale (Whisper, ~/whisper).
  • Sortie HTML avec GIF, rapport de situation complet, mail de réponse.
  • Boutons d'action (« analyse approfondie ») : le langage naturel suffit d'abord.
  • Déploiement serveur, authentification, plusieurs séances en parallèle, reprise d'une séance après redémarrage du serveur.

Anti-buts (un échec même si ça marche)

  • Le PDF répond à autre chose que la question, ou en dit plus qu'elle.
  • De l'interne dans le PDF : codes d'events, noms des détecteurs ou des outils, autres stations, identifiants (SIM_CCID, ip), vocabulaire de preuve en anglais.
  • Le PDF met en cause notre système, ou affirme ce qu'on ne sait pas (« l'ouvrage ne bouge pas »), ou donne des consignes au client. Les règles de .claude/skills/presentation/SKILL.md (« Ce que veut l'utilisateur », « Ce qui n'a pas marché ») s'appliquent.
  • L'analyse approfondie part sans que Marc l'ait demandée.
  • Un fichier de API/ dépend de .claude/, de agent-tools/, de detectors/ ou d'une autre partie du projet (hors des données, §6).

3. Le déroulé d'une séance

  1. Marc colle le mail du client (texte et images) dans la page, ajoute au besoin son contexte (station, plage, ce qu'il sait du cas), et clique Analyser.
  2. Le support tire du mail et du contexte la station (un dossier de data/), la plage (UTC) et la question reformulée. S'il lui manque quelque chose qu'il ne peut pas déduire, il le demande à Marc dans son fil, puis attend la réponse.
  3. Le support envoie à l'analyste une demande précise : station, plage, question.
  4. Première passe de l'analyste : il lance les détecteurs sur la plage (pas les étiquettes de labeling/auto/ : en opérationnel, une plage nouvelle n'en a pas). Les détecteurs doivent dire quand la caméra bouge (tilt, pan, rotation) : aujourd'hui aucun ne lit camera/, c'est un préalable, développé dans detectors/ (point 78 du plan vivant, §10) puis copié dans API/. Il retient les événements qui répondent à la question et produit une illustration par événement retenu (la courbe corr_y à plage grisée, ou l'image de la cause), qu'il regarde avant de la garder. Il rend au support les faits par événement (quand, cibles, ce qu'on voit, diagnostic), les illustrations, et à part une courte liste « hors question, pour Marc ».
  5. Le support écrit la présentation (.typ) et la compile. Le PDF v1 s'affiche dans la page ; la liste « hors question » s'affiche dans le fil de l'analyste, pour Marc seulement.
  6. Retours de Marc :
    • Forme (trop technique, trop long, une diapositive de trop) : il l'écrit au support, qui corrige et recompile (v2, v3…).
    • Fond (« ce n'est pas la pluie, regarde les images du 28 ») : il l'écrit au support, qui transmet à l'analyste, ou directement à l'analyste dans son fil.
    • Analyse approfondie : seulement à la demande explicite de Marc, dans le fil de l'analyste ou par le support qui relaie sa demande. L'analyste prend alors la plage avec les outils de lecture et les images, et critique ou complète les détecteurs. En v1, il n'exécute pas de code qu'il écrirait lui-même (décision de Claude : code arbitraire sur le poste, projet en lecture seule) ; on l'ajoutera quand une analyse approfondie en aura besoin.
  7. Marc télécharge le PDF. La séance est gardée dans API/cases/ (§6).

Une séance, un PDF, même si le mail concerne plusieurs stations. En v1, Marc ne donne que des cas sur une seule station ; les cas croisés viendront ensuite. Le dossier de la séance et les outils sont pensés pour une station, sans rien interdire pour plusieurs.

L'analyste ne modifie jamais les détecteurs (ni l'original ni la copie) : il complète ou critique leurs constats dans la séance, par un texte rendu au support (décision de Claude).

4. La page (disposition B, choisie par Marc)

  • En haut : la zone du mail (texte, et images collées depuis le presse-papiers), la zone de contexte, le bouton Analyser, le coût de la séance en dollars (par agent et total).
  • Au milieu, deux fils côte à côte : à gauche, le support ; à droite, l'analyste. Chacun avec sa zone de saisie. Dans le fil de l'analyste, on voit aussi les demandes du support et ce que l'analyste lui rend, pour savoir sur quoi le rapport s'appuie. Une ligne courte par appel d'outil (« → détecteurs NEBRASKA 20.10–31.10 ») suffit pour suivre ce qu'il fait.
  • En dessous : l'aperçu du PDF (le lecteur PDF du navigateur), la version (v1, v2…), le bouton Télécharger.

Les messages s'affichent au fil de l'eau, pas seulement à la fin d'un tour (un tour de l'analyste peut durer plusieurs minutes).

5. Les deux clients

Mon choix (Claude), pas une demande de Marc : la Messages API avec le SDK Python anthropic et des outils que nous définissons (Tool Runner, client.beta.messages.tool_runner avec @beta_tool, ou une boucle écrite à la main si les tours doivent être interrompus ou suivis plus finement). Pas d'Agent SDK : c'est Claude Code empaqueté, la frontière avec .claude/ deviendrait floue, et nos outils déclarent exactement ce que chaque agent a le droit de faire. Pas de Managed Agents : les données et la fabrique Typst sont sur le poste.

Un agent vivant = un historique de messages tenu en mémoire par le serveur de la page, auquel chaque message de Marc ou du support s'ajoute. L'historique est seulement ajouté, jamais réécrit (le modèle refuse un historique modifié qui contient ses blocs de réflexion).

Modèle : claude-opus-5-5 pour les deux (défaut de l'API), réflexion adaptative, effort réglé explicitement par agent (la valeur par défaut d'Opus 5.5 est medium). Passer le support sur claude-sonnet-5-5 pour réduire le coût, c'est à Marc de le décider, après mesure. Mise en cache du prompt (outils et système stables en tête) ; fallbacks: "default" contre les refus des classifieurs.

Prompts : en balises (<role>, <regles>, <sortie>…), un fichier par prompt dans API/prompts/, versionnés.

Le support

  • Rôle : il pilote la séance, parle à Marc, met en forme. Il ne fait pas d'analyse lui-même.
  • Savoir : les règles de rédaction du support (.claude/skills/support/SKILL.md, §5 : la langue du client, des faits plutôt que des consignes, rien d'interne), celles de la présentation (.claude/skills/presentation/SKILL.md, tout le fichier) et le modèle modele.typ, copiés dans API/ ; la structure de la présentation (titre, résumé, une diapositive par événement, conclusions, clôture) se restreint à la question du mail.
  • Outils :
    • demander_analyste(message) : ajoute le message au fil de l'analyste, en le marquant comme venant du support, fait tourner l'analyste jusqu'à sa réponse, et la rend ;
    • ecrire_presentation(source_typ) : écrit le .typ dans le dossier de la séance ;
    • compiler() : compile avec la fabrique copiée, rend le nombre de diapositives qui débordent et les erreurs ;
    • voir_page(n) : l'image d'une page du PDF, pour vérifier la mise en page.
  • Poser une question à Marc n'est pas un outil : le support finit son tour par sa question, et attend.

L'analyste

  • Rôle : le diagnostic. Première passe sur les détecteurs ; analyse approfondie sur demande de Marc seulement.
  • Savoir : le strict nécessaire, copié dans API/ : ce que sont les familles et comment les lire (labeling/familles.md), les connaissances utiles de labeling/connaissances/ (colonnes des déplacements, images de la caméra, cycle thermique, trous), la carte des événements, le mode d'emploi des outils de lecture (.claude/skills/lire-les-donnees/SKILL.md, adapté) et les règles de preuve (agent-diagnostic/instructions.md, §5). Choisir quoi copier relève du constructeur, avec une règle : un document n'entre que si l'analyste s'en sert.
  • Outils :
    • detecteurs(station, debut, fin) : les événements du journal sur la plage (copie de detectors/categories.py et des détecteurs) ;
    • figure(...) : la courbe corr_y à plage grisée, la caméra, la température (copie de figure-y.py), et l'image de la cause (copie de image-de-la-cause.py), écrites dans le dossier de la séance ;
    • voir_image(chemin) : rend l'image elle-même (bloc image) pour qu'il la regarde ;
    • outil_de_lecture(nom, arguments) : lance un des outils de lecture copiés (inventaire, resume, plages, vignettes, qualite…), sur une liste fermée ; c'est l'outil de l'analyse approfondie.
  • Qui décide de l'approfondi : chaque message entrant porte sa source (Marc ou le support). Le prompt de l'analyste dit de n'approfondir que sur la demande de Marc ; une demande du support qui l'exigerait se renvoie au support, qui la soumet à Marc.

Mon choix : quand Marc écrit directement à l'analyste, l'échange (sa question, la réponse de l'analyste) est transmis au support au début de son tour suivant, pour qu'il en tienne compte dans le rapport.

6. Le dossier API/, un sous-projet

Tout ce dont les clients ont besoin est dans API/ ; rien de API/ n'est lu par les agents Claude Code, et réciproquement. Si on extrait API/ vers un nouveau projet, il tourne seul, avec des données.

API/
  README.md            # lancer la page, installer, les clés
  PROVENANCE.md        # chaque fichier copié : d'où, à quel commit, le 2026-11-05
  docs/                # ce design, puis la doc du sous-projet
  prompts/             # support.md, analyste.md (balises)
  knowledge/           # les documents copiés que lisent les agents
  tools/               # détecteurs, outils de lecture, figures copiés ; la fabrique Typst (brand/, build) copiée
  support/             # le serveur de la page, la page HTML, les deux clients
  cases/               # une séance par dossier : <date>_<STATION>_<sujet>/
  .venv/  .env         # hors de git

Les noms des sous-dossiers relèvent du constructeur ; la séparation, non.

  • Données : data/ reste hors de API/ (hors de git, pompé par extraction/). Son chemin est un réglage (défaut ../data). C'est la seule dépendance extérieure.
  • Versions : les copies vieillissent (les détecteurs évoluent par /detector-learner). PROVENANCE.md dit d'où vient chaque copie et à quel commit ; on les rafraîchit à la main, quand Marc le décide.
  • Dossier d'une séance (cases/<date>_<STATION>_<sujet>/) : le mail et ses images, le contexte, les deux historiques (JSON, sauvegardés à chaque tour), les figures, le .typ, les PDF par version. Il contient des mails et des images de clients, comme support/. Versionné comme support/, commité seulement quand Marc valide le PDF.
  • Dépendances : API/.venv avec anthropic, langsmith, matplotlib (figures) ; Typst ≥ 0.14 et pdftotext sur le poste.
  • Clés : ANTHROPIC_API_KEY et celles de LangSmith dans API/.env, hors de git. Traces LangSmith : un projet LangSmith dédié, une trace par séance, les deux agents dedans, complètes (mails, images, sorties des outils : accord de Marc, sans masquage).

7. Contraintes

  • Lecture seule sur les stations et les données, comme tout le projet.
  • Le serveur écoute sur 127.0.0.1 seulement.
  • Bibliothèque standard pour le serveur et la page (pas de framework), comme les autres pages du projet.
  • Toute heure en UTC ; la page et les documents de API/ en français ; le PDF dans la langue du client.

8. Laissé au constructeur

  • Le découpage du code, le mécanisme d'affichage au fil de l'eau (SSE ou interrogation périodique), le format exact des historiques.
  • Les prompts de départ, à partir des skills support et presentation et de l'agent analyste ; ils s'affineront par les séances.
  • Les arguments exacts des outils, les valeurs d'effort, la fenêtre de contexte (compaction si un fil grossit trop).
  • Le calcul du coût (usage de chaque réponse × tarif du modèle).

9. Premier essai

Un cas sur une seule station, donné par Marc. À défaut (décision de Claude) : une des trois stations du cas Renault (NEBRASKA, octobre), avec un mail écrit d'après la réunion et une question précise (« pourquoi les courbes sont-elles si bruitées ? »), pas « que s'est-il passé en octobre », sinon on ne teste pas la règle de la question et rien d'autre. Comparer ensuite le PDF aux constats de support/2026-11-02_NEBRASKA_rapport-situation/, qui reposent sur la caméra qui bouge : l'essai n'a de sens qu'après le préalable du §10.

10. Ordre

  1. Préalable, hors de API/ : les détecteurs lisent le mouvement de la caméra (point 78 du plan vivant docs/superpowers/plans/2026-10-23-journal-du-matin.md), mesuré par le benchmark de /detector-learner.
  2. API/ : la page, les deux clients, les outils copiés, la fabrique ; on peut le construire en parallèle du point 1 sur les détecteurs actuels, puis rafraîchir la copie.
  3. Le premier essai (§9), puis les séances qui affinent les prompts.