Créer un agent IA sur son propre serveur n8n

Qu'est-ce qu'un agent IA n8n et en quoi diffère-t-il d'une chaîne

Un agent IA n8n est un nœud AI Agent unique auquel sont rattachés des sous-nœuds : un modèle de chat, un ou plusieurs outils, et une mémoire optionnelle. Vous définissez un objectif en langage naturel, et le modèle décide quels outils appeler et dans quel ordre jusqu'à ce qu'il puisse répondre. Tout ce qui suit concerne la configuration autour de ce concept.

Une chaîne fonctionne à l'inverse. Dans une Basic LLM Chain, vous décidez des étapes et le modèle se contente de générer du texte. Dans un agent, c'est le modèle qui décide des étapes ; ainsi, une même question peut nécessiter un appel au modèle aujourd'hui et neuf demain. Cette différence unique dicte chaque paramètre de ce guide.

Ce guide suppose que n8n est déjà opérationnel derrière HTTPS sur une machine que vous contrôlez. Si ce n'est pas le cas, commencez par auto-héberger n8n sur Docker avec un certificat valide, car la clé API que vous allez stocker nécessite la sauvegarde de la clé de chiffrement préconisée dans ce guide. Pour les modèles sans agent, les résumeurs 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 indiqués ici, car n8n modifie fréquemment les 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 en tant que Tools Agent, le menu déroulant de type d'agent n'existe donc plus.

Étape 1 : choisir le déclencheur

Pour un agent conversationnel, ajoutez un nœud Chat Trigger. Laissez l'option Make Chat Publicly Available désactivée pendant la phase de construction, afin que seul le panneau de chat de l'éditeur puisse y accéder. Activez-la une fois l'agent terminé et l'authentification définie.

Le Chat Trigger transmet à l'agent un champ nommé chatInput. Ce nom est important à l'étape 3, et une erreur à ce niveau est la cause d'échec la plus fréquente lors de la première utilisation.

Pour un agent autonome, utilisez plutôt un nœud Schedule Trigger ou Webhook. Aucun des deux ne génère de chatInput, vous devrez donc rédiger le prompt vous-même.

Étape 2 : les identifiants du modèle

Déposez un nœud AI Agent sur le canevas. n8n affiche immédiatement un connecteur Chat Model vide en dessous. Attachez-y un sous-nœud Anthropic Chat Model.

Créez les identifiants depuis la console Anthropic sur platform.claude.com, sous 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 est distincte de tout abonnement Claude.ai ; le compte doit donc disposer d'un moyen de paiement configuré avant la première exécution.

Choisissez le modèle par agent, et non par entreprise. Un agent doté d'un seul outil qui effectue une recherche et en rend compte fonctionne très bien avec Haiku, qui, en juillet 2026, est facturé 1 $ par million de tokens en entrée et 5 $ par million en sortie. Dès que l'agent dispose de plusieurs outils et doit planifier leur utilisation, passez à Sonnet. Vous évitez ainsi l'échec d'un modèle bon marché qui appelle quatre fois le mauvais outil, ce qui coûte plus cher qu'un modèle coûteux appelant une seule fois le bon outil.

Définissez le Maximum Number of Tokens dans les options du sous-nœud. Cela limite la longueur de chaque réponse produite par le modèle. Si vous laissez la valeur par défaut élevée, une exécution erronée peut générer une réponse très longue et vous être facturée en conséquence.

Une mise en garde de la documentation n8n qui piège tout le monde : les expressions à l'intérieur d'un sous-nœud sont toujours résolues par rapport au premier élément en entrée, jamais par élément. Placez les expressions traitant 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 dispose de deux réglages.

• Take from previous node automatically attend un champ entrant nommé chatInput. C'est le choix approprié derrière un Chat Trigger.
• Define below affiche un champ Prompt (User Message) où vous saisissez du texte statique ou une expression. C'est le choix approprié derrière un Schedule Trigger ou un nœud Webhook.

Avec un nœud Webhook en amont, le corps d'une requête POST arrive sous $json.body, le champ du 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 : donner 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, car un outil fonctionnel vous apprendra davantage que quatre outils mal configurés.

Connectez un nœud HTTP Request au connecteur Tool de l'agent. Configurez-le exactement comme vous le feriez pour un nœud HTTP Request standard, puis testez d'abord ce point de terminaison depuis un shell.

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

Si ce curl renvoie une erreur ou une page de connexion HTML, l'agent échouera également. L'échec semblera provenir du modèle alors qu'il s'agit en réalité d'un problème d'URL ou d'authentification. Corrigez-le au niveau du shell, pas dans le nœud.

Le champ Description de l'outil n'est pas une documentation pour vos collègues. C'est la seule chose que le modèle lit pour décider si cet outil est pertinent. Rédigez-le comme une déclaration simple de ce qui est renvoyé : "Renvoie l'état actuel (up ou down) et la durée d'indisponibilité pour un service surveillé, au format JSON."

Pour laisser le modèle remplir une partie de la requête, utilisez l'expression $fromAI(). Elle ne fonctionne que dans les outils connectés à un nœud AI Agent et ne fonctionne pas dans l'outil Code.

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

Les arguments sont key, suivis d'un description optionnel, type et defaultValue. La clé doit comporter entre 1 et 64 caractères, en utilisant des lettres, des chiffres, des underscores et des tirets. Le type est l'un des suivants : string, number, boolean ou json, et la valeur par défaut est string. Un appel plus complet ressemble à ceci.

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

La clé est une indication, pas une référence à des données existantes. $fromAI('service') ne lit pas un champ nommé service depuis une source quelconque. Il indique au modèle : "produis une valeur et appelle-la service", et le modèle parcourt la conversation, les données d'entrée et les résultats d'autres outils pour en trouver une. Dans un flux de discussion, il peut simplement poser la question à l'utilisateur.

Étape 5 : la mémoire, et pourquoi l'agent oublie

Sans sous-nœud de mémoire, chaque message repart de zéro. Attachez un sous-nœud Simple Memory pour conserver la conversation récente.

Il possède deux paramètres. Session Key détermine de quelle conversation il s'agit ; ainsi, deux utilisateurs avec des clés différentes disposent d'historiques séparés. Context Window Length définit combien d'interactions précédentes sont réinjectées dans le prompt.

La valeur de Context Window Length influe autant sur le coût que sur la qualité, car chaque tour mémorisé est renvoyé en tant que jetons d'entrée à chaque appel ultérieur. Une fenêtre de 20 sur un agent bavard signifie que vous payez vingt fois pour les mêmes messages initiaux.

Simple Memory ne fonctionne pas dans un flux de production actif lorsque n8n s'exécute en mode file d'attente, car l'historique réside dans les données propres au workflow plutôt que dans un stockage partagé. Sur une instance en mode file d'attente, 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 Message système. C'est ici que vous insérez la description de la tâche ; il s'agit du texte ayant le plus d'impact dans votre flux de travail.

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.

« Appelez toujours l'outil de statut avant de répondre » joue ici un rôle déterminant. Sans cette instruction, un modèle qui pense déjà connaître la réponse ignorera l'outil et répondra de mémoire. Il fournira alors une réponse erronée dès que votre infrastructure changera.

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

Dans les Options, vous trouverez également Max Iterations, dont la valeur par défaut est 10. Une itération correspond à un appel au modèle suivi d'un résultat d'outil réinjecté dans le contexte. Ainsi, une exécution d'agent ne représente pas un seul appel API, mais jusqu'à dix, chacun transportant l'intégralité de la conversation croissante en entrée.

Réduisez cette valeur. La plupart des agents utilisant un seul outil terminent en deux itérations. Une limite de 3 ou 4 tours transforme une boucle infinie en un échec propre, visible dans la liste d'exécution.

Pendant le débogage, activez Return Intermediate Steps. La sortie finale inclut alors les appels d'outils effectués par l'agent. Cela permet de distinguer le cas où « le modèle n'a jamais appelé l'outil » de celui où « l'outil n'a rien renvoyé d'utile ». Désactivez cette option avant la mise en production, car ces étapes constituent du bruit pour l'utilisateur final.

Surveillez une exécution depuis le shell.

docker compose logs -f n8n

Empêcher un agent sans surveillance de consommer silencieusement

Un agent derrière un Chat Trigger implique une intervention humaine, et cet humain l'arrête si la réponse semble incorrecte. Un agent derrière un Schedule Trigger n'est surveillé par personne. La procédure complète se trouve dans Contrôle des coûts d'un agent IA sur un VPS permanent. Quatre paramètres effectuent la majeure partie du travail ici.

• Limitez le Maximum Number of Tokens sur le sous-nœud du modèle, afin qu'aucune réponse unique ne puisse être trop longue.
• Définissez Max Iterations sur le nombre le plus petit permettant d'accomplir la tâche.
• Maintenez les réponses des outils aussi courtes que possible. Un outil qui renvoie un blob JSON de 4 000 lignes l'intègre entièrement dans l'appel suivant au modèle, puis dans chaque appel ultérieur au cours de la même exécution.
• Demandez-vous si l'agent a réellement besoin d'un planning. Une tâche s'exécutant toutes les cinq minutes se déclenche 288 fois par jour. Quel que soit le coût d'une exécution, c'est ce chiffre que vous devez multiplier.

Désactivez le workflow pendant vos itérations. Un workflow actif avec un Schedule Trigger continue de s'exécuter sur la version enregistrée par n8n, qui n'est pas toujours la version affichée à votre é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 possédant un modèle mais aucun outil échoue avant même d'effectuer un appel API. Attachez un outil, même trivial, et relancez l'exécution.

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

Il s'agit presque toujours du champ Description de l'outil. Le modèle choisit les outils en lisant ces descriptions ; une description comme "Requête HTTP" ne lui indique pas quand utiliser l'outil. Réécrivez-la pour préciser quelles données sont renvoyées et dans quelle situation l'outil est utile, puis ajoutez une ligne au System Message demandant à l'agent d'appeler cet outil avant de répondre.

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

Parce que le modèle choisit le nombre d'étapes. Chaque itération renvoie l'intégralité de la conversation jusqu'à présent, y compris les sorties d'outils précédentes. Une exécution qui nécessite quatre itérations coûte donc beaucoup plus cher qu'un simple appel multiplié par quatre. Max Iterations définit le plafond, et Return Intermediate Steps vous indique combien d'étapes une exécution donnée 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 s'exécute en mode file d'attente (queue mode). Simple Memory stocke l'historique dans les données d'exécution du workflow lui-même, ce qui ne survit pas au transfert vers un processus worker distinct. Un workflow de production actif perd donc ces données. Remplacez-le par le sous-nœud Postgres Chat Memory, qui conserve l'historique dans la base de données partagée par tous les workers.