跳到正文
DEV Community· Flux Intelligent·· 4 天前AI 評分60

n8n 教學:如何為 AI Agent 配置工具,避免誤用

Tutoriel n8n : donner des outils à un agent IA sans qu'il s'emmêle (descriptions, $fromAI et garde-fous)

AI 導讀

Flux Intelligent 分享 n8n AI Agent 工具配置教學,涵蓋工具描述、參數設定和操作防護。文中建議只讓模型透過 $fromAI() 填寫依對話而定的欄位,並把 API 認證保存在 n8n Credentials;敏感操作可先經子工作流程加入人工驗證或檢查。工具輸出應精簡且結構化,並設定 AI Agent 的 Max Iterations,以避免不必要的重複呼叫。

正文

Un agent IA dans n8n devient vraiment utile au moment où il peut agir : consulter un stock, chercher un client dans le CRM, créer un rendez-vous. Mais c'est aussi là que les ennuis commencent : l'agent appelle le mauvais outil, invente un paramètre, ou appelle trois fois la même API pour une question simple.

Dans la grande majorité des cas, le problème ne vient pas du modèle : il vient de la façon dont les outils sont présentés. Ce tutoriel montre comment brancher des outils sur le nœud AI Agent de n8n de manière propre et prévisible. Les noms exacts des options peuvent varier selon votre version de n8n ; la logique reste la même.

1. Comprendre ce que l'agent « voit »

Quand vous connectez un outil (HTTP Request Tool, Google Sheets Tool, un sous-workflow via Call n8n Workflow Tool…) au connecteur Tool de l'AI Agent, le modèle ne voit pas votre configuration. Il voit essentiellement trois choses :

  • le nom de l'outil ;
  • sa description ;
  • la liste des paramètres qu'il doit remplir.

C'est tout. Si la description dit « Outil API », le modèle devine. S'il devine, il se trompe tôt ou tard.

2. Écrire une description qui dit quand utiliser l'outil… et quand ne pas l'utiliser

Une bonne description répond à quatre questions : ce que fait l'outil, quand l'utiliser, quand ne pas l'utiliser, et ce qu'il renvoie. Exemple pour un outil de consultation de stock :

Nom : verifier_stock
Description : Renvoie la quantité disponible d'un produit à partir de sa référence (SKU).
À utiliser uniquement quand le client demande si un produit est disponible.
Ne pas utiliser pour les prix ni les délais de livraison.
Renvoie un JSON { "sku": string, "quantite": number }. Si le SKU est inconnu, renvoie quantite = -1.

Quelques règles simples :

  • Un nom en snake_case, explicite : verifier_stock plutôt que HTTP Request1.
  • Un outil = une action. Évitez l'outil « couteau suisse » qui fait lecture, écriture et suppression selon un paramètre.
  • Décrivez la sortie, surtout les cas vides ou d'erreur, pour que l'agent sache quoi répondre au client.

3. Laisser le modèle remplir uniquement ce qu'il doit remplir avec $fromAI()

Dans les nœuds outils, n8n permet de marquer un champ comme rempli par le modèle, soit via le bouton dédié à côté du champ, soit avec l'expression $fromAI() :

{{ $fromAI('sku', 'Référence produit exacte, ex. TSH-001, telle que donnée par le client', 'string') }}

Le principe à retenir : le modèle ne remplit que ce qui dépend de la conversation. Tout le reste est fixé par vous :

Champ Qui le remplit ?
URL de l'API, méthode, en-têtes Vous (fixe)
Authentification Credential n8n (jamais dans le prompt)
SKU, date souhaitée, nom du client Le modèle, via $fromAI()
Limite de résultats, filtres de sécurité Vous (fixe)

Plus il y a de champs fixes, moins l'agent a d'occasions de se tromper. Et une clé API ne doit jamais transiter par le modèle : elle reste dans les Credentials de n8n.

4. Séparer les outils de lecture et les outils d'action

Un outil qui lit (consulter un stock, chercher une fiche client) est peu risqué. Un outil qui agit (créer une commande, envoyer un message, modifier un statut) mérite plus de précautions :

  • donnez-lui un nom qui commence par un verbe d'action clair : creer_rendez_vous ;
  • précisez dans la description les conditions préalables (« seulement après confirmation explicite du client ») ;
  • pour les actions sensibles, faites passer l'appel par un sous-workflow qui ajoute une validation humaine ou des contrôles (montant maximum, champs obligatoires) avant d'exécuter quoi que ce soit.

Le sous-workflow a un autre avantage : vous pouvez y valider les paramètres reçus (format du SKU, date dans le futur…) et renvoyer un message d'erreur lisible à l'agent au lieu de laisser l'API planter.

5. Renvoyer des réponses courtes et structurées

Les outils renvoient souvent beaucoup trop de données : une réponse d'API de 200 champs consomme du contexte et noie l'information utile. Ajoutez un nœud Set (Edit Fields) en fin de sous-workflow pour ne garder que l'essentiel :

{ "sku": "TSH-001", "quantite": 12, "entrepot": "Casablanca" }

Et quand rien n'est trouvé, renvoyez quelque chose d'explicite ({ "trouve": false, "raison": "SKU inconnu" }) plutôt qu'une liste vide que l'agent risque d'interpréter de travers.

6. Cadrer l'usage des outils dans le prompt système

Le prompt système de l'agent complète les descriptions. Restez court et concret :

Tu es l'assistant commercial de la boutique.
- Pour toute question de disponibilité, utilise verifier_stock avant de répondre.
- N'appelle jamais creer_commande sans que le client ait confirmé le produit et la quantité.
- Si un outil renvoie une erreur, dis-le simplement et propose de transmettre à un conseiller.
- N'invente jamais un stock, un prix ou un délai.

Pensez aussi à limiter le nombre d'itérations de l'agent (option Max Iterations du nœud AI Agent) pour éviter les boucles d'appels inutiles.

7. Vérifier ce que l'agent a réellement fait

Dans l'historique des exécutions, ouvrez le nœud AI Agent : n8n affiche chaque appel d'outil avec les paramètres envoyés et la réponse obtenue. C'est le meilleur endroit pour repérer :

  • un outil jamais appelé (description trop vague ou trop proche d'un autre outil) ;
  • des paramètres mal remplis (description du $fromAI() à préciser, exemple à ajouter) ;
  • des appels en double (sortie d'outil pas assez claire).

Corrigez une chose à la fois, puis rejouez vos cas de test.

En résumé

  1. Un nom explicite et une description qui dit quand utiliser et quand ne pas utiliser l'outil.
  2. Le modèle ne remplit que les paramètres liés à la conversation ; le reste est fixe.
  3. Les outils d'action passent par un sous-workflow avec contrôles.
  4. Des sorties courtes, structurées, avec des cas d'erreur explicites.
  5. Un prompt système bref et une limite d'itérations.

Chez Flux Intelligent, à Casablanca, c'est la base que nous appliquons quand nous concevons des agents IA pour les PME : peu d'outils, bien décrits, et des garde-fous avant chaque action.

來源:DEV Community · dev.to