Architecture DeepAgents : outils de planification, sous-agents et système de fichiers

Pourquoi votre agent IA s’effondre-t-il toujours sur les tâches complexes ?

Vous lui demandez d’étudier un sujet technique : après 20 étapes, la qualité baisse. Vous lui confiez la refactorisation d’une base de code : après une demi-journée, il a perdu les fonctionnalités d’origine. Vous lui demandez un long rapport : à mi-chemin, il recommence à répéter les mêmes phrases.

Je suis déjà tombé dans ce piège. À l’époque, avec un agent traditionnel pour une recherche approfondie sur les bonnes pratiques LangGraph, les premières sorties étaient structurées. Mais après une trentaine d’étapes, il « oubliait » — les sources déjà consultées, le cadre d’analyse initial — et le rapport final devenait incohérent, plein de contradictions.

La racine est la même : les agents traditionnels sont « Shallow ». Ils exécutent pas à pas, de façon réactive, sans planification, sans mémoire, sans découpage de sous-tâches. Comme demander à quelqu’un un rapport de 5 000 mots sans plan : à mi-parcours, il dévie forcément.

Pourtant Claude Code, Deep Research ou Manus accomplissent des tâches complexes — refactorisation de projets de milliers de lignes, rapports de recherche de dizaines de pages. Quelle méthode utilisent-ils ?

La réponse : l’architecture Deep Agent. LangChain l’a encapsulée dans le package DeepAgents. Aujourd’hui, décryptons ses quatre piliers : outils de planification, sous-agents, système de fichiers et prompts système.

Pourquoi les Deep Agents ?

Un fait d’abord : sur les tâches de plus de 10 étapes, le taux de réussite des agents traditionnels chute de plus de moitié.

Ce n’est pas une affirmation gratuite. Les données de Prompting Guide montrent qu’au-delà de 10 étapes, la qualité des Shallow Agents décline nettement. Pourquoi ? Parce qu’ils n’ont pas de « cerveau ».

Le design classique est réactif : instruction reçue → appel d’outil → résultat renvoyé. Chaque étape est isolée, sans planification long terme ni gestion d’état intermédiaire. Comme demander à quelqu’un de nettoyer toute la maison sans ordre ni liste des pièces déjà faites : il commence la cuisine, part au salon, oublie la cuisine à moitié faite.

Trois scénarios d’échec typiques :

Recherche approfondie. Vous demandez à l’agent d’étudier un sujet, par exemple « les bonnes pratiques LangGraph en production ». Il cherche, lit, extrait. Après 20 étapes, les sources déjà consultées sont expulsées de la fenêtre de contexte ; les nouvelles recherches écrasent le cadre d’analyse. Le rapport final manque de cohérence.

Refactorisation de code. Vous lui confiez un projet de milliers de lignes. Il modifie un module, puis un autre, sans voir les dépendances entre eux. À la fin, ce qui fonctionnait ne tourne plus.

Génération de contenu long. Vous demandez un article technique de 5 000 mots. Vers 2 000 mots, il répète ce qui a déjà été dit ou s’éloigne du sujet initial.

Le cœur du problème : perte de contrôle du contexte.

Claude Code gère des refactorisations de milliers de lignes, Deep Research produit des rapports structurés de dizaines de pages, Manus enchaîne des tâches multi-étapes. Ce n’est pas de la magie : une structure commune — l’architecture Deep Agent.

Le Deep Agent donne un « cerveau » à l’agent : planifier, découper, gérer la mémoire, suivre l’avancement. LangChain a encapsulé tout cela dans DeepAgents. Voyons le design concret.

Les quatre piliers de DeepAgents

La philosophie est claire : découper les tâches complexes en unités gérables, chacune avec un rôle défini.

Les quatre piliers coopèrent : Planning Tools pour planification et suivi, Sub-agents pour spécialisation et isolation du contexte, File System pour la mémoire, System Prompts pour les limites comportementales. Comme un orchestre — chef (Planning), sections (Sub-agents), partition (File System), règles de jeu (System Prompts).

Planning Tools : donner un « cerveau » à l’agent

Le cœur de Planning Tools, c’est todo_write.

Le principe est intéressant : en essence, c’est un no-op (opération vide). Il n’exécute aucune tâche réelle ; il crée et met à jour des listes de tâches. Ces listes passent par la fenêtre de contexte comme working memory, pour que l’agent « voie » plan et progression tout au long de l’exécution.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Exemple : une enquête technique. L’agent commence par todo_write :

- [ ] Rechercher la documentation officielle LangGraph
- [ ] Lire la conception State Machine de LangGraph
- [ ] Extraire des cas de bonnes pratiques
- [ ] Synthétiser les patterns de design clés
- [ ] Produire un rapport structuré

À chaque tâche terminée, il met à jour la liste, [ ] → [x]. Quelle que soit la longueur de l’exécution, l’agent voit l’avancement — fait, à faire, en cours.

Cela résout un problème central : la cohérence des objectifs sur le long terme.

À l’étape 20, un agent traditionnel a souvent oublié l’objectif de l’étape 1. La todo list du Deep Agent, c’est le post-it sur le frigo : « qu’est-ce que tu es censé faire ? »

"Le planning tool de Claude Code et Manus repose sur le même principe — la fenêtre de contexte comme working memory pour ne pas perdre le fil"

Sub-agents : spécialisation et isolation du contexte

Les Sub-agents forment le deuxième pilier.

Un orchestrateur principal planifie et distribue ; des sous-agents spécialisés exécutent. Chaque sous-agent a sa propre fenêtre de contexte et ne renvoie que le résultat final à l’orchestrateur.

Quatre avantages clés :

Context Preservation. La fenêtre de l’orchestrateur n’est pas polluée par les étapes intermédiaires des sous-agents. Un agent classique met tout dans le contexte : résultats de recherche, pages web, extractions. Un Sub-agent ne renvoie qu’un résultat propre — « voici les informations clés trouvées ». Le contexte de l’orchestrateur reste léger.

Specialized Expertise. Chaque sous-agent se concentre sur un domaine. research_subagent pour la recherche et l’extraction, writer_subagent pour l’organisation du contenu, coder_subagent pour l’analyse de code. La spécialisation améliore la qualité dans chaque domaine.

Reusability. Un même sous-agent peut servir plusieurs orchestrateurs. research_subagent convient à la recherche, à la rédaction, à l’analyse. Écrire une fois, réutiliser partout.

Fine-Grained Permissions. Des frontières de permissions différentes : lecture seule, écriture, accès réseau. Un contrôle fin réduit les risques.

"Architecture Orchestrator-Sub-agent recommandée, aussi appelée Task Decomposition Pattern — découper la tâche complexe en sous-tâches confiées à des unités dédiées"

Implémentation : DeepAgents expose une API simple :

from deepagents import create_deep_agent, create_subagent

# Définir les sous-agents
research_subagent = create_subagent(
    name="research",
    tools=[internet_search, read_url],
    description="Spécialisé dans la recherche et l'extraction d'information"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[write_file],
    description="Spécialisé dans l'organisation et la production de contenu"
)

# Créer l'agent principal
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file]
)

Lors des appels aux sous-agents, DeepAgents gère automatiquement le changement de contexte et le passage des résultats.

File System : dépasser la limite de la fenêtre de contexte

C’est la solution centrale au problème de mémoire.

La fenêtre de contexte a une taille limitée. Claude environ 200K tokens, GPT-4 environ 128K. Pour les tâches courtes, suffisant. Pour les longues — milliers de lignes de code, dizaines de documents — l’espace sature vite.

L’idée du File System Backend : des références fichiers plutôt qu’un chargement direct.

L’agent ne met pas tout dans le contexte ; il stocke les résultats intermédiaires sur le système de fichiers. Quand un fichier est nécessaire, read_file le charge à la demande. Comme en recherche : on ne mémorise pas toute la bibliographie, on classe les documents et on les ouvre au besoin.

DeepAgents propose trois Backend :

StateBackend. Stockage en mémoire, pour tests et tâches courtes. État et résultats intermédiaires en RAM, perdus à la fin de session. Rapide, non persistant.

FilesystemBackend. Système de fichiers local, pour production et persistance. Résultats intermédiaires sur disque, relisibles au prochain run. Persistant, dépend du stockage local.

StoreBackend. Stockage cloud, pour déploiement entreprise et audit. État en base cloud, versioning et journaux d’audit. Fiable, configuration plus lourde.

Le choix dépend du scénario. Tests rapides : StateBackend. Production : FilesystemBackend. Entreprise avec audit : StoreBackend.

Le tableau Context Management Strategy de FlowHunt résume les trois modes :

DeepAgents utilise par défaut le mode Hybrid — informations clés en contexte, gros volumes en fichiers.

System Prompts : la clé sous-estimée

System Prompts est le pilier le plus souvent négligé.

Beaucoup pensent qu’un System Prompt, ce sont quelques lignes : « vous êtes un assistant utile ». Pour un Deep Agent, ce sont des centaines à milliers de lignes de documentation d’ingénierie.

Le System Prompt de Claude Code compte des centaines de lignes : appels d’outils, flux fichiers, contraintes de style. Celui de Deep Research dépasse le millier : méthodologie de recherche, extraction, modèles de sortie.

Pourquoi autant de détail ?

Sur une longue tâche, l’agent rencontre des cas limites. Des instructions courtes ne couvrent pas tout. Un System Prompt détaillé sert à :

Définir les limites comportementales. Quand appeler todo_write, quand déléguer à un sub-agent, quand renvoyer directement. Des règles précises pour de bons choix.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

Normaliser les appels d’outils. Usage de chaque outil, format des paramètres, traitement des retours. read_file : chemin ou ID ? contenu brut ou résumé ?

Fixer le format de sortie. Rapport en Markdown structuré, refactor en diff, génération selon un modèle.

La Middleware Architecture de DeepAgents injecte les System Prompts automatiquement. Pas besoin d’écrire des milliers de lignes à la main — le framework génère selon votre config. Mais comprendre leur rôle compte : c’est la « constitution » du comportement de l’agent.

Les quatre piliers sont posés. Passons au code.

DeepAgents en pratique

Un exemple complet : un agent de recherche technique.

from deepagents import create_deep_agent, create_subagent
from langchain_community.tools import TavilyInternetSearch

# 1. Définir les outils
search_tool = TavilyInternetSearch(
    name="internet_search",
    description="Rechercher des informations sur Internet"
)

# 2. Définir les sous-agents
research_subagent = create_subagent(
    name="research",
    tools=[search_tool],
    system_prompt="Vous êtes expert en recherche d'information.\
                   Votre tâche : rechercher et extraire les informations clés.\
                   Ne renvoyez que des résultats structurés, sans étapes intermédiaires.",
    description="Sous-agent chargé de la recherche d'information"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[],  # writer n'a pas besoin d'outils externes
    system_prompt="Vous êtes expert en organisation de contenu.\
                   Votre tâche : structurer les résultats de recherche en rapport.\
                   Format Markdown avec sections claires.",
    description="Sous-agent chargé de la production de contenu"
)

# 3. Créer le Deep Agent
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file],
    backend="filesystem"  # stockage sur système de fichiers
)

# 4. Exécuter la tâche
result = agent.invoke(
    "Étudier les bonnes pratiques LangGraph,\
     produire un rapport de recherche structuré"
)

Déroulement :

Étape 1 : Plan. L’agent appelle todo_write pour créer la liste.

todo_write([
    "Rechercher la documentation officielle LangGraph",
    "Lire la conception d'architecture centrale",
    "Extraire des cas de bonnes pratiques",
    "Synthétiser les patterns de design",
    "Produire un rapport structuré"
])

Étape 2 : Delegate. L’agent appelle research_subagent pour la recherche.

call_subagent("research", "Rechercher des documents sur les bonnes pratiques LangGraph")

research_subagent appelle internet_search, obtient les résultats, extrait l’essentiel, renvoie un résultat structuré propre à l’orchestrateur. Celui-ci ne reçoit qu’un résumé du type « 5 bonnes pratiques clés trouvées », pas le contenu brut de toutes les pages.

Étape 3 : Update. L’agent met à jour la todo list.

todo_write([
    "[x] Rechercher la documentation officielle LangGraph",
    "[x] Lire la conception d'architecture centrale",
    "[ ] Extraire des cas de bonnes pratiques",
    ...
])

Étape 4 : Continuer. L’agent appelle writer_subagent, puis write_file pour le rapport final.

call_subagent("writer", "Organiser les résultats et produire le rapport")
write_file("langgraph_best_practices.md", report_content)

Journal d’exécution typique :

[Step 1] todo_write: création de 5 tâches
[Step 2] call_subagent(research): début de la recherche
[Step 3] internet_search: recherche "LangGraph best practices"
[Step 4] read_url: lecture de 3 documents officiels
[Step 5] subagent_complete: research renvoie un résultat structuré
[Step 6] todo_write: mise à jour, 2 tâches terminées
[Step 7] call_subagent(writer): début de l'organisation du contenu
[Step 8] subagent_complete: writer renvoie un rapport Markdown
[Step 9] write_file: écriture du rapport
[Step 10] todo_write: toutes les tâches terminées

Tout au long du flux, la fenêtre de l’orchestrateur reste propre — liste de tâches, résumés des sous-agents, sans bruit des étapes intermédiaires.

C’est la force du Deep Agent : flux structuré, gestion du contexte, division du travail.

Comparaison avec d’autres frameworks Agent

DeepAgents n’est pas le seul choix. LangGraph, AutoGen, CrewAI, SmolAgents ont chacun leur angle. Scénarios différents.

Tableau comparatif :

Quelques distinctions :

DeepAgents vs LangGraph. DeepAgents encapsule LangGraph pour le mode Deep Agent : Planning Tools, File System Backend, Sub-agent Management prêts à l’emploi. LangGraph est plus bas niveau : machine à états, nœuds et arêtes libres, mais Memory et Planning à construire.

En bref : Deep Agent rapide → DeepAgents ; personnalisation bas niveau → LangGraph.

DeepAgents vs AutoGen. AutoGen (Microsoft) : dialogue multi-agents, pipelines, débat et négociation entre agents. DeepAgents privilégie la décomposition et l’exécution ; AutoGen la collaboration et la communication.

En bref : équipe, débat, négociation → AutoGen ; décomposition et spécialisation → DeepAgents.

DeepAgents vs CrewAI. CrewAI met l’accent sur le « role-play » — chercheur, éditeur, développeur avec des personas. Proche des Sub-agents de DeepAgents, mais CrewAI insiste sur les rôles et l’interaction ; DeepAgents sur la découpe et l’isolation des tâches.

En bref : simulation d’équipe et role-play → CrewAI ; découpage technique → DeepAgents.

DeepAgents vs SmolAgents. SmolAgents (Hugging Face) est léger et code-first : l’agent écrit du Python plutôt que d’appeler des outils. Idéal pour prototyper, moins pour les longues tâches complexes.

En bref : agent simple rapide → SmolAgents ; longues tâches complexes → DeepAgents.

"Le choix dépend du scénario. DeepAgents pour le raisonnement complexe, LangGraph pour la production, AutoGen et CrewAI pour la collaboration multi-agents, SmolAgents pour valider une idée. Pas de framework universel, seulement le bon pour votre cas"

Déploiement en production et bonnes pratiques

Quelques points clés pour la production avec DeepAgents.

Stratégie de choix du Backend

Logique pour les trois Backend :

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

StateBackend : tests, tâches courtes. Rapide — tout en mémoire, pas de latence IO. Non persistant — état perdu au redémarrage. Tests unitaires, validation rapide.

FilesystemBackend : production, persistance. Fiable — données sur disque, relisibles après redémarrage. Coût IO. Déploiement production, longues tâches.

StoreBackend : entreprise, audit. Contrôlé — base cloud, versioning, journaux. Configuration lourde. Applications entreprise, conformité.

Exemple de configuration :

from deepagents import create_deep_agent, FilesystemBackend

agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    backend=FilesystemBackend(
        base_path="/var/agent-state",  # chemin de stockage
        max_file_size=10 * 1024 * 1024,  # taille max par fichier 10 Mo
        cleanup_after_days=30  # nettoyage des anciens fichiers après 30 jours
    )
)

Granularité des sous-agents

Ne sur-découpez pas.

Certains découpent une recherche en 10 sous-agents : search_google, search_bing, read_wikipedia, read_github, extract_summary, extract_quotes, format_markdown, check_citations… L’orchestrateur passe plus de temps à appeler qu’à exécuter.

Design raisonnable : 3 à 5 sous-agents cœur :

• research : toute la recherche et l’extraction
• analysis : traitement de données et raisonnement
• writer : organisation et production de contenu
• reviewer : contrôle qualité (optionnel)

Frontières claires. research ne fait pas l’organisation ; writer ne fait pas la recherche.

Optimisation des performances

Deux points :

Lecture fichiers à la demande. Ne read_file pas tous les résultats intermédiaires d’un coup. L’agent lit selon la tâche en cours. Les références fichiers de DeepAgents gardent le chemin en contexte et chargent le contenu au besoin.

Context Summarization avec mesure. Sur une longue tâche, le contexte s’encombre. DeepAgents peut résumer les étapes intermédiaires — compresser l’historique en état court. Économise de l’espace, mais la précision du résumé compte : ne pas perdre l’information clé.

agent = create_deep_agent(
    ...,
    context_management={
        "summarization_threshold": 50000,  # déclenchement à 50K tokens
        "preserve_last_n_steps": 5  # conserver le détail des 5 dernières étapes
    }
)

Gestion des erreurs et validation

Les Deep Agents s’exécutent longtemps ; les erreurs sont probables. Prévoyez :

LLM-as-a-Judge. Un second LLM vérifie la qualité. Par exemple reviewer_subagent contrôle le rapport de writer_subagent : failles logiques, omissions.

Points d’intervention humaine. Confirmation utilisateur aux décisions clés. Après la recherche, pause pour valider la direction avant de continuer.

agent = create_deep_agent(
    ...,
    verification={
        "auto_verify": True,  # validation automatique
        "human_checkpoint": "before_output"  # confirmation humaine avant sortie
    }
)

Conclusion

Récapitulatif des quatre piliers DeepAgents :

Planning Tools donne la planification ; todo_write utilise la fenêtre de contexte comme working memory pour la cohérence des objectifs.

Sub-agents assure spécialisation et isolation ; le contexte de l’orchestrateur reste propre, les étapes intermédiaires ne polluent pas le flux principal.

File System contourne la limite de la fenêtre : références fichiers, chargement à la demande.

System Prompts fixe les limites comportementales ; des centaines à milliers de lignes couvrent les cas limites.

Ensemble, ils font passer l’agent de l’exécution réactive au raisonnement structuré. Claude Code, Deep Research et Manus en sont la preuve.

Prochaines étapes :

• Construire votre premier agent longue tâche avec DeepAgents. Exemples complets sur le dépôt GitHub : langchain-ai/deepagents.
• Approfondir avec la documentation LangChain : docs.langchain.com/oss/python/deepagents.
• Suivre la série Développement IA : prochains articles sur LangGraph, optimisation des systèmes de mémoire Agent, etc.