Guide

Agents dans LangChain 1, create_agent et middleware

Agents dans LangChain 1 : create_agent remplace AgentExecutor, middleware, lien avec LangGraph, outils, coûts et migration de l'ancien code.

L'équipe CodeWorlds14 min de lecture ·

Pratique Python dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article10

Dans la première version majeure de LangChain, la façon de construire des agents a entièrement changé. L'ancienne approche fondée sur un exécuteur d'agent a été retirée, et une seule fonction de création d'agent a pris sa place, en s'exécutant sur le runtime LangGraph. La version actuelle est la 1.3.14, sous licence MIT.

Cela a une conséquence directe pour l'apprentissage : pratiquement tous les tutoriels antérieurs à cette version montrent du code désormais retiré. Si tu copies un exemple d'un article et que tu reçois un avertissement ou une erreur d'import, c'est exactement cette situation.

Ce qui a été retiré exactement

Trois choses à reconnaître dans l'ancien code.

L'exécuteur d'agent, la classe qui liait un modèle à des outils et exécutait la boucle. La fonction qui initialisait un agent à partir d'un nom de type. Et la fonction qui créait un agent selon le schéma de raisonnement et d'action, dans la forme qu'elle avait dans le paquet principal.

Les trois sont remplacées par une seule fonction de création d'agent, disponible dans le module agents du paquet principal. Elle prend un modèle, une liste d'outils et un prompt, et renvoie quelque chose d'appelable.

Il faut savoir tout de suite que le retrait signifie ici une suppression et non un simple marqueur d'obsolescence. Le paquet principal a été réduit à une poignée de modules, et l'ancien exécuteur ainsi que la fonction d'initialisation ont été déplacés dans un paquet séparé hérité nommé langchain-classic, qui s'installe à part. Un ancien import laissé tel quel se termine donc par une erreur d'import plutôt qu'un avertissement. Tu ne vois des avertissements qu'après avoir installé ce paquet et réécrit les chemins d'import vers son espace de noms.

La raison du retrait est technique et vaut la peine d'être comprise, car elle explique le reste des changements. L'ancien exécuteur était une boucle : appeler le modèle, vérifier s'il veut un outil, appeler l'outil, recommencer. Cette boucle n'avait aucune place pour les branchements, pour s'arrêter et attendre une décision humaine, ou pour reprendre après un échec. Tout ce qui dépassait une simple boucle obligeait à contourner la bibliothèque.

La nouvelle approche place un agent sur un graphe qui intègre ces choses. Un agent est un graphe avec une disposition de nœuds définie, et tu obtiens un constructeur pratique au lieu de l'assembler à la main.

L'agencement de base

Python
from langchain.agents import create_agent
from langchain_core.tools import tool

@tool
def check_status(number: str) -> str:
    """Returns an order's status by its number."""
    return db.status(number)

agent = create_agent(
    model="anthropic:claude-sonnet-5",
    tools=[check_status],
    prompt="You answer questions about orders. Use the tool, do not guess.",
)

result = agent.invoke({"messages": [{"role": "user", "content": "where is 4471"}]})

Trois choses méritent d'être remarquées.

Le modèle est fourni sous forme de chaîne préfixée par le fournisseur, ce qui réduit le changement de fournisseur à la modification d'un littéral. On peut passer à la place un objet modèle préparé quand on a besoin de réglages particuliers.

Un outil est une fonction ordinaire avec une chaîne de documentation. Cette chaîne parvient au modèle et constitue la seule information qu'il utilise pour décider d'appeler, donc une phrase qui dit clairement quand appeler l'outil vaut mieux qu'une phrase qui dit seulement ce qu'il fait.

Le résultat est une structure contenant l'historique des messages plutôt qu'une chaîne. Ce détail piège la plupart des gens qui arrivent de l'ancienne approche.

Les middleware, le cœur de la nouvelle approche

Cet élément sépare le plus la solution actuelle de la précédente, et il mérite d'être appris, car il remplace la plupart des contournements que les gens utilisaient auparavant.

Un middleware est une couche branchée sur un moment particulier du travail d'un agent. Tu peux changer ce qui part vers le modèle, inspecter une décision d'appeler un outil avant son exécution, modifier le résultat d'un outil avant qu'il ne retourne au modèle, ou interrompre le flux.

Quatre usages reviennent le plus souvent.

L'approbation humaine : l'agent a l'intention d'appeler un outil qui effectue une opération irréversible, la couche interrompt le flux et attend une confirmation. Auparavant, cela exigeait de casser la boucle et d'écrire la tienne.

Le rognage de l'historique : sur une longue conversation, le contexte cesse de tenir, donc la couche supprime les anciens messages ou les résume avant l'envoi au modèle.

La restriction des permissions : la couche vérifie si le contexte actuel autorise l'appel d'un outil donné et rejette la tentative avant que quoi que ce soit ne s'exécute. C'est le bon endroit pour une telle vérification, car elle ne dépend pas de ce que le modèle a lu dans la conversation.

L'enregistrement et la mesure : la couche voit chaque appel, donc c'est le foyer naturel pour attacher des identifiants, compter le coût ou émettre des événements vers un outil de tracing, Arize Phoenix par exemple.

L'avantage de cet agencement est que les couches sont indépendantes et composables. Ajouter l'approbation ne demande aucun changement au code de rognage de l'historique, et en désactiver une dans un environnement de test revient à retirer une entrée d'une liste.

Le rapport avec LangGraph

Il vaut la peine de clarifier cela, car la question LangChain contre LangGraph revient souvent et a cessé d'avoir un sens sous sa forme ancienne.

Un agent créé par cette fonction est un graphe. Le constructeur assemble un graphe de forme fixe : un nœud qui appelle le modèle, un nœud qui exécute les outils et une arête conditionnelle qui décide de retourner au modèle ou de terminer.

Cela signifie que tout ce que fournit la couche inférieure est disponible : des checkpoints qui enregistrent l'état après chaque étape, la reprise d'une exécution interrompue, le voyage dans le temps et la consultation de l'historique des états. J'ai traité cela longuement dans le texte sur la mémoire dans LangGraph.

Un conseil pratique pour choisir le niveau. Commence par le constructeur, car il couvre le cas typique : un modèle plus des outils plus un prompt. Descends à l'assemblage d'un graphe à la main quand tu as besoin d'une forme que le constructeur n'offre pas, par exemple deux modèles dans des rôles différents ou un branchement selon la catégorie de la question.

Passer d'un niveau à l'autre n'est pas une réécriture, puisque tu travailles dans le même runtime. C'est en fait le principal bénéfice de ce changement : auparavant, dépasser l'exécuteur signifiait abandonner la bibliothèque.

Migrer l'ancien code

Un ordre qui fonctionne quand tu as un agent en cours d'exécution dans l'ancienne approche.

Commence par un inventaire. Liste ce que fait ton code actuel au-delà d'une simple boucle : rognage de l'historique, gestion des erreurs d'outils, approbation, journalisation. C'est la liste des choses qui deviennent des couches.

Remplace ensuite la création de l'agent elle-même. Le modèle, les outils et le prompt se transfèrent presque un pour un, donc une première version tourne vite.

La troisième étape consiste à déplacer les contournements vers des couches. C'est généralement là que le plus de code disparaît, car ce qui était écrit à la main autour de l'ancienne boucle a maintenant une vraie place.

La quatrième est la gestion du résultat. L'ancien exécuteur renvoyait un dictionnaire avec une clé contenant la réponse en texte ; le nouveau renvoie une structure avec l'historique des messages, donc les endroits qui lisent le résultat doivent être corrigés.

Ne migre pas tout d'un coup si tu as plusieurs agents. Un seul pour commencer, une semaine en production, puis les autres. L'ancienne approche peut être maintenue en vie via le paquet hérité, donc la pression du temps est plus faible que ne le suggèrent les messages, même si cela te coûte l'installation de ce paquet et la correction des imports partout où apparaît l'ancien exécuteur.

Les outils et ce qui décide de la précision

Puisqu'un agent se réduit à un modèle qui appelle des outils, la qualité des outils décide du résultat plus que tout le reste.

La description compte le plus et se rédige le plus mal. Le modèle ne voit que le nom de la fonction, le texte de documentation et le schéma des arguments, donc c'est toute l'information derrière sa décision. « Checks an order's status » dit ce que fait l'outil. « Call this when the user asks about an order's state and supplied its number » dit quand l'appeler, et cette différence se voit dans les statistiques de précision.

Décris les arguments avec les types les plus étroits possibles. Un champ qui accepte n'importe quelle chaîne sera rempli avec n'importe quoi, alors qu'un champ qui accepte l'une de trois valeurs limite les erreurs à la source. La validation de schéma, avec Zod côté interface ou son équivalent Python, joue ici un double rôle : elle décrit la forme au modèle et rejette un appel invalide.

La gestion des erreurs mérite une réflexion à part. Un outil qui lève une exception renvoie un message à l'agent, et l'agent décide de la suite à partir de lui. Un message qui dit ce qui s'est mal passé et ce qu'on pourrait faire à la place transforme un échec en étape intermédiaire. Un message technique mène généralement à répéter la même tentative.

Le dernier point est le nombre d'outils. Un agent avec cinq outils choisit avec précision ; un agent avec trente commence à se perdre, car les descriptions se font concurrence dans le contexte. Au-delà d'un certain nombre, il vaut la peine d'envisager de le scinder en plusieurs agents spécialisés, ou une couche qui sélectionne un sous-ensemble d'outils à partir de la question.

Coûts et limites d'exécution

Un agent diffère d'un simple appel de modèle en ce qu'il décide lui-même du nombre d'appels, et cela se traduit directement dans la facture.

Chaque étape transporte toute la conversation jusque-là ainsi que les résultats des outils. Une exécution de six étapes n'est pas six appels de coût similaire mais six appels de coût croissant, car le contexte s'accumule.

Deux choses méritent donc d'être réglées dès le départ. Une limite d'étapes qui arrête l'exécution protège contre une boucle où l'agent appelle un outil qui renvoie une erreur et réessaie indéfiniment. Et le rognage de l'historique, car sans lui une longue exécution cesse de tenir dans la fenêtre de contexte.

Adapter le modèle au rôle est aussi rentable. Un agent qui décide quels outils appeler n'a pas besoin d'être le modèle le plus puissant quand le jeu d'outils est clairement décrit. Garde le modèle plus puissant pour les étapes qui exigent du raisonnement, et avec deux modèles dans des rôles différents tu es déjà descendu jusqu'à un graphe construit à la main.

Le dernier point est l'observation. Sans exécutions enregistrées, tu ne sais pas combien d'étapes prend une requête typique ni quel outil est appelé le plus souvent sans nécessité. Ces chiffres surprennent généralement à la première inspection et mènent aux économies les plus simples.

Cet enregistrement vient par l'une de deux voies, qu'il faut distinguer car elles diffèrent par le coût de mise en place. La première est une couche dans le code de l'agent, décrite plus haut. La seconde est un proxy entre l'application et le fournisseur du modèle, qui compte les tokens et les temps sans toucher au code, même si l'exemple le plus connu de cette approche, Helicone, appartient à Mintlify depuis mars 2026 et fonctionne en mode maintenance, donc pour un nouveau déploiement la couche dans le code est le choix le plus sûr.

LangChain face aux alternatives

OptionNiveauDépendanceÀ choisir quand
create_agentUn constructeur au-dessus d'un grapheLangChain plus LangGraphUn agent typique avec des outils
Un graphe construit à la mainContrôle total du fluxLangGraphUne forme de flux inhabituelle
OpenAI Agents SDKUn constructeur d'un fournisseurLié à ce fournisseurTu travailles dans un seul écosystème
Ta propre boucleAucune abstractionLe seul client du modèleUn cas simple, tu veux tout comprendre

La dernière ligne mérite une considération honnête et se fait sauter. Une boucle qui appelle le modèle, vérifie s'il veut des outils et les appelle représente une quarantaine de lignes de code. Avec un agent et trois outils, l'écrire toi-même donne une compréhension totale et zéro dépendance.

La valeur de la bibliothèque apparaît avec ce que ta propre boucle devrait ajouter : un état durable, la reprise, l'approbation humaine, le streaming d'événements intermédiaires, la gestion des appels d'outils en parallèle. Si tu n'as besoin d'aucun d'eux, la bibliothèque est un coût sans retour.

La troisième ligne est un choix sur un autre axe : elle te lie à un seul fournisseur de modèle en échange de moins de pièces à assembler. Avec une certitude sur le fournisseur, c'est parfois sensé ; avec un besoin de comparer des modèles, moins.

Erreurs fréquentes

La première est d'apprendre à partir de tutoriels antérieurs à la première version majeure. Le code qu'ils montrent est retiré, et les différences sont assez grandes pour qu'aucune petite correction ne le répare.

La deuxième est une description d'outil qui dit ce qu'il fait plutôt que quand l'appeler. Le modèle ne voit que le nom, la description et le schéma des arguments, donc cette phrase décide de la précision plus que le prompt système.

La troisième est l'absence de limite sur le nombre d'étapes. Un agent qui appelle un outil renvoyant une erreur peut réessayer indéfiniment pendant que la facture grossit en arrière-plan.

La quatrième est une approbation des opérations irréversibles qui repose sur un prompt plutôt que sur une couche. Un prompt est une suggestion que le modèle peut ignorer ; une couche est du code qu'il ne peut pas contourner.

La cinquième est de lire le résultat comme dans l'ancienne approche. La nouvelle renvoie une structure avec l'historique des messages plutôt qu'un texte sous une clé fixe.

La sixième est de recourir à la bibliothèque pour un cas qu'une quarantaine de lignes de ta propre boucle géreraient. L'abstraction est rentable avec la durabilité et la reprise, pas avec un agent et trois outils.

FAQ

AgentExecutor est-il retiré ?

Oui, avec la fonction d'initialisation d'agent et l'ancienne fonction qui créait un agent selon le schéma de raisonnement et d'action. Une seule fonction de création d'agent dans le module agents les remplace, construite sur le runtime LangGraph. Les classes retirées ont disparu du paquet principal et subsistent dans un paquet hérité séparé.

Pourquoi l'approche a-t-elle été changée ?

Parce que l'ancien exécuteur était une simple boucle sans place pour les branchements, l'arrêt en attente d'une décision humaine ou la reprise après un échec. Tout ce qui dépassait cette boucle obligeait à contourner la bibliothèque, et la nouvelle approche intègre ces choses.

Qu'est-ce qu'un middleware dans ce contexte ?

Une couche branchée sur un moment particulier du travail d'un agent : avant l'appel du modèle, avant l'exécution d'un outil ou après celle-ci. Elle sert à approuver des opérations, rogner l'historique, restreindre les permissions et mesurer, c'est-à-dire des choses qu'on écrivait auparavant à la main autour de la boucle.

Dois-je apprendre LangGraph ?

Pour un agent typique non, car le constructeur assemble le graphe pour toi. Il vaut cependant la peine de savoir qu'un agent est un graphe, car cela rend disponibles les checkpoints, la reprise et la consultation de l'historique des états sans changer de bibliothèque.

À quel point la migration est-elle urgente ?

Sans précipitation, même si ne rien faire du tout n'est pas une option. L'exécuteur d'agent a disparu du paquet principal, donc garder l'ancien code un moment signifie installer le paquet hérité et corriger ses chemins d'import ; ce n'est qu'alors qu'il continue de fonctionner, avec des avertissements d'obsolescence. Une voie raisonnable est de migrer un agent, une semaine d'observation en production, et seulement ensuite les autres. La plus grande partie du travail consiste à déplacer tes propres contournements vers des couches.

La documentation sur les agents se trouve sur le site du projet, et le code et les versions dans le dépôt GitHub.

À lire aussi