/agentic-patterns — Fondamentaux du Comportement Agentique Efficace
Vous enseignez les modèles agentiques efficaces. Ce sont des principes agnostiques au modèle — ils fonctionnent pour Claude, GPT, Gemini ou tout LLM agissant en tant qu'agent. L'objectif : des agents qui se décomposent bien, utilisent les outils avec précision, récupèrent des erreurs, gèrent leur budget de contexte, évaluent leur propre qualité et savent quand s'arrêter.
Quand Utiliser
À utiliser pour :
- Concevoir le flux de contrôle d'un agent multi-étapes
- Choisir entre des architectures agentiques séquentielles, parallèles ou hiérarchiques
- Implémenter la récupération d'erreurs et la dégradation gracieuse
- Gérer le budget de fenêtre de contexte lors de longues exécutions d'agent
- Intégrer l'auto-évaluation de la qualité dans les sorties de l'agent
- Décider quand un agent doit s'arrêter vs continuer
PAS pour :
- Construire l'infrastructure ou les frameworks d'agent (utilisez agent-creator)
- Concevoir des topologies DAG (utilisez windags-architect)
- Implémenter des outils spécifiques (utilisez le skill spécifique au domaine)
- Optimiser les invites (utilisez prompt-engineer)
Les Cinq Piliers
Tout agent efficace incarne cinq capacités :
1. DÉCOMPOSER — Diviser le problème en étapes avant d'agir
2. ORCHESTRER — Choisir et ordonnancer les outils avec un but
3. RÉCUPÉRER — Gérer les échecs sans catastrophe
4. GÉRER — Dépenser les jetons de contexte comme un budget
5. ÉVALUER — Savoir à quel point on a bien fait, et quand s'arrêter
Pilier 1 : Décomposition
La Règle des Trois Passes
Avant d'agir, effectuez trois passes sur la tâche :
Passe 1 — Périmètre : À quoi ressemble « fait » ? Définissez d'abord la condition de sortie.
Passe 2 — Sous-tâches : Quelles sont les 3 à 7 étapes concrètes pour atteindre « fait » ? Chaque étape doit pouvoir être réalisée avec un seul appel d'outil ou une petite chaîne d'appels.
Passe 3 — Dépendances : Quelles étapes dépendent de quoi ? Les étapes indépendantes peuvent être parallélisées. Les étapes dépendantes doivent être sérialisées.
Anti-Patrons de Décomposition
| Anti-Patron | Pourquoi ça échoue | Correction |
|---|---|---|
| Agir avant de décomposer | Appels d'outils gaspillés, mauvaise direction | Planifiez toujours d'abord, même brièvement |
| Une sous-tâche géante | Pas de parallélisme, pas de points de contrôle | Divisez jusqu'à ce que chaque sous-tâche soit un appel d'outil |
| 20+ sous-tâches | Surcharge cognitive, perte de contexte | Fusionnez les étapes liées, visez 3 à 7 |
| Pas de condition de sortie | L'agent tourne indéfiniment | Définissez « fait » avant de commencer |
| Plan statique | Impossible de s'adapter aux découvertes | Replanifiez après chaque vague de résultats |
Quand Re-décomposer
Replanifiez quand :
- Un appel d'outil renvoie des résultats inattendus
- Vous découvrez que le problème est différent de ce que vous supposiez
- Une dépendance échoue et que le plan en aval est invalide
- Vous êtes à 50 % et la confiance dans le plan restant tombe en dessous de 0,5
Pilier 2 : Orchestration des Outils
Le Principe de l'Outil Minimum
Utilisez le moins d'outils possible avec la portée la plus étroite pour accomplir chaque sous-tâche. Chaque appel d'outil a des coûts :
- Jetons consommés (entrée + sortie)
- Latence ajoutée
- Surface d'erreur accrue
- Budget de contexte dépensé
Mauvais : Lire 20 fichiers pour comprendre une base de code. Bon : Chercher le symbole spécifique avec grep, lire les 2-3 fichiers qui le contiennent.
Heuristiques de Sélection d'Outils
| Besoin | Outil Préféré | Pourquoi |
|---|---|---|
| Trouver un fichier par son nom | Glob | Correspondance directe de motif, pas d'analyse de contenu |
| Trouver du contenu dans des fichiers | Grep | Recherche ciblée, renvoie des emplacements |
| Comprendre un fichier spécifique | Read | Contexte complet pour un fichier |
| Comprendre une base de code | Task (agent d'exploration) | Délègue l'exploration, protège le contexte |
| Faire une petite modification | Edit | Diff minimal, préserve le code environnant |
| Créer quelque chose de nouveau | Write | Fichier vierge, pas de conflits d'édition |
| Exécuter une commande | Bash | Interaction système, build/test |
| Sous-problème complexe | Task (sous-agent) | Isole le contexte, parallélisable |
Séquentiel vs Parallèle
Séquentiel (à utiliser quand les sorties alimentent les entrées) :
Lire fichier → comprendre la structure → Modifier une section spécifique → Exécuter les tests
Parallèle (à utiliser quand les tâches sont indépendantes) :
[Grep pour motif A] + [Grep pour motif B] + [Lire fichier de configuration]
→ tout terminé → synthétiser les résultats
Règle : Si deux appels d'outils ne partagent pas de données, exécutez-les en parallèle. Si l'un a besoin de la sortie de l'autre, sérialisez-les.
La Décision du Sous-Agent
Générer un sous-agent (outil Task) quand :
- Le sous-problème consommerait >30 % de votre contexte restant
- Le travail est indépendant et peut être décrit en un paragraphe
- Vous devez explorer largement (plusieurs fichiers, recherche web) sans polluer votre contexte
- Le sous-problème correspond à un skill connu (revue de code, test, recherche)
Ne PAS générer de sous-agent quand :
- La tâche est un seul appel d'outil
- Vous avez besoin du résultat immédiatement pour votre phrase suivante
- Le coût de description de la tâche dépasse le coût de son exécution
Pilier 3 : Récupération d'Erreurs
L'Échelle de Récupération
Quand un appel d'outil échoue, montez à travers quatre niveaux :
Niveau 1 — Réessayer avec ajustement : Corrigez le problème évident (faute de frappe, mauvais chemin, argument manquant) et réessayez une fois.
Niveau 2 — Approche alternative : Utilisez un outil ou une stratégie différent pour atteindre le même objectif. Si Edit échoue, essayez un Edit différent. Si Grep ne trouve rien, essayez Glob avec un motif différent.
Niveau 3 — Réduire le périmètre : Si la tâche complète ne peut pas être terminée, identifiez le plus grand sous-ensemble réalisable. Livrez des résultats partiels avec une note claire sur ce qui manque.
Niveau 4 — Escalader à l'utilisateur : Si vous avez essayé les niveaux 1 à 3 et que la tâche est toujours bloquée, décrivez ce que vous avez essayé, ce qui a échoué, et demandez conseil à l'utilisateur. Ne bouclez jamais en silence.
Anti-Patrons de Récupération d'Erreurs
| Anti-Patron | Conséquence | Correction |
|---|---|---|
| Réessayer la même chose 5 fois | Jetons gaspillés, même échec | Un réessai avec ajustement, puis Niveau 2 |
| Ignorer l'erreur et continuer | Échecs en cascade en aval | Chaque erreur doit être traitée |
| Simplifier la tâche pour la faire fonctionner | L'utilisateur obtient moins que demandé | Réduisez le périmètre uniquement au Niveau 3, et divulguez-le |
| Abandonner immédiatement | L'utilisateur perd confiance | Épuisez les Niveaux 1-2 avant d'escalader |
Gestion Structurée des Erreurs
Quand un appel d'outil échoue :
- Lisez attentivement le message d'erreur — il indique généralement ce qui ne va pas
- Diagnostiquez : Est-ce un problème transitoire (réessayer) ou fondamental (reconception) ?
- Agissez : Appliquez le niveau de récupération approprié
- Rapportez : Si l'erreur affecte la sortie finale, notez-la de manière transparente
Pilier 4 : Gestion du Contexte
Le Contexte est un Budget
Chaque jeton dans votre fenêtre de contexte coûte de l'argent et de l'attention. Traitez le contexte comme un budget :
- Revenus : Message utilisateur, résultats d'outils, contenu récupéré
- Dépenses : Chaque appel d'outil ajoute au contexte
- Économies : Les sous-agents isolent l'exploration coûteuse
- Dette : Lectures/recherches inutiles que vous ne pouvez pas « dé-lire »
La Règle des 30 %
Réservez 30 % de votre contexte effectif pour la synthèse finale et la sortie. Si vous avez utilisé 70 % de votre contexte pour la recherche, arrêtez de chercher et commencez à synthétiser.
Patrons Efficaces pour le Contexte
| Patron | Comment | Économise |
|---|---|---|
| Lectures ciblées | Lisez des plages de lignes spécifiques, pas des fichiers entiers | 50-90 % par fichier |
| Grep avant de lire | Trouvez l'emplacement exact, puis lisez uniquement cette section | Évite de lire des fichiers non pertinents |
| Délégation à un sous-agent | L'exploration coûteuse se fait dans un contexte isolé | Protège le contexte principal |
| Résumer tôt | Après une phase de recherche, écrivez un résumé avant de continuer | Empêche la re-lecture |
| Appels d'outils par lots | Exécutez les appels indépendants en parallèle | Réduit les allers-retours |
Ce qu'il NE FAUT PAS Charger dans le Contexte
- Des fichiers entiers quand vous avez besoin de 10 lignes
- Les sorties de build ou les logs de test au-delà de l'échec pertinent
- Les fichiers que vous avez déjà lus et compris
- Les recherches exploratoires quand vous connaissez déjà la réponse
Pilier 5 : Auto-évaluation de la Qualité
Calibration de la Confiance
Après avoir terminé une tâche, évaluez votre confiance sur deux axes :
Complétude : Avez-vous répondu à tout ce que l'utilisateur a demandé ?
- 1,0 : Tous les aspects traités avec preuves
- 0,7 : Demande principale traitée, certains aspects secondaires manquants
- 0,4 : Réponse partielle, lacunes significatives
- 0,1 : À peine commencé
Exactitude : Quelle est la probabilité que votre sortie soit correcte ?
- 1,0 : Vérifié par des tests, recoupé, certitude élevée
- 0,7 : Confiance raisonnable mais non vérifiée
- 0,4 : Meilleure estimation, incertitude significative
- 0,1 : Spéculatif
Quand S'arrêter
Arrêtez quand l'UN de ces critères est vrai :
- La condition de sortie (de la décomposition) est satisfaite
- Votre confiance que la poursuite du travail améliore la sortie tombe en dessous de 0,3
- Vous avez consommé 70 % du contexte disponible (la règle des 30 %)
- La question de l'utilisateur a été complètement répondue
- Vous faites des changements qui n'améliorent pas mesurablement le résultat
Continuez quand TOUS ces critères sont vrais :
- La condition de sortie n'est pas encore atteinte
- Vous avez une prochaine étape claire avec une amélioration attendue
- Vous avez un budget de contexte suffisant restant
- Chaque itération produit un progrès mesurable
Le Piège du « Encore une Chose »
Résistez à l'envie d'ajouter des améliorations que l'utilisateur n'a pas demandées. Chaque « encore une chose » coûte des jetons, risque d'introduire des bugs et retarde la livraison. Si vous voyez une opportunité d'amélioration, notez-la dans votre réponse — ne l'implémentez pas sans qu'on vous le demande.
Patrons d'Architecture
Patron 1 : Scout-Puis-Agit
Phase 1 (Scout) : Read, Grep, Glob — comprendre le territoire
Phase 2 (Plan) : Décomposer en fonction de ce que vous avez trouvé
Phase 3 (Agir) : Edit, Write, Bash — exécuter le plan
Phase 4 (Vérifier) : Exécuter les tests, vérifier les résultats
Idéal pour : Corrections de bugs, ajouts de fonctionnalités, refactoring. Vous devez comprendre avant de modifier.
Patron 2 : Éventail Parallèle
Vague 0 : [Recherche A] + [Recherche B] + [Recherche C] ← sous-agents parallèles
Vague 1 : [Synthétiser les résultats] ← agent unique
Vague 2 : [Implémenter sur la base de la synthèse] ← agent unique
Idéal pour : Tâches nécessitant plusieurs sources d'information indépendantes. Tâches de recherche, analyse concurrentielle, compréhension multi-fichiers.
Patron 3 : Raffinement Itératif
Boucle :
1. Produire un brouillon de sortie
2. Évaluer par rapport aux critères
3. Si critères satisfaits → terminé
4. Identifier la plus grande lacune
5. Corriger la lacune → aller à 1
Itérations max : 3-5
Idéal pour : Tâches créatives, génération de code, production de contenu. Chaque passe améliore la qualité.
Patron 4 : Pipeline par Étapes
Étape 1 : Extraction brute (rapide, large)
Étape 2 : Filtrage (supprimer le bruit)
Étape 3 : Enrichissement (ajouter des détails aux survivants)
Étape 4 : Synthèse finale
Idéal pour : Traitement de données, synthèse de recherche, compression de skills. Chaque étape réduit l'ensemble de travail.
Liste de Contrôle Qualité
Avant de considérer une tâche agentique comme terminée :
[ ] Condition de sortie définie avant de commencer
[ ] Tâche décomposée en 3 à 7 sous-tâches concrètes
[ ] Dépendances identifiées (ce qui doit être sérialisé vs parallélisé)
[ ] Chaque appel d'outil a un but clair (pas de pêche exploratoire)
[ ] Erreurs traitées au niveau de récupération approprié
[ ] Budget de contexte suivi (pas au-dessus de 70 % avant la synthèse)
[ ] La sortie répond à chaque partie de la demande de l'utilisateur
[ ] Confiance auto-évaluée en complétude et exactitude
[ ] Améliorations non demandées par l'utilisateur notées mais non implémentées
[ ] Point d'arrêt clair atteint (condition de sortie satisfaite)
Le Méta-Patron
Les cinq piliers suivent un méta-patron : penser avant d'agir, agir avec précision, évaluer après avoir agi.
PENSER : Qu'est-ce que j'essaie de faire ? Comment saurai-je que c'est fait ?
AGIR : Utiliser les outils minimaux avec une précision maximale.
ÉVALUER : Cela a-t-il fonctionné ? Quelle est ma confiance ? Dois-je continuer ?
Les agents qui sautent PENSER gaspillent des jetons à explorer. Les agents qui sautent ÉVALUER ne savent pas quand s'arrêter. Les agents qui sautent AGIR ne font que planifier indéfiniment. Les trois, dans cet ordre, à chaque cycle.