agent-architecture-audit

Audit de l'Architecture d'Agent

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

Quand Activer

OBLIGATOIRE pour :

• Publier toute application pilotée par un agent ou un LLM en production
• Livrer des fonctionnalités utilisant des appels d'outils, de la mémoire ou des workflows en plusieurs étapes
• Le comportement de l'agent se dégrade après l'ajout de couches d'encapsulation
• L'utilisateur signale que « l'agent empire » ou que « les outils sont instables »
• Le même modèle fonctionne dans le playground mais échoue dans votre encapsulation
• Déboguer le comportement d'un agent pendant plus de 15 minutes sans trouver la cause racine

Particulièrement critique lorsque :

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

Ne pas utiliser pour :

• Le débogage général du code — utilisez agent-introspection-debugging
• La revue de code — utilisez des agents de révision spécifiques au langage
• Le scan de sécurité — utilisez security-review ou security-review/scan
• L'évaluation comparative des performances d'agent — utilisez agent-eval
• L'écriture de nouvelles fonctionnalités — utilisez la compétence de workflow appropriée

La Pile en 12 Couches

Chaque système d'agent possède ces couches. N'importe laquelle 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 obsolète provenant des tours précédents
3	Mémoire à long terme	Pollution entre les sessions, anciens sujets dans de nouvelles conversations
4	Distillation	Artefacts compressés qui réintègrent sous forme de pseudo-faits
5	Rappel actif	Couches de résumé redondantes qui gaspillent du contexte
6	Sélection d'outils	Aiguillage vers le mauvais outil, le modèle ignore 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 du format dans la réponse finale
10	Rendu de la plateforme	Mutation au niveau du transport (UI, API, CLI modifie des réponses valides)
11	Boucles de réparation cachées	Agents de secours/réessai silencieux qui exécutent un second passage LLM
12	Persistance	État expiré ou artefacts mis en cache réutilisés comme preuve en direct

Modèles de Défaillance Courants

1. Régression d'Encapsulation

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

Symptômes :

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

2. Contamination de la Mémoire

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

Symptômes :

• L'agent évoque des sujets passés sans rapport
• Les corrections de l'utilisateur ne persistent pas (l'ancienne mémoire écrase la nouvelle)
• Des artefacts de la même session réintègrent sous forme de pseudo-faits
• La mémoire croît sans limite, dégradant la qualité des réponses avec le temps

3. Échec de Discipline d'Outils

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

Symptômes :

• « Doit utiliser l'outil X » dans l'invite, mais le modèle répond sans l'appeler
• Les résultats des outils 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 le devrait pas, ou l'ignore quand il le doit

4. Corruption de Rendu/Transport

La réponse interne de l'agent est correcte, mais la couche plateforme la modifie pendant 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 secours caché remplace silencieusement la réponse avant livraison
• La sortie diffère entre le terminal et l'interface utilisateur

5. Couches d'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
• Les boucles de « correction automatique » 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 : Cadrage

Définissez ce que vous auditez :

• Système cible — quelle application agent ?
• Points d'entrée — comment les utilisateurs interagissent-ils avec elle ?
• 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 depuis la base de code :

• Code source — boucle d'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 sessions

Utilisez rg pour rechercher des anti-patrons :

# Exigences d'outils exprimées uniquement dans le texte de l'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 principale de l'agent
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 secours qui exécutent des appels LLM supplémentaires
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts

# Mutation silencieuse de la 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 l'encapsulation le provoque
• Couche source — laquelle des 12 couches
• Cause racine — la cause la plus profonde
• Preuve — référence fichier:ligne ou log:ligne
• Confiance — 0.0 à 1.0

Phase 4 : Stratégie de Correction

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

1. Imposer les exigences d'outils dans le code — appliquer dans le code, pas seulement dans le texte de l'invite
2. Supprimer ou limiter les agents de réparation cachés — rendre le secours explicite avec des contrats
3. Réduire la duplication de contexte — mêmes informations via invite + historique + mémoire + distillation
4. Resserer l'admission mémoire — corrections utilisateur > assertions de l'agent
5. Resserer les déclencheurs de distillation — ne pas compresser ce qui ne doit pas l'être
6. Réduire la mutation de rendu — laisser passer, ne pas transformer
7. Passer à des enveloppes JSON typées — flux interne structuré, pas de prose libre

Modèle de Sévérité

Niveau	Signification	Action
critique	L'agent peut produire avec assurance un comportement opérationnel erroné	Corriger avant la prochaine version
élevé	L'agent dégrade fréquemment la justesse ou la stabilité	Corriger dans ce sprint
moyen	La justesse survit généralement mais la sortie est fragile ou gaspilleuse	Planifier pour le prochain cycle
faible	Problèmes surtout cosmétiques ou de maintenabilité	Mettre dans le backlog

Format de Sortie

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

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

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 d'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 imposé dans le code
2	Le contenu d'anciennes conversations apparaît-il dans de nouveaux tours ?	Contamination de la 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 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 de l'invite ?	Échec de discipline d'outils
7	Le propre monologue de l'agent peut-il devenir une mémoire persistante ?	Empoisonnement de la mémoire

Anti-Patrons à Éviter

• Évitez de blâmer le modèle avant d'infirmer les régressions des couches d'encapsulation.
• É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 de l'invite lorsque le code ne l'applique jamais.
• Gardez les constats directs, étayés 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 Connexes

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