Le node AI Agent de n8n : guide complet

Le node AI Agent est probablement le node le plus puissant — et le plus mal utilisé — de la palette IA de n8n. Beaucoup de workflows l'emploient là où une simple chaîne LLM suffirait, et inversement, beaucoup de chaînes rigides mériteraient un agent. La différence tient en une phrase : une chaîne exécute toujours les mêmes étapes, un agent décide lui-même quels outils appeler, dans quel ordre, et quand s'arrêter. Ce guide détaille le fonctionnement du node (le Tools Agent), ses quatre branchements, le rôle central du system message, l'activation du parseur de sortie, et surtout les limites qu'il faut accepter avant de le mettre en production. Si vous découvrez tout juste la palette IA de n8n, commencez plutôt par notre introduction aux nodes IA.

AI Agent vs Basic LLM Chain : deux logiques différentes

Le node Basic LLM Chain est un tuyau : un prompt entre, le modèle répond, la réponse sort. Le chemin est fixe, connu à l'avance, identique à chaque exécution. C'est exactement ce qu'il faut pour classer un email, extraire des champs d'une facture ou résumer un document — des tâches où vous savez déjà quelles étapes s'enchaînent.

Le node AI Agent (dont le mode par défaut est le Tools Agent, qui s'appuie sur le mécanisme d'appel d'outils natif des modèles récents) fonctionne autrement : vous lui donnez un objectif, une liste d'outils, et il construit lui-même son plan. Face à la question « quel est le statut de la commande 4521 et quand sera-t-elle livrée ? », l'agent peut décider d'appeler d'abord un outil de recherche en base, observer le résultat, puis appeler un outil d'API transporteur, avant de synthétiser une réponse — sans que vous ayez câblé cette séquence nulle part.

Cette approche a un fondement académique précis : l'étude de Yao et al. présentée à ICLR 2023, « ReAct: Synergizing Reasoning and Acting in Language Models » (Google Scholar), a montré qu'un LLM qui alterne des traces de raisonnement et des actions (appels d'outils suivis d'observations) résout mieux les tâches nécessitant des informations externes qu'un modèle qui raisonne seul, tout en réduisant les hallucinations puisque le modèle s'appuie sur ce qu'il observe plutôt que sur sa mémoire interne. C'est exactement la boucle qu'implémente le Tools Agent de n8n.

Les quatre branchements du node

Contrairement aux nodes classiques qui n'ont qu'une entrée de données, le node AI Agent expose des connecteurs spécialisés sous le node :

• Chat Model (obligatoire) — le cerveau de l'agent. On y branche un modèle conversationnel : OpenAI, Anthropic, Google, ou un modèle local. Le choix compte plus ici que pour une chaîne simple, car l'agent repose sur la capacité du modèle à décider correctement d'appeler des outils. Notre guide pour connecter Claude ou GPT à n8n détaille la configuration des credentials.
• Memory (optionnel) — sans mémoire, chaque message repart de zéro : l'agent oublie tout entre deux exécutions, ce qui rend impossible un dialogue suivi. Le branchement d'un node de mémoire (Window Buffer, Postgres Chat Memory…) est traité en détail dans notre article sur la mémoire de conversation d'un agent IA.
• Tools (optionnel mais c'est là tout l'intérêt) — chaque outil branché devient une capacité que l'agent peut invoquer : un outil de calcul, un appel HTTP, une requête vers une base vectorielle, ou même un sub-workflow n8n complet exposé comme outil. La description de chaque outil est déterminante, car c'est elle que le modèle lit pour décider de l'appeler — nous y consacrons un guide entier sur les outils personnalisés de l'AI Agent.
• Output Parser (optionnel) — pour contraindre la réponse finale à un format structuré, voir plus bas.

Le system message : la pièce la plus importante

Le champ System Message (dans les options du node) définit le rôle, le périmètre et les règles de l'agent. C'est le levier de contrôle numéro un, bien avant le choix du modèle. Un system message efficace précise :

• Le rôle et le périmètre : « Tu es l'assistant support de X. Tu réponds uniquement aux questions sur les commandes et les livraisons. »
• Quand utiliser chaque outil : « Utilise l'outil lookup_order dès qu'un numéro de commande est mentionné. N'invente jamais un statut de commande. »
• Ce que l'agent ne doit pas faire : ne pas promettre de remboursement, ne pas révéler d'informations d'autres clients, escalader vers un humain quand la demande sort du périmètre.
• Le ton et la langue de la réponse finale.

Un agent sans system message explicite se comporte comme un généraliste bavard : il répond à tout, appelle les outils de façon erratique et sort facilement de son rôle. C'est aussi la première ligne de défense contre les manipulations par le contenu traité — sujet que nous approfondissons dans notre article sur la prompt injection et les guardrails.

Choisir le modèle : la capacité d'appel d'outils avant tout

Tous les modèles ne se valent pas en usage agentique. Trois critères pratiques :

• La fiabilité du tool calling : l'agent passe son temps à décider s'il appelle un outil et avec quels arguments ; un modèle qui produit des arguments mal formés ou ignore les outils disponibles rend l'agent inutilisable, quelle que soit la qualité de sa prose.
• Le rapport coût/latence : chaque itération de la boucle (décision → outil → observation) est un appel au modèle. Un modèle rapide et économique de génération récente suffit souvent pour des agents à 2-3 outils bien décrits ; réservez les modèles haut de gamme aux agents dont les décisions sont réellement complexes.
• La fenêtre de contexte : l'historique de conversation, les descriptions d'outils et les observations s'accumulent dans le contexte à chaque tour.

Commencez avec un modèle milieu de gamme, mesurez, puis montez en gamme seulement si les décisions de l'agent sont mauvaises — et non l'inverse.

Structurer la sortie : Require Specific Output Format

Par défaut, l'agent répond en texte libre — très bien pour un chatbot, inutilisable quand la suite du workflow attend des champs précis. Le node propose pour cela l'option « Require Specific Output Format » (correspondant au paramètre hasOutputParser du node) : une fois activée, une entrée Output Parser apparaît sous le node, sur laquelle on branche typiquement un Structured Output Parser configuré avec un exemple de JSON ou un schéma.

L'agent reçoit alors les instructions de format en plus de son system message, et sa réponse finale est validée et parsée avant d'être transmise aux nodes suivants — qui peuvent lire {{ $json.output.category }} directement au lieu de découper du texte à la regex. Le fonctionnement détaillé (schéma, auto-fixing, cas d'échec) est couvert dans notre guide du Structured Output Parser.

La boucle de raisonnement : outil → observation → décision

Concrètement, une exécution d'agent se déroule ainsi :

1. Le modèle reçoit le system message, l'historique éventuel, la liste des outils avec leurs descriptions, et le message utilisateur.
2. Il décide : répondre directement, ou appeler un outil avec des arguments précis.
3. n8n exécute l'outil et renvoie le résultat au modèle comme observation.
4. Le modèle intègre l'observation et décide à nouveau : autre outil, même outil avec d'autres arguments, ou réponse finale.
5. La boucle se répète jusqu'à la réponse finale ou jusqu'à la limite d'itérations (l'option Max Iterations du node, garde-fou indispensable contre les boucles infinies).

Chaque itération est visible dans les logs d'exécution de n8n : on y lit quels outils l'agent a appelés, avec quels arguments et quelles observations — le premier réflexe de débogage quand un agent se comporte bizarrement.

Limites et bonnes pratiques

L'autonomie a un prix, et il faut le connaître avant la mise en production :

• Coût : un agent qui enchaîne 4 appels d'outils fait au minimum 5 appels au modèle, avec un contexte qui grossit à chaque tour. Sur un volume réel, la facture surprend — instrumentez dès le départ avec notre méthode pour suivre le coût des appels IA.
• Latence : chaque itération ajoute des secondes. Un agent conversationnel qui met 20 secondes à répondre est un problème produit, pas seulement technique.
• Dérive : sur des demandes ambiguës, l'agent peut appeler des outils hors sujet, boucler, ou halluciner une réponse quand aucun outil ne convient. Les parades : des descriptions d'outils précises, un system message strict, une limite d'itérations basse, et des tests réguliers sur un jeu de cas représentatifs.
• Prévisibilité : un agent n'est pas déterministe. Pour tout ce qui touche à des actions irréversibles (envoi d'email, écriture en base, remboursement), préférez une validation humaine ou une chaîne fixe en aval de l'agent.

La règle simple : chaîne fixe par défaut, agent quand le chemin dépend réellement de la demande. Un tri de tickets suit toujours les mêmes étapes — chaîne. Un assistant qui répond à des questions variées en s'appuyant sur une base documentaire, un CRM et un calendrier — agent.

Par où commencer

Le plus court chemin pour voir un Tools Agent fonctionner en conditions réelles reste de partir d'un exemple complet : le Pack Assistant RAG (119 €) contient un agent branché sur une base vectorielle Supabase, avec mémoire de conversation, system message rédigé et outils configurés — un point de départ concret à adapter, plutôt qu'une page blanche. Et pour aller plus loin sur chaque branchement, les guides sur les outils personnalisés, la mémoire et le parseur de sortie couvrent chacun leur connecteur en profondeur.