flowdeck/docs/agents-skills-phase-5-durcissement-et-extensions.md

Agents & Skills pour Flowdeck — Phase 5 : Durcissement et extensions

Champ	Valeur
Phase	5 sur 5 — optionnelle, fondée sur les données réelles des Phases 1 à 4
Document parent	architecture-agents-skills-notion-flowdeck.md v1.1 — en particulier §16.4 (injection de prompt), §17 (exigences non fonctionnelles), §20 Phase 5
Version	1.0 — 9 octobre 2026
Auteur	Spark, pour Bruno
Statut	À planifier après retour d'usage des Phases 1 à 4 — contrairement aux phases précédentes, son périmètre exact se confirme avec les données, il ne se devine pas
Prérequis	Phases 1 à 4 en production avec du trafic réel
Migration créée	Aucune planifiée (toute migration nécessaire serait numérotée à partir de 44, au moment du besoin)
Nature	Durcissement (sécurité, coûts, fiabilité), mesure avancée, extensions publiques

Résultat visible à la fin de cette phase. La solution complète tourne avec des preuves : le routeur de skills s'est amélioré sur les contre-exemples réels ; les Insights couvrent le workspace entier avec export à l'échelle ; une campagne de tests d'injection de prompt a été menée et ses résultats traités ; les runs et journaux ont une politique de rétention et d'archivage appliquée ; la Skills API publique permet de publier une base de skills vers des agents externes ; et les deux chantiers voisins — serveur MCP Flowdeck et SDK d'agents — sont soit lancés avec leur cadrage prêt, soit explicitement écartés, sur données plutôt que sur impressions.

---

Table des matières

1. Pourquoi cette phase est différente
2. Conditions d'entrée
3. Chantier A — Améliorer le routeur de skills sur données réelles
4. Chantier B — Insights à l'échelle et administration avancée
5. Chantier C — Sécurité offensive : campagne d'injection de prompt
6. Chantier D — Rétention, archivage et performance des journaux
7. Chantier E — Skills API publique et publication externe
8. Chantier F — Préparer (ou écarter) le serveur MCP et le SDK d'agents
9. Chantier G — Qualité des agents : évaluation continue
10. Tests transverses de la phase
11. Critères de sortie
12. Ce que cette phase ne doit pas devenir

---

1. Pourquoi cette phase est différente

Les Phases 1 à 4 construisent des mécanismes ; leurs documents peuvent donc être écrits avant le code. La Phase 5, elle, consomme les retours de ces mécanismes : taux d'erreur du routeur, distribution réelle des coûts, tentatives d'injection observées, volume des journaux. Écrire aujourd'hui ses seuils ou ses priorités internes serait de la fausse précision.

Ce document fixe donc : les conditions d'entrée (quelles données doivent exister), les chantiers avec leur méthode et leurs critères de sortie, et les décisions à prendre sur données. Chaque chantier est indépendant : ils peuvent être menés dans n'importe quel ordre, partiellement, ou pas du tout — sans remettre en cause la complétude des Phases 1 à 4.

2. Conditions d'entrée

Avant d'ouvrir un chantier, réunir (une page de constat suffit) :

• Le nombre de runs par surface (chat, éditeur, déclencheurs, API) sur au moins 4 semaines, et leur taux d'échec.
• Les décisions du Skill Router : distribution des branches (forced, high, grey, none), nombre de contre-exemples « skill pas pertinent » collectés (mécanisme livré en Phase 2).
• La distribution des coûts : crédits par agent, par membre, par modèle ; part des runs autonomes.
• Les incidents : approbations expirées, boucles stoppées, plafonds atteints, écritures externes refusées.
• Le volume des tables de journaux (agent_runs, ai_usage_ledger, agent_actions, skill_runs) et les temps de requête des écrans Activity/Insights.

Chaque constat débouche sur un classement des chantiers A à G par bénéfice attendu — c'est ce classement, pas ce document, qui fixe l'ordre réel.

3. Chantier A — Améliorer le routeur de skills sur données réelles

Méthode.

1. Étendre le jeu d'essai de la Phase 2 (30 demandes) avec les cas réels : demandes ayant reçu un « pas pertinent », demandes où l'utilisateur a forcé un skill que le routeur n'avait pas retenu (signal faible d'un rappel insuffisant), demandes relancées juste après un skill automatique (signal faible d'une mauvaise application).
2. Rejouer le routeur hors ligne sur ce corpus élargi ; ajuster les seuils et, si le corpus le justifie, enrichir l'arbitrage (par exemple fournir à l'arbitre les exemples du skill, pas seulement sa description).
3. Traiter la cause avant le symptôme : une description qui attire de mauvais appariements se réécrit — fournir dans la Library un signalement « ce skill est souvent écarté » visible par son propriétaire, avec ses demandes fautives.
4. Toute modification des seuils par défaut est livrée avec le rapport du corpus (précision/rappel avant/après), comme un changement de modèle se livre avec son évaluation.

Critères de sortie. Le corpus dépasse 150 demandes étiquetées et fait partie des tests permanents ; les taux d'erreur mesurés ont baissé par rapport au constat d'entrée, ou l'analyse montre qu'ils sont dominés par des descriptions à réécrire (et la liste de ces descriptions a été traitée).

4. Chantier B — Insights à l'échelle et administration avancée

Travaux.

• Vue workspace des Insights : tous les agents (runs, statuts, modèles, crédits, taux d'échec), avec la règle d'accès déjà posée — un admin doit être ajouté à un agent pour voir le détail de ses conversations ; les agrégats anonymisés de contenu, eux, sont visibles sans cet ajout.
• Export CSV à l'échelle : conversations et runs sur une période, avec un plafond documenté par export et un export asynchrone (job, comme les imports) au-delà ; format stable, colonnes versionnées.
• Alertes d'administration : agent en échec répété, agent dont le coût dévie fortement de sa moyenne, skill partagé massivement édité, modèle devenu indisponible chez le fournisseur.
• Comparaison de modèles sur les données réelles : pour un même agent, qualité perçue (feedbacks), coût et latence par modèle — l'écran qui permet de choisir un modèle pour une raison, pas par habitude.

Critères de sortie. Un admin répond depuis l'interface, sans SQL, aux questions du constat d'entrée (qui coûte, qui échoue, quoi optimiser) ; les exports sont utilisés par au moins un processus réel (revue mensuelle) plutôt que seulement testés.

5. Chantier C — Sécurité offensive : campagne d'injection de prompt

Méthode. Constituer une suite d'attaques reproductibles (fixtures, exécutées en CI sur le mode offline quand c'est possible, et contre un fournisseur de test sinon) couvrant les trois surfaces du document parent §16.4 :

Surface	Scénarios types
Contenus lus (pages, courriels, messages, fichiers, résultats web/MCP)	Instruction cachée demandant une écriture, une exfiltration vers un outil externe, ou la désactivation d'une approbation
Skills et instructions partagés	Skill qui tente d'élargir ses outils, de se rendre obligatoire, de faire taire la nomination du skill dans la réponse
Descriptions de skills	Description écrite pour capter des demandes hors sujet (détournement du routeur)
Délégations	Un sous-agent qui tente de faire exécuter par le parent une action hors de son propre périmètre
Données tabulaires / fichiers	Instructions dans les cellules, les noms de fichiers, les métadonnées

Règle de lecture des résultats. La défense attendue n'est pas « le modèle refuse poliment » — c'est la gouvernance refuse mécaniquement : l'outil n'existe pas, l'accès n'est pas accordé, l'approbation n'a pas été donnée. Un scénario où le modèle « a failli » mais où le contrôle a tenu est un succès du système et doit être consigné comme tel ; un scénario où seul le modèle a tenu (aucun contrôle mécanique derrière) est une faille à corriger par un contrôle, pas par un meilleur prompt.

Critères de sortie. La suite tourne en CI ; chaque scénario est classé (contrôle mécanique / comportement modèle) ; les scénarios reposant sur le seul comportement ont donné lieu à un ticket de contrôle ou à une acceptation de risque explicite et datée.

6. Chantier D — Rétention, archivage et performance des journaux

Travaux.

• Politique de rétention par type de journal, réglable par workspace : runs interactifs, runs autonomes, ledger (le plus long — c'est une pièce comptable), actions et leurs snapshots d'annulation, fichiers de runs (déjà en Phase 4).
• Archivage : extraction périodique des journaux expirés vers un fichier du volume de sauvegarde avant suppression ; la suppression d'un run archivé laisse une tombe (identifiant, dates, agent, statut) pour garder les références des exports.
• Performance : vérifier sur les volumes réels les index posés aux Phases 2 et 4 ; ajouter les index que les requêtes d'Activity/Insights réclament (et seulement ceux-là) ; solder automatiquement les runs orphelins dans tous les chemins de redémarrage (le solde au démarrage existe depuis la Phase 2 — l'étendre aux états waiting_approval expirés).
• Limites de taille des champs JSON de journal (sources_json, trigger_payload_json) : tronquer par conception (références, pas de contenus), avec un test qui échoue si un payload dépasse le plafond.

Critères de sortie. Sur les volumes du constat d'entrée projetés à 12 mois, Activity et Insights répondent dans les cibles du document parent §17 ; la politique de rétention est appliquée par un job observable (compte rendu de purge), pas par une promesse.

7. Chantier E — Skills API publique et publication externe

Travaux.

• Enrichir /api/v2/skills : lister les skills d'une base de skills donnée (avec jeton Bearer scopé et ACL de la base), lire la sérialisation SKILL.md et le bundle complet par skill, et recevoir un webhook skill.updated permettant aux consommateurs externes de resynchroniser (le pendant serveur du badge de copie périmée de la Phase 1).
• Page de documentation d'API correspondante dans l'OpenAPI v2 existant, avec le format SKILL.md décrit comme le format d'échange externe de référence.
• Option de « publication » d'une base : un réglage de la base qui la rend listable par l'API avec un jeton dédié (lecture seule), sans ouvrir l'API générale du workspace.

Critères de sortie. Un agent externe de démonstration (par exemple un agent local) consomme une base de skills Flowdeck par l'API et se resynchronise sur un skill.updated sans intervention manuelle.

8. Chantier F — Préparer (ou écarter) le serveur MCP et le SDK d'agents

Ces deux sujets sont des chantiers voisins déjà identifiés côté Flowdeck (conception d'un serveur MCP officiel dans FLOWDECK_MCP_SERVER_GUIDE.md, non implémentée). Cette phase ne les réalise pas ; elle produit la décision cadrée :

• Serveur MCP : les prérequis produits par les Phases 1 à 4 sont réunis (API v2 agents/skills complète, jetons scopés, journal d'audit) ; le cadrage consiste à lister les outils que le serveur exposerait (lecture/écriture de pages et bases, skills, runs d'agents) et leur correspondance exacte avec l'API v2, puis à décider au vu de l'usage réel des agents externes.
• SDK d'agents : la question est de savoir si des applications externes doivent pouvoir continuer une conversation d'agent en streaming ; l'API v2 actuelle est synchrone (SSE tamponné) ; le cadrage évalue le besoin sur les intégrations réelles avant tout développement.
• Dans les deux cas, « écarter pour l'instant, avec la raison et la date de réexamen » est une sortie valide de la phase — l'important est que la décision soit prise sur les données du §2, pas laissée en suspens.

Critères de sortie. Une note de décision par sujet, rangée avec les documents de la solution, avec périmètre, prérequis vérifiés et date de réexamen.

9. Chantier G — Qualité des agents : évaluation continue

Travaux.

• Pour les Custom Agents les plus utilisés : constituer des jeux d'évaluation (entrées réelles anonymisées + sorties attendues ou critères de jugement), rejoués à chaque changement d'instructions, de modèle ou de version — le pendant des tests pour des objets configurés par des non-développeurs.
• Brancher ces évaluations sur l'écran de restauration de version (Phase 3) : avant de restaurer, on peut évaluer l'ancienne configuration sur le jeu de l'agent.
• Feedback 👍/👎 (existant) agrégé par agent, par skill et par modèle dans les Insights — en fermant la boucle ouverte dès la Phase 2 (les feedbacks existent, leur agrégation utile attendait les volumes).

Critères de sortie. Les trois agents les plus utilisés du workspace ont un jeu d'évaluation versionné ; un changement de modèle sur l'un d'eux a été décidé avec son rapport d'évaluation.

10. Tests transverses de la phase

#	Cas
T-01	La suite d'injection (chantier C) tourne en CI et classe chaque scénario
T-02	Le corpus du routeur élargi (chantier A) est une fixture permanente ; les seuils livrés le passent
T-03	Rétention : la purge archive avant de supprimer, et les tombes gardent les références des exports
T-04	Skills API : un jeton scopé à une base ne peut pas lister une autre base
T-05	Évaluation d'agent (chantier G) : rejouer un jeu donne le même verdict sur la même configuration (déterminisme en mode offline)

11. Critères de sortie

• Le constat d'entrée (§2) existe et chaque chantier mené y répond explicitement.
• Au moins les chantiers C (sécurité) et D (rétention/performance) sont menés : ce sont les deux seuls qui relèvent de la dette plutôt que de l'opportunité.
• Chaque chantier non mené a une raison datée, pas un oubli.
• Le document parent passe en version finale de la série (« Phases 1 à 5 closes ») avec un bilan honnête : ce qui a été livré, ce qui a été écarté, ce qui reste ouvert.

12. Ce que cette phase ne doit pas devenir

• Pas un fourre-tout de fonctionnalités ajournées. Si une fonctionnalité visible manque, elle appartient à un correctif des Phases 1 à 4, pas à cette phase.
• Pas d'optimisation sans mesure. Aucun seuil, aucun cache, aucun index sans le constat qui le demande.
• Pas de machine learning maison pour le routeur. L'amélioration passe par le corpus, les seuils et les descriptions — les actifs que l'équipe peut relire et corriger.
• Pas de seconde plateforme d'administration. Tout ce que cette phase ajoute vit dans les écrans existants (Library, page agent, réglages IA).

---

Document de phase 5/5 — le dernier de la série. La solution est complète dès la Phase 4 ; cette phase la rend durable.