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>
23 KiB
Support par l'API Claude : plan de construction
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
But : une page locale support où Marc colle le mail d'un client ; deux clients de l'API Claude (support, analyste) produisent un PDF de diapositives qui répond à la question, et Marc les fait corriger jusqu'à un PDF qu'il peut envoyer.
Architecture : un serveur de la bibliothèque standard (ThreadingHTTPServer, 127.0.0.1) sert la page et tient une séance en mémoire. Chaque agent est un historique de messages, seulement ajouté, et une boucle d'outils écrite à la main sur client.beta.messages.stream. Les outils lancent des copies des détecteurs, des outils de lecture, des scripts de figures et de la fabrique Typst, toutes dans API/tools/. LangSmith trace chaque appel.
Technique : Python 3.14, anthropic, langsmith, matplotlib dans API/.venv ; Typst ≥ 0.14 (~/.local/bin/typst), pdftotext, pdftoppm.
Spec : API/docs/2026-11-05-support-api-design.md (validé par Marc le 2026-11-05).
Contraintes globales
- Tout dans
API/; aucun fichier deAPI/ne lit.claude/,agent-tools/,detectors/nilabeling/à l'exécution. Seule dépendance extérieure : le dossier des données, réglageAIMSIGHT_DATA(défaut<API>/../data). - Modèle
claude-opus-5-5pour les deux agents,thinking={"type": "adaptive"},output_config={"effort": ...}explicite : support"medium", analyste"high".betas=["server-side-fallback-2026-07-01"],fallbacks="default". Streaming,max_tokens=64000,.get_final_message(). - Tarifs pour le coût (Opus 5.5, $ par million de tokens) : entrée 4,00 ; sortie 20,00 ; lecture du cache 0,20 ; écriture du cache 5,00.
- Historique seulement ajouté : jamais réécrit ni tronqué (le modèle refuse un historique édité qui contient ses blocs de réflexion). Un message assistant qui demande des outils et ses
tool_results'ajoutent ensemble, ou pas du tout. - Chaque message entrant porte sa source en tête :
<source>marc</source>ou<source>support</source>. - Le serveur écoute sur
127.0.0.1:8770seulement. Bibliothèque standard pour le serveur, HTML et JS sans framework pour la page. - Toute heure en UTC. Page, prompts et documents de
API/en français ; le PDF dans la langue du client. - Lecture seule sur les données. Les outils n'écrivent que dans le dossier de la séance et dans
API/tools/typst/{documents,build}/. - Pas de tests automatisés dans le projet (D-008) : un seul
API/support/check.pyàassert, plus des vérifications par lancement. - Pas de commit avant la validation de Marc (sa règle pour les essais de fonctionnalités). Un seul commit à la fin (Task 6).
Points d'attention
- Mail sans station ni plage : le support pose sa question à Marc et n'appelle pas l'analyste. Vérifié en Task 4, étape 5.
- Station absente de
data/, ou aucune mesure sur la plage : l'outil rend une erreur claire (is_error), l'analyste le dit, le support le dit à Marc ; aucune exception ne remonte au serveur.check.py, Task 3. - Marc écrit pendant qu'un agent travaille : le serveur répond 409 et la page affiche « occupé » ; l'historique reste valide. Le support est occupé tant que l'analyste qu'il a appelé l'est. Task 5.
- Erreur de l'API au milieu d'un tour (surcharge, quota) : le tour s'arrête sur un événement d'erreur, sans
tool_useorphelin dans l'historique ; le message suivant de Marc repart proprement.check.py, Task 2. - Sortie d'outil énorme ou image trop grande : texte plafonné à 40 000 caractères avec la mention
[… tronqué : N caractères]; image réduite à 1568 px de côté au plus.check.py, Task 3.
Task 1 : le dossier API/ et ses copies
Fichiers :
- Créer :
API/README.md,API/PROVENANCE.md,API/.gitignore,API/requirements.txt - Copier :
agent-tools/*.py→API/tools/agent-tools/;detectors/*.py(sansarchive/) →API/tools/detectors/;.claude/skills/presentation/figure-y.pyetimage-de-la-cause.py→API/tools/figures/;~/docfactory-presentation/brand/→API/tools/typst/brand/ - Copier, savoir de l'analyste →
API/knowledge/analyste/:labeling/familles.md,labeling/carte-des-etiquettes.md,labeling/connaissances/{chaine-de-mesure,colonnes-des-deplacements,cycle-thermique,images-de-la-camera,les-trous,metriques-de-qualite}.md,.claude/skills/lire-les-donnees/SKILL.md(→lire-les-donnees.md),agent-diagnostic/instructions.md§5 seul (→regles-de-preuve.md) - Copier, savoir du support →
API/knowledge/support/:.claude/skills/presentation/SKILL.md(→presentation.md),.claude/skills/presentation/modele.typ,.claude/skills/support/SKILL.md§5 seul (→redaction.md)
Interfaces :
-
Produit :
API/tools/detectors/categories.py <dossier> --du AAAA-MM-JJ --au AAAA-MM-JJ(inchangé) ;API/tools/figures/figure-y.py(mêmes arguments que l'original) ;API/tools/typst/= fabrique réduite (brand/,documents/,build/). -
Étape 1 : copier.
agent-tools/etdetectors/restent frères dansAPI/tools/: leurssys.pathrelatifs (.., agent-tools) marchent tels quels. Dansfigures/figure-y.py, remplacer"..", "..", "..", "agent-tools"par"..", "agent-tools". Dans les copies du savoir, les chemins qui pointent hors deAPI/(.claude/…,agent-tools/…) deviennent ceux deAPI/tools/…; le reste du texte est inchangé. -
Étape 2 :
PROVENANCE.md. Une ligne par copie : source, destination,git rev-parse --short HEADdu jour (pourbrand/: leVERSIONde la fabrique), date 2026-11-05, et ce qui a été adapté. En tête, comment rafraîchir : recopier, puis mettre à jour la ligne. -
Étape 3 :
.gitignore,requirements.txt, venv. Ignorer.venv/,.env,__pycache__/,tools/typst/documents/,tools/typst/build/.requirements.txt:anthropic,langsmith,matplotlib. Lancer :python3 -m venv API/.venv && API/.venv/bin/pip install -r API/requirements.txt -
Étape 4 : vérifier les détecteurs copiés. Lancer :
cd API && .venv/bin/python tools/detectors/categories.py ../data/NEBRASKA --du 2026-10-20 --au 2026-11-01Attendu : les mêmes lignes quepython3 detectors/categories.py data/NEBRASKA --du 2026-10-20 --au 2026-11-01depuis la racine (diffvide). -
Étape 5 : vérifier les figures et la fabrique. Lancer :
cd API && .venv/bin/python tools/figures/figure-y.py ../data/NEBRASKA /tmp/f.png 2026-10-20T00:00Z 2026-11-01T00:00Z --cam tilt,pan --cibles COLJ20,COLH21→ PNG écrit. Puis copierknowledge/support/modele.typdanstools/typst/documents/essai/main.typavec les PNG qu'il cite (pris danssupport/2026-11-02_BREITHORN_rapport-situation/), etcd tools/typst && ../../.venv/bin/python brand/tools/build.py essai→build/essai-draft.pdfexiste. Supprimerdocuments/essai/etbuild/ensuite. -
Étape 6 :
README.md. Installer (étape 3), les clés dansAPI/.env(ANTHROPIC_API_KEY,LANGSMITH_API_KEY,LANGSMITH_TRACING=true,LANGSMITH_PROJECT=aimsight-support),AIMSIGHT_DATA, lancer la page (API/.venv/bin/python API/support/serveur.py), ce que contient chaque dossier.
Task 2 : l'agent, une boucle d'outils qui reste vivante
Fichiers :
- Créer :
API/support/agent.py,API/support/check.py
Interfaces :
-
Produit :
PRIX = {"claude-opus-5-5": {"entree": 4.0, "sortie": 20.0, "cache_lu": 0.20, "cache_ecrit": 5.0}}($/Mtok)class Agent(nom: str, systeme: str, outils: list[dict], executer: Callable[[str, dict], str | list[dict]], client, journal: Callable[[dict], None], effort: str, modele: str = "claude-opus-5-5")Agent.messages: list[dict],Agent.cout: float($),Agent.occupe: boolAgent.tour(contenu: str | list[dict], source: str) -> str: ajoute le message de l'utilisateur (source en tête), fait tourner la boucle jusqu'àend_turnet rend le texte finalAgent.sauver(chemin: Path) -> None: écritmessagesen JSON- événements du journal :
{"agent": nom, "type": "entree" | "texte" | "outil" | "erreur" | "cout", "texte": str, "source": str};"entree": le message reçu, avec sa source (marcousupport), pour que le fil de l'analyste montre aussi les demandes du support ; pour"cout","texte"= le coût cumulé de l'agent, formaté0.42;"source"seulement pour"entree"
-
Étape 1 : écrire les vérifications dans
check.pyavec un faux client (un objet dontbeta.messages.stream(**kw)est un gestionnaire de contexte qui rend des réponses scriptées, aveccontent,stop_reasonetusage) :check_boucle(): réponse 1 =tool_use(detecteurs), réponse 2 =end_turnavec un texte →tourrend ce texte ;messagescontient, dans l'ordre, user, assistant (tool_use), user (tool_result du mêmetool_use_id), assistant ; l'exécuteur a été appelé une fois avec le bon nom et la bonne entrée.check_erreur(): la réponse 2 lève une exception →tourne la propage pas, émet un événement"erreur"; la dernière entrée demessagesn'est pas un assistant avectool_usesanstool_result;occuperevient àFalse.check_cout(): usageinput_tokens=1_000_000, output_tokens=100_000, cache_read_input_tokens=0, cache_creation_input_tokens=0→cout == 6.0.check_source(): le premier bloc texte du message de l'utilisateur commence par<source>marc</source>.
-
Étape 2 : lancer, constater l'échec.
API/.venv/bin/python API/support/check.py→ ImportError suragent. -
Étape 3 : écrire
agent.py. Appel :client.beta.messages.stream(model, max_tokens=64000, system=[{"type": "text", "text": systeme, "cache_control": {"type": "ephemeral"}}], tools=outils, messages=messages, thinking={"type": "adaptive"}, output_config={"effort": effort}, betas=["server-side-fallback-2026-07-01"], fallbacks="default", cache_control={"type": "ephemeral"}), puis.get_final_message(). Le contenu de la réponse est ajouté en dicts (b.model_dump(mode="json", exclude_none=True)).stop_reason:tool_use→ exécuter tous lestool_use, puis ajouter l'assistant et un seul message user avec tous lestool_result; un exécuteur qui lève →tool_resultavecis_error: Trueet le message d'erreur ;pause_turn→ renvoyer tel quel ;end_turn→ fin ;max_tokensourefusal→ événement"erreur"et fin. Un événement"texte"par bloc texte de l'assistant ; un événement"outil"par appel (nomet entrée résumée sur une ligne). Coût : usage ×PRIX, cumulé, un événement"cout"par réponse. Une exception autour d'un appel à l'API : événement"erreur", l'assistant n'est pas ajouté, fin du tour. -
Étape 4 : lancer
check.py→okpour chaque vérification.
Task 3 : les outils des deux agents
Fichiers :
- Créer :
API/support/outils.py - Modifier :
API/support/check.py(ajouter les vérifications des outils)
Interfaces :
- Consomme :
Agent(Task 2) seulement pour l'outildemander_analyste, par un rappel que lui donne la séance. - Produit :
OUTILS_ANALYSTE: list[dict],OUTILS_SUPPORT: list[dict](schémas de l'API,strict: True,additionalProperties: false)class Boite(dossier_seance: Callable[[], Path], station: Callable[[], str | None], donnees: Path, demander_analyste: Callable[[str], str], poser: Callable[[str, str], Path])(poser(station, sujet): le rappel de la séance qui renomme son dossier et retient la station) avecexecuter_analyste(nom: str, entree: dict) -> str | list[dict]etexecuter_support(nom: str, entree: dict) -> str | list[dict]LECTURE = {"inventaire", "resume", "plages", "jours", "vignettes", "qualite", "ensemble", "graphique", "metriques", "stations"}plafonner(texte: str, n: int = 40_000) -> str;bloc_image(chemin: Path) -> dict(bloc image en base64, PNG ou JPEG, plus grand côté ≤ 1568 px)
Outils de l'analyste (tous lancés par subprocess.run avec API/.venv/bin/python, cwd = le parent de donnees, délai 600 s, stdout et stderr rendus, plafonnés) :
detecteurs(station: str, du: str, au: str)→tools/detectors/categories.py <donnees>/<station> --du <du> --au <au>outil_de_lecture(nom: str, arguments: list[str])→tools/agent-tools/<nom>.py <arguments>;nomhors deLECTURE→ erreur ; pourgraphique,ensemble,jours,metriques,vignettes,qualite, ajouter--sortie <dossier de la séance>figure_courbes(nom: str, debut: str, fin: str, cibles: list[str], options: list[str])→tools/figures/figure-y.py <donnees>/<station> <séance>/<nom>.png <debut> <fin> --cibles <…> <options>(station : celle de la séance, posée par le support, cf. Task 4)image_de_la_cause(nom: str, x: int, y: int, instants: list[str])→tools/figures/image-de-la-cause.py <donnees>/<station> <x> <y> <séance>/<nom>.png <instants>voir_image(chemin: str)→[bloc_image(…)]; chemin relatif au dossier de la séance, ouimages/…de la station ; tout autre chemin (.., absolu) → erreur
Outils du support :
-
poser_station(station: str, sujet: str)→ vérifie que<donnees>/<station>existe ; renomme le dossier de la séance en<AAAA-MM-JJ>_<STATION>_<sujet>; rend la liste des sous-dossiers de données de la station -
demander_analyste(message: str)→ le rappel de la séance -
ecrire_presentation(source_typ: str)→ écrit<séance>/<station minuscule>.typ -
compiler()→ copie le.typ(enmain.typ) et les PNG de la séance danstools/typst/documents/<slug>/, lancebrand/tools/build.py <slug>depuistools/typst/, copiebuild/<slug>-draft.pdfvers<séance>/v<N>.pdf(N = 1 + nombre dev*.pdfprésents), rendv<N>.pdf : <k> diapositive(s) qui débordent(pdftotextpuis compterOverflow) ou la sortie d'erreur de Typst, sans créer de version -
voir_page(n: int)→pdftoppm -f n -l n -png -r 80sur la dernière version, rendu parbloc_image -
Étape 1 : vérifications dans
check.py(sans appel à l'API ; surdata/NEBRASKA) :check_lecture_refusee():outil_de_lecture("rm", [])rend une erreur et ne lance rien.check_chemin():voir_image("../../.env")etvoir_image("/etc/passwd")→ erreur.check_station_absente():detecteurs("NULLEPART", "2026-10-01", "2026-10-02")→ une erreur qui nomme la station, pas d'exception.check_detecteurs():detecteurs("NEBRASKA", "2026-10-20", "2026-11-01")→ texte non vide.check_plafond():plafonner("x" * 50_000)fait au plus 40 100 caractères et finit partronqué : 50000 caractères].check_image():bloc_imaged'une image dedata/NEBRASKA/images/→media_typeimage/jpeg, image décodée de côté ≤ 1568.check_compiler(): séance temporaire contenantmodele.typ(ennebraska.typ) et ses PNG →compiler()rendv1.pdf : …etv1.pdfexiste ; une seconde fois →v2.pdf. Un.typcassé (#oups() → erreur, pas dev3.pdf.
-
Étape 2 : lancer
check.py→ échec (pas deoutils). -
Étape 3 : écrire
outils.py. -
Étape 4 : lancer
check.py→okpartout.
Task 4 : les prompts, la séance et LangSmith
Fichiers :
- Créer :
API/prompts/support.md,API/prompts/analyste.md,API/support/seance.py
Interfaces :
-
Consomme :
Agent(Task 2),Boite,OUTILS_*(Task 3). -
Produit :
class Seance(mail: str, images: list[tuple[str, bytes]], contexte: str, donnees: Path, journal: Callable[[dict], None]), avec :dossier: Path(d'abordAPI/cases/<AAAA-MM-JJ>_<HHMMSS>/, renommé parposer_station),station: str | Nonesupport: Agent,analyste: Agentdemarrer() -> None: écritdemande.md(mail, contexte, images en fichiers), puis premier tour du support avec le mail, les images (blocs image) et le contexteparler(agent: str, texte: str) -> None:"support"ou"analyste", sourcemarcoccupe(agent: str) -> bool: le support est occupé aussi pendant qu'il attend l'analystecout() -> dict:{"support": float, "analyste": float, "total": float}derniere_version() -> Path | None
-
Étape 1 :
prompts/analyste.md, en balises :<role>,<premiere_passe>,<approfondi>,<rendu>,<regles>, puis le savoir deknowledge/analyste/inclus par le code au chargement (balise<savoir fichier="…">par fichier : prompt stable, donc en cache). Il doit dire :- première passe :
detecteurssur la plage, les événements qui répondent à la question, une illustration par événement retenu (courbecorr_yà plage grisée, ou image de la cause), regardée parvoir_imageavant d'être gardée ; - approfondi (
outil_de_lecture, images, critique des détecteurs) seulement si le message vient de<source>marc</source>et le demande ; une demande du support qui l'exigerait est renvoyée au support, pour Marc ; - le rendu au support : un bloc par événement (quand, cibles, ce qu'on voit, diagnostic, illustration), puis
Hors question (pour Marc); vocabulaire de preuve (regles-de-preuve.md) ; il ne modifie jamais les détecteurs.
- première passe :
-
Étape 2 :
prompts/support.md, en balises :<role>,<deroule>,<presentation>,<redaction>,<interdits>, puisknowledge/support/inclus de la même façon. Il doit dire :- tirer station, plage UTC et question du mail et du contexte ; ce qui manque, le demander à Marc et finir son tour ; sinon
poser_station, puisdemander_analysteavec station, plage et question ; - la présentation suit
presentation.mdetmodele.typ, restreinte à la question du mail : seuls les événements qui y répondent ; titre, résumé, une diapositive par événement, conclusions, clôture ; rien de la section « Hors question » ; compiler, puisvoir_pagesur chaque page à image ; corriger jusqu'à zéro débordement ;- un retour de forme : corriger seul ; un retour de fond : le transmettre à l'analyste ;
- les interdits (spec §2, anti-buts) : rien d'interne, ne pas se mettre en cause, ne rien affirmer sur l'ouvrage, aucune consigne au client.
- tirer station, plage UTC et question du mail et du contexte ; ce qui manque, le demander à Marc et finir son tour ; sinon
-
Étape 3 :
seance.py. Un clientanthropic.Anthropic()enveloppé parlangsmith.wrappers.wrap_anthropic, etdemarrer,parlerdécorés@langsmith.traceable(le nom de la séance en métadonnée) : une trace par séance. Clés lues dansAPI/.envpar un petit lecteurCLE=valeur(pas de dépendance). Quand Marc parle à l'analyste, l'échange (sa question, la réponse) est mis de côté puis ajouté en tête du prochain tour du support, dans<echange_marc_analyste>. Les deux historiques sont sauvés (support.json,analyste.json) dans le dossier de la séance après chaque tour. -
Étape 4 : essai sans page (coûte quelques dollars). Un mail court, station explicite :
cd API && .venv/bin/python -c "from support.seance import Seance; …"avec le mail « Bonjour, pourquoi les courbes de NEBRASKA sont-elles si bruitées du 28 au 31 octobre ? », journal =print. Attendu :poser_station; undemander_analyste; l'analyste lancedetecteurs, produit au moins une figure et la regarde ; le support écrit, compile, regarde ses pages ;v1.pdfexiste ;cache_read_input_tokens > 0à partir du deuxième appel d'un même agent ; une trace dans le projet LangSmithaimsight-support. -
Étape 5 : essai du point d'attention 1. Mail « Bonjour, les courbes sont bizarres depuis la semaine passée, tu peux regarder ? » sans contexte → le support pose une question à Marc, et aucun
demander_analyste.
Task 5 : la page et le serveur
Fichiers :
- Créer :
API/support/serveur.py,API/support/page.html
Interfaces :
-
Consomme :
Seance(Task 4). -
Produit, routes de
127.0.0.1:8770:GET /→page.htmlPOST /analyser{"mail": str, "contexte": str, "images": [{"nom": str, "type": str, "base64": str}]}→ crée la séance, lancedemarrerdans un fil ; 409 si une séance tourne déjàPOST /message{"agent": "support" | "analyste", "texte": str}→parlerdans un fil ; 409 sioccupe(agent)GET /evenements?depuis=N→{"evenements": [...], "n": int, "cout": {...}, "version": "v2.pdf" | null, "occupe": {"support": bool, "analyste": bool}}GET /pdf→ la dernière version (application/pdf)
-
Étape 1 :
serveur.py.ThreadingHTTPServer, une seule séance à la fois, la liste des événements en mémoire derrière unthreading.Lock. Au lancement, ouvrir la page dans le navigateur comme les autres pages du projet (explorer.exesous WSL, sinonwebbrowser), sans dépendre desrc/common/. -
Étape 2 :
page.html, disposition B (maquette :.superpowers/brainstorm/*/content/page-support.html) : en haut, le mail (zone de texte ; une image collée depuis le presse-papiers s'ajoute en vignette), le contexte, Analyser, le coût (support, analyste, total, en $) ; au milieu, deux fils côte à côte, support à gauche, analyste à droite, chacun avec sa zone de saisie, désactivée et marquée « occupé » quand l'agent travaille ; les événements"outil"en une ligne grise, les"erreur"en rouge ; en dessous, le PDF dans un<iframe>rechargé à chaque nouvelle version, son numéro et Télécharger. Interrogation de/evenementschaque seconde. -
Étape 3 : vérifier par lancement et capture.
API/.venv/bin/python API/support/serveur.py, coller le mail de la Task 4 étape 4, Analyser : les deux fils se remplissent au fil de l'eau, le coût monte, le PDF v1 apparaît et se télécharge. Écrire au support « La conclusion est trop longue, deux puces au plus » → v2. Écrire au support pendant qu'il travaille → refusé, « occupé ». Capture de la page à montrer à Marc.
Task 6 : documenter et livrer
Fichiers :
-
Modifier :
docs/decisions.md(D-133),CLAUDE.md(carte et « État »),run.md(la commande de la page) -
Étape 1 : D-133, au format du fichier : le support par l'API Claude dans le sous-projet
API/, séparé de.claude/; options écartées (Agent SDK, Managed Agents) et pourquoi ; renvoi au design. -
Étape 2 :
CLAUDE.md. Une ligne dans « État et prochaine étape » (support par l'API, prototype) et une entréeAPI/dans la carte du dépôt (sous-projet autonome ; sa doc dansAPI/README.md) ; rester sous 200 lignes. -
Étape 3 : montrer à Marc la capture et le PDF de l'essai ; attendre sa validation.
-
Étape 4 : commit, après sa validation seulement.
git add API docs/decisions.md CLAUDE.md run.md docs/superpowers/plans/2026-10-23-journal-du-matin.md git commit -m "API: support page with two Claude API clients, support and analyst (D-133)"Vérifier avant que
git statusne montre niAPI/.envniAPI/.venv/.