LangChain Deep Agents : planification, fichiers et subagents intégrés.

Les équipes qui prennent les agents au sérieux suivent généralement le même parcours. Elles commencent avec les chaînes LangChain, qui gèrent bien les pipelines simples. Puis la tâche s’aggrave : il devient nécessaire d’effectuer des appels à des outils, d’utiliser des boucles et de gérer des sorties de longueur imprévisible. Les chaînes ne suffisent plus, alors elles passent à LangGraph, et elles commencent alors à écrire des schémas d’état, des arêtes conditionnelles et du code de compilation de graphes avant même d’avoir abordé le problème réel.

LangGraph n’est pas le problème. C’est un outil puissant. Mais c’est un environnement de exécution, une primitive de bas niveau, et les gens ont souvent tendance à le traiter comme un framework d’application. deepagents est la réponse de LangChain à cette inadéquation.

Qu’est-ce que c’est

« Deep agents » peut signifier presque n’importe quoi, alors pour être précis : deepagents est un package Python indépendant, à installer avec pip install deepagents, qui s’appuie sur LangChain et LangGraph. Les documents de LangChain le désignent comme un outil de gestion d’agents. Il utilise le même cycle d’appel d’outils de base que d’autres frameworks, mais intègre des fonctionnalités supplémentaires, ce qui évite de devoir les recréer à chaque fois.

Le point d’entrée est create_deep_agent(). Importez-le d’abord :

from deepagents import create_deep_agent

Ensuite, passez un outil et une instruction :

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"
agent = create_deep_agent(
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)
agent.invoke(
    {"messages": [{"role": "user", "content": "What is the weather in Mumbai?"}]}
)

C’est tout. La bibliothèque s’occupe du graphe LangGraph, de la gestion de l’état, du streaming et de la fenêtre de contexte, sans que vous ayez à intervenir. La partie la plus intéressante, c’est ce qui est inclus par défaut.

Cinq fonctionnalités intégrées

Planification via write_todos

Chaque agent avancé dispose automatiquement d’outil write_todos. Face à une tâche complexe, il la divise en étapes, marque chacune comme en attente, en cours ou terminée, et ajuste le plan en fonction des changements. Il ne s’agit pas d’un tour de passe-passe lié aux prompts : la liste est stockée dans l’état de l’agent, ce qui lui permet de y revenir, de la mettre à jour et de s’y référer tout au long d’une session. Personne n’a besoin de dire au modèle de réfléchir étape par étape, car cette structure fait partie intégrante du système.

Un système de fichiers virtuel

Ce point pourrait être la plus grande surprise. Par défaut, l’agent dispose de ls, read_file, write_file, edit_file, glob et grep. Pourquoi un agent aurait-il besoin de fichiers ? Pour la gestion du contexte.

Les fenêtres de contexte sont limitées, et de longues recherches, des exécutions de code ou de gros résultats d’outils font que l’historique augmente rapidement. Les agents avancés stockent du contenu volumineux dans le système de fichiers virtuel plutôt que de le conserver entièrement dans la demande. Lorsqu’un résultat d’outil dépasse 20 000 tokens, la bibliothèque le sauvegarde dans le backend configuré et laisse dans le contexte un chemin de fichier ainsi qu’un aperçu de 10 lignes. Lorsque l’agent a besoin du contenu complet, il appelle read_file ou grep. Il ne s’agit ni de segmentation ni de troncature, mais d’un transfert délibéré avec récupération sur demande.

Le backend du système de fichiers est adaptable : état en mémoire par défaut, disque local, LangGraph Store pour la persistance entre threads, ou des environnements isolés comme Modal et Daytona.

Subagents

Un outil task intégré permet à l’agent principal de créer des subagents spécialisés pour des sous-tâches isolées. Cela est plus important qu’il n’y paraît. Dans une longue tâche de recherche, un agent gérant tout remplit son contexte d’étapes intermédiaires, de résultats de recherche et de sorties partielles. Avec les subagents, l’agent principal confie une sous-tâche à une instance neuve disposant d’un contexte propre. Cette instance travaille indépendamment, termine sa tâche et envoie un résumé, ce qui permet au contexte de l’agent principal de rester organisé.

Vous pouvez définir des subagents personnalisés avec leurs propres outils et prompts système. Commencez par l’importation :

from deepagents import create_deep_agent, Subagent

Ensuite, définissez un éditeur et associez-le :

code_reviewer = Subagent(
    name="code-reviewer",
    system_prompt="You are an expert code reviewer. Analyze code for bugs, style, and performance.",
    tools=[read_file_tool],
)
agent = create_deep_agent(
    tools=[internet_search],
    subagents=[code_reviewer],
    system_prompt="You are a research and engineering assistant.",
)

Un sous-agent polyvalent doté d’outils de système de fichiers est toujours disponible sans aucune configuration nécessaire.

Résumé automatique

Pour les tâches longues, c’est ici que la bibliothèque se révèle utile. Lorsque le contexte atteint 85 % de la capacité du modèle et qu’il ne reste plus rien à enregistrer dans des fichiers, le système déclenche le résumé. Un LLM rédige alors un résumé structuré couvrant l’intention de la session, les éléments créés et les prochaines étapes, et ce résumé remplace l’historique complet dans la mémoire de travail. Les messages originaux sont enregistrés dans le système de fichiers en tant que version canonique, afin que les détails puissent être récupérés ultérieurement. En pratique, les agents avancés peuvent continuer à travailler sur des tâches complexes sans atteindre les limites de contexte, ce qui nécessiterait normalement une configuration manuelle sur LangGraph brut.

Mémoire entre conversations

Normalement, l’état reste à l’intérieur d’une seule thread. Cependant, en configurant un CompositeBackend avec un LangGraph Store, l’agent peut conserver sa mémoire entre les sessions et les threads. Les fichiers stockés sous le chemin /memories/, ou tout autre chemin de votre choix, survivent aux redémarrages et peuvent être lus depuis n’importe quelle conversation. Utilisez-le pour permettre à un agent de se remémorer vos préférences, les habitudes de codage de votre répertoire, ou là où s’est arrêté un travail de recherche qui a duré plusieurs jours. Importez d’abord :

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

Puis le câblage :

store = InMemoryStore()
backend = CompositeBackend(
    routes={"/memories/": StoreBackend(store=store)},
    default=StateBackend(),
)
agent = create_deep_agent(
    tools=[...],
    backend=backend,
    memory=["path/to/AGENTS.md"],  # persistent context file
)

Comment les éléments sont liés

Les gens confondent souvent ces concepts, il est donc utile d’être précis.

• LangChain fournit les éléments de base : modèles, outils, prompts et chaînes. C’est la fondation.
• LangGraph est un environnement d’exécution permettant des traitements durables, basés sur des graphes et gérant la persistance, le streaming, les interruptions ainsi que des flux conditionnels complexes. C’est le moteur.
• Deep Agents est un outil qui intègre les deux. Il ne remplace pas LangGraph. Il utilise LangGraph pour tout et ajoute une API de niveau supérieur avec des paramètres par défaut prédéfinis, afin que vous n’ayez pas à développer vous-même le planificateur, la couche de système de fichiers, la compression du contexte ou l’infrastructure des sous-agents.

Pour bien le visualiser : LangGraph vous fournit un moteur et une transmission, tandis que Deep Agents vous donne une voiture entière.

Pour des agents simples, create_agent de LangChain suffit probablement. Lorsque les tâches sont complexes, longues à exécuter et nécessitent beaucoup de contexte, c’est là que deepagents compense le coût de son abstraction.

Une introduction pratique : un agent de recherche

Voici un agent de recherche qui explore le web et rédige un rapport structuré. La configuration vient en premier :

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

Ensuite, l’outil, les instructions et l’agent lui-même :

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search and return results."""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )
research_instructions = """You are an expert researcher.
Your job is to conduct thorough research and then write a polished report.
Use internet_search to gather information.
Write your findings to files as you go to avoid losing context.
Use write_todos to plan your research steps before starting.
"""
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",  # default model
    tools=[internet_search],
    system_prompt=research_instructions,
)
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Research the current state of agentic AI frameworks in 2025 and write a structured report."
    }]
})
print(result["messages"][-1].content)

L’exécution déclenche une séquence d’actions. L’agent appelle write_todos pour planifier la recherche. Il effectue des recherches et transfère automatiquement les résultats volumineux vers le système de fichiers virtuel. Si le travail est important, il lance un sous-agent pour chaque section. Il lit à nouveau les fichiers lorsque c’est nécessaire et rassemble tout dans un rapport final. Tout au long de ce processus, l’outil de gestion gère le contexte afin que le modèle ne dépasse jamais sa limite de temps de traitement. Vous n’avez pas écrit cette infrastructure, car elle est fournie avec l’outil de gestion.

L’agent en ligne de commande

Le paquet inclut également un agent terminal basé sur le même SDK :

pip install deepagents
deepagents  # launches the interactive CLI agent

C’est un agent de codage similaire à Claude Code ou Aider, mais fonctionnant avec le Deep Agents SDK. Il propose un mode interactif, un mode pipe non interactif pour l’écriture de scripts (l’option -n), des compétences personnalisées et une mémoire persistante. En lui enseignant les conventions de votre projet, il s’en souviendra d’une session à l’autre. Ainsi, le SDK qui permet de faire fonctionner un agent de recherche en production vous offre également immédiatement un outil de développement utilisable.

Quand l’utiliser

deepagents convient à vous lorsque :

• La tâche nécessite une planification et de nombreuses étapes.
• Les résultats des outils sont volumineux et doivent être gérés sur une longue session.
• Vous souhaitez déléguer des sous-agents sans devoir mettre en place les infrastructures nécessaires.
• Vous avez besoin d’une mémoire qui persiste entre les différents threads de conversation.
• Vous développez un agent de codage ou un système de recherche autonome.

Préférez create_agent ou LangGraph pur dans les cas suivants :

• L’agent est simple, avec une ou deux appels d’outils et des réponses courtes.
• Vous avez besoin d’un contrôle précis sur la topologie du graphe.
• Vous êtes déjà engagé dans un flux de travail personnalisé avec LangGraph et ne souhaitez pas de paramètres par défaut imposés.

Les documents eux-mêmes le précisent : les agents simples exigent des outils simples.

Pourquoi c’est important

Le contexte temporel en dit long. Les modèles d’agents de base, les appels d’outils, les boucles ReAct et les systèmes RAG simples sont désormais bien compris. Ce que le domaine cherche encore à résoudre, c’est la fiabilité dans les tâches à long terme, celles qui exigent de la planification, un contexte volumineux, de la persistance et de la délégation. Chaque équipe développant des agents en production a dû résoudre ces mêmes problèmes de zéro, et les stratégies de contexte, les modèles de sous-agents et les conceptions de mémoire continuent d’être réinventés sous des formes légèrement différentes.

deepagents représente la stratégie de LangChain, qui consiste à considérer que ces solutions sont suffisamment courantes pour être standardisées. Un outil doté de paramètres par défaut prédéfinis, d’une infrastructure intégrée et de backends interchangeables vise à déplacer la question de « comment construire les infrastructures nécessaires ? » vers « quelles actions l’agent doit-il effectuer réellement ? ». Son succès dépendra du fait que ces paramètres par défaut résistent en environnement de production. Néanmoins, en tant que direction à suivre, cela semble logique.

Démarrer

Installez le paquet ainsi que le client de recherche :

pip install deepagents tavily-python

Ensuite, définissez vos clés :

export ANTHROPIC_API_KEY="your-key"
export TAVILY_API_KEY="your-key"
export LANGSMITH_TRACING=true  # optional, for debugging
export LANGSMITH_API_KEY="your-key"

La présentation des Deep Agents dans les documents de LangChain couvre les backends, les subagents, les sandboxes, le mode humain intégré et la ligne de commande. Si vous développez quelque chose de sérieux avec des agents, accordez-vous une après-midi pour voir comment cela s’intègre dans votre stack, même si vous ne l’adoptez pas immédiatement.