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 seul nœud AI Agent auquel sont rattachés des sous-nœuds : un modèle de chat, un ou plusieurs outils et, éventuellement, 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 unique.

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. Avec 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 paramètres présentés dans ce guide. Si cette boucle est nouvelle pour vous 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 pendant le reste 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é d’API que vous allez stocker nécessite la sauvegarde de la clé de chiffrement exigé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 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 régulièrement les nœuds IA.

docker compose exec n8n n8n --version

La version 1.82.0 a rendu obsolète le paramètre de type d’agent au profit de Tools Agent. Les nœuds hérités v1 proposent encore ce paramètre ; la documentation n8n prévoit la suppression de cette version de nœud dans n8n 3.0.

É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 au 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 depuis la Claude Console, à l’adresse platform.claude.com, dans Settings, puis API keys. La clé ne s’affiche qu’une seule fois. La Console vous demande également de choisir une date d’expiration lors de la création de la clé. Un agent sans supervision cesse de fonctionner le jour où sa clé expire. Notez donc cette date à un endroit visible. Pour un agent sans supervision, utilisez une clé de compte de service limitée à un workspace. Les requêtes n’ont ainsi pas besoin d’un en-tête workspace distinct.

L’utilisation de l’API est facturée au token. Le mode de paiement dépend de votre forfait Claude, au 31 octobre 2026. Les forfaits Max, Ultra et Team incluent des crédits API mensuels : $100 pour Max, $200 pour Ultra et jusqu’à $500 mutualisés pour Team. Pour les utiliser, associez une organisation Console au forfait depuis Settings > Billing avec Max ou Ultra, ou depuis Organization settings > Billing avec Team. Vous n’avez pas besoin d’ajouter de moyen de paiement dans la Console. Les nouveaux abonnés peuvent les utiliser après 7 jours avec le forfait. Les crédits inutilisés expirent à la fin de chaque cycle de facturation, ou chaque mois pour les forfaits annuels. Lorsque les crédits inclus sont épuisés, les requêtes continuent d’utiliser les crédits achetés. L’auto-reload peut en acheter d’autres. Les organisations facturées sur facture paient l’utilisation excédentaire. Les requêtes s’arrêtent lorsqu’une organisation prépayée n’a plus de crédits. L’utilisation de l’API n’est jamais facturée sur votre forfait Claude. Les forfaits Free, Pro et Enterprise n’incluent aucun crédit API mensuel. Avec ces forfaits, l’API est donc facturée séparément de l’abonnement.

Choisissez le modèle pour chaque agent, et non pour toute l’entreprise. Un agent qui utilise un seul outil pour rechercher une information et la restituer fonctionne très bien avec Haiku. La version actuelle, Haiku 5.5, est facturée $0.10 par million de tokens d’entrée et $0.50 par million de tokens de sortie au 12 octobre 2026. Ces tarifs passent à $0.50 et $2.50 pour toute requête dont le prompt dépasse 100,000 tokens. Une longue fenêtre de mémoire et des résultats d’outils volumineux peuvent atteindre ce seuil. 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. Cela peut coûter plus cher qu’un modèle plus onéreux qui appelle une seule 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 fixée à une valeur par défaut élevée, une exécution perturbée peut produire une réponse très longue et vous être facturée en conséquence.

Une particularité signalée dans la documentation n8n prend souvent 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 dépendantes de 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 Source for Prompt (User Message) propose deux options.

• Connected Chat Trigger Node attend un champ entrant nommé chatInput. Choisissez cette option avec un Chat Trigger.
• Define below affiche un champ Prompt (User Message) dans lequel vous pouvez saisir du texte statique ou une expression. Choisissez cette option avec un Schedule Trigger ou un nœud Webhook.

Avec un nœud Webhook en amont, le corps d’une 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 : donnez un outil à l’agent

La documentation de n8n indique que vous devez connecter au moins un sous-nœud d’outil à un nœud AI Agent, même si le code actuel du nœud (version 3.1) refuse seulement de s’exécuter en l’absence d’un modèle de chat. Commencez malgré tout par un seul outil, car un outil fonctionnel vous apprend davantage que quatre outils à moitié configurés, et un agent sans outil n’est qu’une chaîne plus coûteuse.

Connectez un nœud HTTP Request au connecteur Tool de l’agent. Configurez-le exactement comme un nœud HTTP Request classique, 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’erreur semblera venir du modèle alors qu’elle provient en réalité de l’URL ou de l’authentification. Corrigez le problème dans le shell, pas dans le nœud.

Le champ Description de l’outil ne sert pas à documenter celui-ci pour vos collègues. Le modèle le lit avec le nom de l’outil et le schéma de ses paramètres pour déterminer si cet outil est pertinent. Décrivez simplement ce que l’outil renvoie : « Renvoie au format JSON l’état actuel, actif ou interrompu, ainsi que la durée d’indisponibilité d’un service surveillé. »

Pour laisser le modèle remplir une partie de la requête, utilisez l’expression $fromAI(). Elle fonctionne uniquement avec les outils connecté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 tirets. Le type doit être string, number, boolean ou json. Sa valeur par défaut est string. Un appel plus complet se présente ainsi.

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

La clé est un indice, pas une référence à des données existantes. $fromAI('service') ne lit pas quelque part un champ nommé service. Cela 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. Comme il s’agit simplement d’un autre endpoint HTTP, vous pouvez utiliser ce même nœud avec votre propre instance SearXNG plutôt qu’une API de recherche payante, à condition de considérer chaque page renvoyée comme du texte non fiable désormais inclus 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 repart de zéro. Ajoutez un sous-nœud Simple Memory pour conserver la conversation récente.

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

Context Window Length influe autant sur les coûts 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 bavard, vous payez vingt fois pour les mêmes premiers messages.

Simple Memory ne fonctionne pas dans un workflow de production actif lorsque n8n s’exécute en queue mode. Il stocke l’historique dans une Map singleton locale au processus, indexée par les identifiants du workflow et de la session. Les workers ne partagent pas cette mémoire. Sur une instance en queue mode, utilisez plutôt le sous-nœud Postgres Chat Memory et pointez-le vers 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, vous trouverez également Max Iterations, dont la valeur par défaut est 10. Une itération correspond à un appel au modèle. Celui-ci demande soit l’utilisation d’outils, soit renvoie la réponse finale ; les résultats des outils sont transmis à l’appel suivant. Une exécution de l’agent ne correspond donc pas à un seul appel d’API, mais peut en effectuer jusqu’à dix. Chaque appel contient l’intégralité de la conversation, qui s’allonge progressivement, dans ses données d’entrée.

Réduisez cette valeur. La plupart des agents qui n’utilisent qu’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 rien renvoyé d’utile ». Désactivez cette option avant la mise en production, car ces étapes sont inutiles pour l’utilisateur final.

Observez une exécution depuis le shell.

docker compose logs -f n8n

Éviter qu’un agent sans surveillance ne dépense discrètement

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 dépenses liées au modèle plutôt que celles liées aux licences, 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 surtout le travail en équipe et la gouvernance. Le traitement complet se trouve dans Contrôler les coûts d’un agent IA sur un VPS toujours actif. Quatre réglages font l’essentiel du travail ici.

• Limitez Maximum Number of Tokens sur le sous-nœud du modèle, afin qu’aucune réponse ne puisse s’exécuter trop longtemps.
• Définissez Max Iterations sur le nombre minimal d’itérations permettant d’achever la tâche.
• Gardez les réponses des outils courtes. Un outil qui renvoie un bloc JSON de 4,000 lignes l’insère en totalité 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’un schedule. 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 ce montant qu’il faut multiplier.

Dépubliez le workflow pendant vos itérations, ou retenez au moins la version actuellement active. Un workflow publié avec un Schedule Trigger continue d’exécuter la dernière version publiée, et non le brouillon affiché à l’écran, car n8n conserve vos modifications dans le brouillon jusqu’à leur nouvelle publication.

FAQ

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

Vérifiez d’abord les connecteurs. Le nœud AI Agent a besoin d’un sous-nœud de modèle de chat. Sans celui-ci, il s’arrête avec le message « Please connect a model to the Chat Model input » avant d’effectuer un appel d’API. La documentation de n8n indique également qu’au moins un sous-nœud d’outil est requis. Si le modèle est connecté et que le nœud refuse toujours de s’exécuter, ajoutez un outil, même très simple, puis relancez-le.

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

Dans la plupart des cas, le problème vient 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 quelle situation 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, il renvoie l’intégralité de la conversation jusque-là, y compris les résultats précédents des outils. Une exécution qui prend quatre itérations facture donc les tokens d’entrée et de sortie de chacun des quatre appels. Max Iterations définit la limite maximale. Return Intermediate Steps indique combien d’étapes l’exécution a réellement utilisées.

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 une Map singleton locale au processus, indexée par les identifiants du workflow et de la session. Des processus worker distincts ne partagent pas cette Map. Remplacez-la par le sous-nœud Postgres Chat Memory, qui conserve l’historique dans la base de données partagée par tous les workers.