Créer un agent IA n8n sur votre propre VPS

Ce qu’est un agent IA n8n et ce qui le distingue d’une chaîne

Un agent IA n8n est un nœud AI Agent auquel sont rattachés des sous-nœuds : un modèle de conversation, un ou plusieurs outils et, facultativement, une mémoire. Vous indiquez un objectif en langage courant, puis le modèle décide quels outils appeler et dans quel ordre jusqu’à pouvoir répondre. Tout ce qui suit concerne la configuration autour de cette idée.

Une chaîne fonctionne à l’inverse. Dans une Basic LLM Chain, vous définissez les étapes et le modèle se contente de générer le texte. Dans un agent, le modèle définit les étapes. La même question peut donc nécessiter un appel au modèle aujourd’hui et neuf demain. Cette différence détermine tous les réglages de ce guide. Si cette boucle vous est nouvelle en tant que concept, et pas seulement en tant que fonctionnalité n8n, il est utile de la coder manuellement une fois avant de la construire avec des nœuds, car le nœud masque précisément la partie que vous devrez analyser dans la suite de ce guide.

Ce guide suppose que n8n fonctionne déjà derrière HTTPS sur une machine que vous contrôlez. Si ce n’est pas le cas, commencez par auto-héberger n8n avec Docker et un certificat valide, car la clé API que vous allez stocker nécessite la sauvegarde de la clé de chiffrement imposée par ce guide. Pour les modèles sans agent, notamment les résumeurs déclenchés par webhook et les classificateurs planifiés, consultez les modèles de workflows Claude et n8n.

Vérifiez votre version avant de vous fier aux noms des champs présentés ici, car n8n modifie souvent ses nœuds IA.

docker compose exec n8n n8n --version

Les noms utilisés dans ce guide correspondent à la version stable actuelle de n8n en juillet 2026. Depuis la version 1.82.0, chaque nœud AI Agent s’exécute comme un Tools Agent. La liste déroulante de l’ancien type d’agent n’existe donc plus.

Étape 1 : choisissez le déclencheur

Pour un agent conversationnel, ajoutez un nœud Chat Trigger. Laissez Make Chat Publicly Available désactivé pendant la création, afin que seul le panneau de discussion de l’éditeur puisse y accéder. Activez cette option lorsque l’agent est terminé et que vous avez choisi la méthode d’authentification.

Le nœud Chat Trigger fournit à l’agent un champ appelé chatInput. Ce nom est important à l’étape 3. Une erreur sur ce nom est la cause la plus fréquente du premier échec.

Pour un agent sans intervention, utilisez plutôt un nœud Schedule Trigger ou Webhook. Aucun des deux ne produit chatInput. Vous devrez donc rédiger vous-même le prompt.

Étape 2 : l’identifiant du modèle

Ajoutez un nœud AI Agent sur le canvas. n8n affiche immédiatement un connecteur Chat Model vide sous ce nœud. Ajoutez-y un sous-nœud Anthropic Chat Model.

Créez l’identifiant dans l’Anthropic Console, à l’adresse platform.claude.com, dans Settings, puis API Keys. La clé n’est affichée qu’une seule fois. L’utilisation de l’API est facturée au token et séparément de tout abonnement Claude.ai. Le compte doit donc avoir la facturation configurée avant la première exécution.

Choisissez le modèle pour chaque agent, et non pour l’entreprise entière. Un agent qui utilise un seul outil pour rechercher une information et la restituer fonctionne très bien avec Haiku, qui est affiché, en juillet 2026, au tarif de $1 par million de tokens d’entrée et $5 par million de tokens de sortie. Lorsque l’agent utilise plusieurs outils et doit planifier leur enchaînement, passez à Sonnet. Le problème à éviter est un modèle peu coûteux qui appelle quatre fois le mauvais outil, ce qui revient plus cher qu’un modèle coûteux qui appelle une fois le bon outil.

Définissez Maximum Number of Tokens dans les options du sous-nœud. Cette valeur limite la longueur de chaque réponse produite par le modèle. Si elle reste définie sur une valeur par défaut élevée, une exécution confuse peut produire une réponse très longue et vous la facturer.

Une précision de la documentation n8n prend souvent les utilisateurs au dépourvu : les expressions placées dans un sous-nœud sont toujours évaluées par rapport au premier élément d’entrée, jamais élément par élément. Placez les expressions propres à chaque élément dans les champs de prompt du nœud racine.

Étape 3 : le prompt reçu par l’agent

Ouvrez le nœud AI Agent. Le paramètre Prompt propose deux options.

• Take from previous node automatically attend un champ entrant nommé chatInput. C’est le bon choix derrière un Chat Trigger.
• Define below affiche un champ Prompt (User Message) dans lequel vous pouvez saisir du texte statique ou une expression. C’est le bon choix derrière un Schedule Trigger ou un nœud Webhook.

Avec un nœud Webhook en amont, le corps de la requête POST est placé sous $json.body. Le champ de prompt se présente donc ainsi.

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

Étape 4 : fournissez un outil à l’agent

Un nœud AI Agent sans sous-nœud d’outil refuse de s’exécuter. Commencez par un seul outil : un outil fonctionnel vous apprend davantage que quatre outils à moitié configurés.

Reliez un nœud HTTP Request au connecteur Tool de l’agent. Configurez-le exactement comme un nœud HTTP Request normal, puis testez d’abord cet endpoint depuis un shell.

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

Si cette commande curl renvoie une erreur ou une page de connexion HTML, l’agent échouera également. L’échec ressemblera à un problème de modèle, alors qu’il s’agit en réalité d’un problème d’URL ou d’authentification. Corrigez-le dans le shell, pas dans le nœud.

Le champ Description de l’outil ne sert pas à documenter celui-ci pour vos collègues. C’est la seule information que le modèle lit pour déterminer si cet outil est pertinent. Décrivez simplement ce que l’outil renvoie : « Renvoie l’état actuel, actif ou en panne, ainsi que la durée de l’interruption d’un service surveillé, au format JSON. »

Pour permettre au modèle de renseigner une partie de la requête, utilisez l’expression $fromAI(). Elle fonctionne uniquement avec les outils reliés à un nœud AI Agent. Elle ne fonctionne pas dans l’outil Code.

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

Les arguments sont key, puis éventuellement description, type et defaultValue. La clé doit comporter de 1 à 64 caractères et utiliser des lettres, des chiffres, des underscores et des traits d’union. Le type doit être string, number, boolean ou json. Sa valeur par défaut est string. Un appel plus complet se présente comme suit.

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

La clé est un indice, pas une référence vers des données existantes. $fromAI('service') ne lit pas un champ appelé service quelque part. Cette expression indique au modèle de « produire une valeur et de l’appeler service ». Le modèle cherche ensuite cette valeur dans la conversation, les données d’entrée et les résultats des autres outils. Dans un workflow de chat, il peut simplement la demander à l’utilisateur.

La recherche Web est généralement le deuxième outil utilisé. Comme il s’agit simplement d’un autre endpoint HTTP, vous pouvez relier ce même nœud à votre propre instance SearXNG plutôt qu’à une API de recherche payante, à condition de traiter chaque page renvoyée comme du texte non fiable désormais présent dans votre prompt.

Étape 5 : la mémoire et les raisons pour lesquelles l’agent oublie

Sans sous-nœud de mémoire, chaque message est traité sans contexte. Ajoutez un sous-nœud Simple Memory pour conserver les échanges récents.

Il comporte deux paramètres. Session Key détermine la conversation concernée. Deux utilisateurs ayant des clés différentes disposent donc d’un historique distinct. Context Window Length indique le nombre d’interactions précédentes réinjectées dans le prompt.

Context Window Length influe autant sur le coût que sur la qualité, car chaque échange mémorisé est renvoyé comme input tokens à chaque appel suivant. Avec une fenêtre de 20 et un agent très sollicité, vous payez vingt fois pour les mêmes premiers messages.

Simple Memory ne convient pas à un workflow de production actif lorsque n8n fonctionne en queue mode, car l’historique est stocké dans les données propres au workflow et non dans un store partagé. Sur une instance en queue mode, utilisez plutôt le sous-nœud Postgres Chat Memory et configurez-le avec une base de données accessible à la fois par le processus principal et par les workers.

Étape 6 : le message système

Ouvrez les Options de l’agent et ajoutez un System Message. C’est ici que vous indiquez la description de la tâche. C’est également le texte qui influence le plus le comportement du workflow.

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

« Always call the status tool before answering » joue un rôle important. Sans cette instruction, un modèle qui pense déjà connaître la réponse peut ignorer l’outil et répondre de mémoire. Sa réponse devient alors incorrecte dès que votre infrastructure change.

Pourquoi l’agent boucle-t-il et qu’est-ce qui l’arrête ?

Dans Options se trouve également Max Iterations, dont la valeur par défaut est 10. Une itération correspond à un appel au modèle, puis à la réinjection d’un résultat d’outil dans le contexte. Une exécution d’agent ne correspond donc pas à un seul appel d’API : elle peut en effectuer jusqu’à dix, et chacun transmet l’ensemble de la conversation qui s’allonge.

Réduisez cette valeur. La plupart des agents qui utilisent un seul outil terminent en deux itérations. Une limite de 3 ou 4 transforme une boucle sans fin en échec propre, visible dans la liste des exécutions.

Pendant le débogage, activez Return Intermediate Steps. La sortie finale inclut alors les appels d’outils effectués par l’agent. Vous pouvez ainsi distinguer « le modèle n’a jamais appelé l’outil » de « l’outil n’a renvoyé aucun résultat exploitable ». Désactivez cette option avant la mise en production, car ces étapes n’apportent rien à l’utilisateur final.

Observez une exécution depuis le shell.

docker compose logs -f n8n

Empêcher un agent sans surveillance de consommer des ressources en silence

Un agent derrière un Chat Trigger est supervisé par une personne, qui l’arrête lorsque la réponse semble incorrecte. Un agent derrière un Schedule Trigger n’est surveillé par personne. Ici, vous surveillez les coûts de modèles, et non les coûts de licence, car les nœuds agent, outil et mémoire fonctionnent tous avec l’édition self-hosted gratuite, et les fonctionnalités qui nécessitent une clé payante concernent principalement le travail en équipe et la gouvernance. La procédure complète est présentée dans Contrôler les coûts d’un agent IA sur un VPS toujours actif. Quatre paramètres font l’essentiel du travail ici.

• Définissez une valeur maximale pour Maximum Number of Tokens dans le sous-nœud du modèle, afin qu’une réponse ne puisse pas s’exécuter trop longtemps.
• Définissez Max Iterations sur la valeur la plus faible permettant de terminer la tâche.
• Limitez la taille des réponses des outils. Un outil qui renvoie un bloc JSON de 4,000 lignes l’injecte intégralement dans l’appel suivant au modèle, puis dans tous les appels suivants de la même exécution.
• Demandez-vous si l’agent a réellement besoin d’une planification. Une tâche exécutée toutes les cinq minutes se déclenche 288 fois par jour. Quel que soit le coût d’une exécution, c’est cette valeur que vous devez multiplier.

Désactivez le workflow pendant vos itérations. Un workflow actif avec un Schedule Trigger continue de s’exécuter avec la version enregistrée par n8n, qui n’est pas toujours celle affichée à l’écran.

FAQ

Pourquoi mon nœud AI Agent refuse-t-il de s’exécuter ?

Le nœud AI Agent nécessite un sous-nœud de modèle de chat et au moins un sous-nœud d’outil. Un nœud associé à un modèle, mais à aucun outil, échoue avant d’effectuer le moindre appel API. Ajoutez un outil, même trivial, puis relancez l’exécution.

L’agent répond, mais n’appelle jamais mon outil. Quel est le problème ?

Le problème vient presque toujours du champ Description de l’outil. Le modèle choisit les outils en lisant ces descriptions. Une description comme « HTTP Request » ne lui indique pas dans quel cas l’outil s’applique. Réécrivez-la en précisant quelles données sont renvoyées et dans quelle situation l’outil est utile. Ajoutez ensuite une ligne au System Message pour demander à l’agent d’appeler cet outil avant de répondre.

Pourquoi la même question coûte-t-elle un montant différent à chaque exécution ?

Parce que le modèle choisit le nombre d’étapes. À chaque itération, la conversation complète est renvoyée, y compris les sorties précédentes des outils. Une exécution qui nécessite quatre itérations coûte donc bien plus que quatre fois un appel unique. Max Iterations définit la limite maximale, et Return Intermediate Steps indique le nombre d’étapes effectivement utilisées par une exécution donnée.

Ma mémoire fonctionne dans l’éditeur, mais pas en production. Qu’est-ce qui a changé ?

Vérifiez si l’instance fonctionne en mode queue. Simple Memory stocke l’historique dans les données d’exécution du workflow. Cet historique n’est pas conservé lorsque l’exécution est transmise à un processus worker distinct. Un workflow de production actif le perd donc. Remplacez ce sous-nœud par Postgres Chat Memory, qui conserve l’historique dans la base de données partagée par tous les workers.