06 — Agents et sous-agents
Comprendre ce qu'est vraiment un agent, quand en construire un, et quand une bonne vieille requête SQL fait mieux.
Temps de lecture : 6 min (cette page) | Niveau : Intermédiaire
Ce que tu sauras faire après
- Situer cette section dans ton parcours et choisir par où commencer.
- Distinguer les 3 objets qu'on confond tout le temps : appel LLM, workflow, agent.
- Repérer, dans ton quotidien de dev / data engineer, les tâches qui méritent un agent.
- Écrire tes premiers fichiers de sous-agent Claude Code pour tes travaux SQL et Python.
- Décider en 2 minutes si tu construis un agent ou un script.
🎯 Pourquoi cette section
Le mot agent est partout. Il est aussi très mal défini. Beaucoup de gens appellent « agent » un simple appel à un modèle dans une boucle for.
Cette section te donne une définition honnête, sourcée, et surtout utilisable. Anthropic est explicite sur le sujet :
« Workflows are systems where LLMs and tools are orchestrated through predefined code paths. Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage. » — Building Effective Agents, Anthropic
Traduction simple : dans un workflow, c'est ton code qui décide de l'enchaînement. Dans un agent, c'est le modèle qui décide.
Tout le reste de la section découle de cette phrase.
📚 Prérequis
Avant d'attaquer, tu dois être à l'aise avec :
| Prérequis | Où le voir | Pourquoi c'est nécessaire |
|---|---|---|
| Ce qu'est un token, un contexte, une température | 01-fondamentaux-llm | La notion de « contexte isolé » n'a aucun sens sans ça |
| Écrire un prompt structuré (rôle, tâche, contraintes, format) | 02-prompt-engineering-fondamentaux | Un sous-agent, c'est avant tout un prompt système |
| Savoir évaluer une sortie de modèle | 04-evaluation-fiabilite-securite | Un agent qui se trompe en boucle coûte cher |
| Utiliser Claude Code en interactif (fichiers, permissions) | 05-claude-code-bases | Les sous-agents sont une fonctionnalité de Claude Code |
Tu n'as pas besoin de savoir coder en TypeScript. Le fichier sur le SDK donne les exemples en Python et en TypeScript.
🗺️ Ordre de lecture
Lis dans l'ordre. Chaque fichier suppose le précédent.
| # | Fichier | Ce que tu y gagnes | Niveau |
|---|---|---|---|
| 1 | 01-quest-ce-quun-agent.md | La définition honnête + la boucle percevoir-décider-agir-observer | Débutant |
| 2 | 02-subagents-claude-code.md | Créer tes propres sous-agents (fichiers complets fournis) | Intermédiaire |
| 3 | 03-orchestration-multi-agents.md | Faire travailler plusieurs agents ensemble sans exploser la facture | Avancé |
| 4 | 04-agent-sdk.md | Construire ton propre agent en Python ou TypeScript | Avancé |
| 5 | 05-quand-ne-pas-utiliser-un-agent.md | La grille de décision qui t'évite de perdre 3 jours | Débutant |
Astuce si tu es pressé : lis le 01, puis saute directement au 05. Tu auras déjà 80 % de la valeur. Le 02 est celui qui change ton quotidien le plus vite.
🧭 La carte mentale de la section
Retiens ces trois niveaux de complexité. Tu montes d'un cran seulement quand le niveau du dessous ne suffit plus.
Niveau 1 — UN APPEL LLM
Tu poses une question, tu reçois une réponse.
Exemple : "Explique-moi cette requête SQL."
Coût : 1 appel. Prévisible.
Niveau 2 — UN WORKFLOW
Ton code enchaîne plusieurs appels selon un plan FIXE que tu as écrit.
Exemple : extraire le schéma -> générer le SQL -> valider la syntaxe.
Coût : N appels connus d'avance. Prévisible.
Niveau 3 — UN AGENT
Le modèle choisit lui-même ses outils et le nombre d'étapes.
Exemple : "Trouve pourquoi le DAG Airflow 'daily_sales' échoue depuis mardi."
Coût : inconnu d'avance. Puissant mais imprévisible.C'est exactement la recommandation d'Anthropic : commencer simple, et n'ajouter de la complexité que quand le besoin est prouvé.
🛠️ Ce que tu auras construit à la fin
À la fin de cette section, tu auras dans ton projet :
- Un fichier
.claude/agents/auditeur-sql.mdqui relit tes requêtes SQL avant production. - Un fichier
.claude/agents/explorateur-de-schema.mdqui cartographie une base sans polluer ta conversation. - Un fichier
.claude/agents/relecteur-de-notebook.mdpour tes notebooks d'analyse. - Un squelette d'agent Python avec le Claude Agent SDK.
- Une grille de décision imprimable « agent ou script ? ».
⚠️ Deux avertissements avant de commencer
1. Un agent coûte cher en tokens. Anthropic donne deux repères mesurés : un agent consomme environ 4 fois plus de tokens qu'une conversation classique, un système multi-agents environ 15 fois plus. Ce n'est pas un détail quand tu itères toute la journée.
2. La documentation de Claude Code bouge vite. Les noms de champs et d'options cités dans cette section ont été relus sur la documentation officielle en septembre 2026. Certaines fonctionnalités indiquent explicitement une version minimale de Claude Code. Quand un comportement diffère chez toi, vérifie ta version avant de conclure à une erreur du cours.
À retenir
- Un workflow suit un chemin que tu as écrit ; un agent choisit son chemin lui-même.
- On monte en complexité seulement quand le niveau inférieur échoue, jamais par principe.
- La vraie valeur d'un sous-agent au quotidien : le contexte isolé et les outils restreints.
- Le multi-agents multiplie le coût par ~15 : il se justifie sur des tâches parallélisables à forte valeur, pas sur du travail routinier.
- Commence par le fichier 01, applique le fichier 02 dès demain sur un vrai projet.
Depots GitHub a explorer
Les fichiers de cette section te donnent les concepts et les templates. Ces dépôts te donnent le code qui tourne : la boucle d'agent, les fichiers de sous-agents, et les cinq patrons d'orchestration écrits pour de vrai.
| Depot | Ce qu'on y trouve | Par ou commencer |
|---|---|---|
| anthropics/claude-agent-sdk-python | Le SDK Python officiel : boucle d'agent, sous-agents, outils MCP en-process, hooks, plafond de budget | examples/quick_start.py, puis examples/agents.py |
| anthropics/claude-agent-sdk-demos | Huit applications complètes bâties sur le SDK, dont un système de recherche multi-agents avec agent chef et sous-agents parallèles | le dossier research-agent/ |
| anthropics/claude-cookbooks | Les notebooks de référence de l'article « Building Effective Agents » : les patrons d'orchestration codés pas à pas | patterns/agents/basic_workflows.ipynb |
| openai/openai-agents-python | Le SDK d'agents d'OpenAI : les mêmes patrons vus depuis un autre écosystème, utile pour ne pas confondre le concept et l'outil | le dossier examples/agent_patterns/ |
| VoltAgent/awesome-claude-code-subagents | Plus de 160 fichiers de sous-agents Claude Code, en markdown brut, classés par métier | categories/01-core-development/backend-developer.md |
| wshobson/agents | Un catalogue d'agents distribués en plugins, avec le modèle assigné à chacun (Opus, Sonnet, Haiku) | docs/agents.md |
Clone d'abord anthropics/claude-agent-sdk-python. C'est le seul de la liste qui tourne en deux commandes, et son dossier examples/ suit exactement la progression du fichier 04 : l'agent minimal, puis les sous-agents, puis un outil maison.
Si tu ne veux pas installer de dépendances ce week-end, prends plutôt VoltAgent/awesome-claude-code-subagents : ce ne sont que des fichiers .md, tu les lis et tu en copies un dans ton .claude/agents/.