audit-architecture-agent

Audit d'Architecture Agent

Un workflow de diagnostic pour les systèmes agent qui cachent leurs défaillances derrière des couches d'encapsulation, une mémoire périmée, des boucles de réessai ou des mutations de transport/rendu.

Quand Activer

OBLIGATOIRE pour :

• Publication en production de toute application agent ou LLM
• Livraison de fonctionnalités utilisant l'appel d'outils, la mémoire ou les workflows multi-étapes
• Dégradation du comportement de l'agent après ajout de couches d'encapsulation
• Signalement par l'utilisateur que "l'agent empire" ou "les outils sont instables"
• Même modèle fonctionne en playground mais échoue dans votre wrapper
• Débogage du comportement de l'agent pendant plus de 15 minutes sans trouver la cause racine

Particulièrement critique quand :

• Vous avez ajouté de nouvelles couches d'invite, définitions d'outils ou systèmes mémoire
• Différents agents dans votre système se comportent de manière incohérente
• Le modèle fonctionnait bien hier mais hallucine aujourd'hui
• Vous suspectez des boucles de réparation/réessai cachées qui modifient silencieusement les réponses

Ne pas utiliser pour :

• Débogage général de code — utilisez agent-introspection-debugging
• Revue de code — utilisez des agents de révision spécifiques au langage
• Analyse de sécurité — utilisez security-review ou security-review/scan
• Évaluation comparative des performances agent — utilisez agent-eval
• Rédaction de nouvelles fonctionnalités — utilisez la compétence de workflow appropriée

La Pile en 12 Couches

Tout système agent possède ces couches. Chacune peut corrompre la réponse :

#	Couche	Ce qui peut mal tourner
1	Invite système	Instructions contradictoires, gonflement des instructions
2	Historique de session	Injection de contexte périmé depuis des tours précédents
3	Mémoire à long terme	Pollution entre sessions, anciens sujets dans de nouvelles conversations
4	Distillation	Artefacts compressés réintégrés comme pseudo-faits
5	Rappel actif	Couches de re-résumé redondantes gaspillant le contexte
6	Sélection d'outils	Routage d'outil incorrect, le modèle saute les outils requis
7	Exécution d'outils	Exécution hallucinée — prétend appeler mais ne le fait pas
8	Interprétation d'outils	Sortie d'outil mal lue ou ignorée
9	Mise en forme de la réponse	Corruption de format dans la réponse finale
10	Rendu de plateforme	Mutation au niveau du transport (UI, API, CLI modifie des réponses valides)
11	Boucles de réparation cachées	Agents de repli/réessai silencieux exécutant un second passage LLM
12	Persistance	État expiré ou artefacts en cache réutilisés comme preuve vivante

Schémas de Défaillance Courants

1. Régression d'Encapsulation

Le modèle de base produit des réponses correctes, mais les couches wrapper les dégradent.

Symptômes :

• Le modèle fonctionne bien en playground ou via appel API direct, mais échoue dans votre agent
• Ajout d'une nouvelle couche d'invite, comportement existant dégradé
• L'agent semble confiant mais a tort avec confiance
• "Ça marchait avant la dernière mise à jour"

2. Contamination Mémoire

Les anciens sujets fuient dans les nouvelles conversations via l'historique, la récupération mémoire ou la distillation.

Symptômes :

• L'agent évoque des sujets passés non pertinents
• Les corrections de l'utilisateur ne persistent pas (vieux souvenirs écrasent les nouveaux)
• Les artefacts de la même session réintègrent comme pseudo-faits
• La mémoire croît sans limite, dégradant la qualité des réponses avec le temps

3. Défaillance de Discipline d'Outils

Les outils sont déclarés dans l'invite mais pas appliqués dans le code. Le modèle les saute ou hallucine leur exécution.

Symptômes :

• "Doit utiliser l'outil X" dans l'invite, mais l'agent répond sans l'appeler
• Les résultats d'outil semblent corrects mais n'ont jamais été exécutés
• Différents outils se disputent la même responsabilité
• Le modèle utilise un outil quand il ne devrait pas, ou le saute quand il le doit

4. Corruption de Rendu/Transport

La réponse interne de l'agent est correcte, mais la couche plateforme la modifie lors de la livraison.

Symptômes :

• Les logs montrent une réponse correcte, l'utilisateur voit une sortie erronée
• Le rendu Markdown, l'analyse JSON ou les fragments de streaming corrompent des réponses valides
• Un agent de repli caché remplace silencieusement la réponse avant livraison
• La sortie diffère entre le terminal et l'interface utilisateur

5. Couches Agent Cachées

Des agents de réparation, réessai, résumé ou rappel silencieux s'exécutent sans contrats explicites.

Symptômes :

• La sortie change entre la génération interne et la livraison à l'utilisateur
• Des boucles "d'auto-correction" exécutent un second passage LLM que l'utilisateur ignore
• Plusieurs agents modifient la même sortie sans coordination
• Les réponses sont "lissées" ou "corrigées" par des couches invisibles

Workflow d'Audit

Phase 1 : Périmètre

Définissez ce que vous auditez :

• Système cible — quelle application agent ?
• Points d'entrée — comment les utilisateurs interagissent-ils ?
• Pile de modèles — quel(s) LLM et fournisseurs ?
• Symptômes — que signale l'utilisateur ?
• Fenêtre temporelle — quand cela a-t-il commencé ?
• Couches à auditer — lesquelles des 12 couches s'appliquent ?

Phase 2 : Collecte de Preuves

Rassemblez des preuves dans la base de code :

• Code source — boucle agent, routeur d'outils, admission mémoire, assemblage d'invite
• Logs — traces de sessions historiques, enregistrements d'appels d'outils
• Configuration — modèles d'invite, schémas d'outils, paramètres fournisseur
• Fichiers mémoire — SOP, bases de connaissances, archives de session

Utilisez rg pour rechercher des anti-patrons :

# Exigences d'outils exprimées uniquement dans le texte d'invite (pas dans le code)
rg "must.*tool|必须.*工具|required.*call" --type md

# Exécution d'outils sans validation
rg "tool_call|toolCall|tool_use" --type py --type ts

# Appels LLM cachés en dehors de la boucle agent principale
rg "completion|chat\.create|messages\.create|llm\.invoke"

# Admission mémoire sans priorité de correction utilisateur
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts

# Boucles de repli exécutant des appels LLM supplémentaires
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts

# Mutation silencieuse de sortie
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts

Phase 3 : Cartographie des Défaillances

Pour chaque constat, documentez :

• Symptôme — ce que l'utilisateur voit
• Mécanisme — comment le wrapper le cause
• Couche source — laquelle des 12 couches
• Cause racine — la cause la plus profonde
• Preuve — fichier:ligne ou log:référence de ligne
• Confiance — 0.0 à 1.0

Phase 4 : Stratégie de Correction

Ordre de correction par défaut (code d'abord, pas invite d'abord) :

1. Code-gate les exigences d'outils — appliquer dans le code, pas seulement dans le texte d'invite
2. Supprimer ou réduire les agents de réparation cachés — rendre le repli explicite avec des contrats
3. Réduire la duplication de contexte — même info via invite + historique + mémoire + distillation
4. Resserrer l'admission mémoire — corrections utilisateur > affirmations de l'agent
5. Resserrer les déclencheurs de distillation — ne pas compresser ce qui ne devrait pas l'être
6. Réduire la mutation de rendu — passage direct, ne pas transformer
7. Convertir en enveloppes JSON typées — flux interne structuré, pas de prose libre

Modèle de Sévérité

Niveau	Signification	Action
critical	L'agent peut produire avec confiance un comportement opérationnel erroné	Corriger avant la prochaine version
high	L'agent dégrade fréquemment l'exactitude ou la stabilité	Corriger dans ce sprint
medium	L'exactitude survit généralement mais la sortie est fragile ou gaspilleuse	Planifier pour le prochain cycle
low	Problèmes principalement cosmétiques ou de maintenabilité	Backlog

Format de Sortie

Présentez les résultats à l'utilisateur dans cet ordre :

1. Résultats classés par sévérité (les plus critiques en premier)
2. Diagnostic d'architecture (quelle couche a corrompu quoi, et pourquoi)
3. Plan de correction ordonné (code d'abord, pas invite d'abord)

Ne commencez pas par des compliments ou des résumés. Si le système est cassé, dites-le directement.

Questions de Diagnostic Rapide

Lors de l'audit d'un système agent, répondez à celles-ci :

#	Question	Si Oui →
1	Le modèle peut-il ignorer un outil requis et quand même répondre ?	Outil non verrouillé par le code
2	Le contenu d'anciennes conversations apparaît-il dans de nouveaux tours ?	Contamination mémoire
3	Les mêmes informations sont-elles dans l'invite système ET la mémoire ET l'historique ?	Duplication de contexte
4	La plateforme exécute-t-elle un second passage LLM avant la livraison ?	Boucle de réparation cachée
5	La sortie diffère-t-elle entre la génération interne et la livraison à l'utilisateur ?	Corruption de rendu
6	Les règles "doit utiliser l'outil X" sont-elles uniquement dans le texte d'invite ?	Défaillance de discipline d'outils
7	Le propre monologue de l'agent peut-il devenir une mémoire persistante ?	Empoisonnement mémoire

Anti-Patrons à Éviter

• Évitez de blâmer le modèle avant d'avoir falsifié les régressions de couche wrapper.
• Évitez de blâmer la mémoire sans montrer le chemin de contamination.
• Ne laissez pas un état actuel propre effacer un incident historique sale.
• Ne traitez pas la prose Markdown comme un protocole interne fiable.
• N'acceptez pas "doit utiliser l'outil" dans le texte d'invite quand le code ne l'applique jamais.
• Gardez les résultats directs, soutenus par des preuves et classés par sévérité.

Schéma de Rapport

Les audits doivent produire des rapports structurés suivant cette forme :

{
  "schema_version": "ecc.agent-architecture-audit.report.v1",
  "executive_verdict": {
    "overall_health": "high_risk",
    "primary_failure_mode": "string",
    "most_urgent_fix": "string"
  },
  "scope": {
    "target_name": "string",
    "model_stack": ["string"],
    "layers_to_audit": ["string"]
  },
  "findings": [
    {
      "severity": "critical|high|medium|low",
      "title": "string",
      "mechanism": "string",
      "source_layer": "string",
      "root_cause": "string",
      "evidence_refs": ["file:line"],
      "confidence": 0.0,
      "recommended_fix": "string"
    }
  ],
  "ordered_fix_plan": [
    { "order": 1, "goal": "string", "why_now": "string", "expected_effect": "string" }
  ]
}

Compétences Associées

• agent-introspection-debugging — Déboguer les défaillances d'exécution des agents (boucles, timeouts, erreurs d'état)
• agent-eval — Évaluer les performances des agents en comparaison directe
• security-review — Audit de sécurité pour le code et la configuration
• autonomous-agent-harness — Configurer des opérations d'agents autonomes
• agent-harness-construction — Construire des harnais d'agents à partir de zéro