Construire un agent IA fiable avec n8n & Claude

Pourquoi les agents cassent en production

En démo, on teste trois cas qui fonctionnent. En production, l'agent reçoit des messages incomplets, des pièces jointes inattendues, des demandes hors sujet, et parfois une API qui ne répond pas. Les pannes que je rencontre le plus souvent ont presque toujours la même origine :

Une sortie libre : le modèle répond en texte, et le workflow essaie d'en extraire une décision.
Aucun contrôle entre la réponse du modèle et l'action déclenchée.
Un contexte trop large : on envoie toute la fiche client ou tout l'historique, ce qui coûte cher et brouille la réponse.
Pas de journal : quand un client se plaint, impossible de savoir ce que l'agent a reçu et décidé.

La bonne nouvelle, c'est que ces quatre problèmes se règlent avec de l'architecture, pas avec un meilleur prompt.

L'architecture en cinq étapes

Tous mes agents n8n suivent le même squelette. Il reste lisible même quand le workflow grossit.

Déclencheur : webhook, formulaire, e-mail entrant, événement CRM.
Préparation du contexte : je récupère uniquement les données utiles à la décision (statut de commande, trois derniers échanges, offre souscrite).
Appel à Claude avec un prompt système court et une sortie JSON imposée.
Validation : un nœud Code vérifie le format et les valeurs autorisées.
Action et journal : réponse au client, mise à jour du CRM ou escalade, puis écriture dans la table de logs.

Le squelette type d'un agent dans n8n : déclencheur, contexte, modèle, validation, action.

Imposer une sortie structurée

Je demande toujours au modèle de répondre dans un format JSON fixe. Le workflow ne lit jamais de texte libre pour prendre une décision.

{
  "intent": "suivi_commande",
  "confidence": 0.86,
  "reply": "Votre commande a été expédiée hier...",
  "action": "send_reply",
  "needs_human": false
}

Dans n8n, un nœud Code vérifie que chaque champ existe et que intent et action font partie des valeurs autorisées. Si la validation échoue, le workflow relance une fois le modèle en lui renvoyant l'erreur. Au deuxième échec, la demande part vers un humain.

Les garde-fous indispensables

Risque	Garde-fou	Dans n8n
Réponse mal formée	Validation du schéma, une relance avec l'erreur	Code + If
API lente ou en erreur	Timeout et nouvelles tentatives espacées	Option Retry On Fail du nœud
Décision sensible	Validation humaine avant exécution	Wait + notification Slack ou e-mail
Confiance faible	Seuil sous lequel l'agent n'agit pas	If sur `confidence`
Dérive de coût	Contexte réduit, limite de tokens, suivi par exécution	Paramètres du modèle + log
Boucle sans fin	Compteur d'itérations	Variable + If

Ce que je ne confie jamais à un agent seulPaiements, remboursements, suppression de données et envois en masse. L'agent prépare l'action et la justifie, une personne la valide en un clic.

Journaliser chaque exécution

Chaque passage dans l'agent écrit une ligne dans une table Airtable ou Postgres. C'est ce qui permet de répondre à un client, de mesurer la qualité et d'améliorer le prompt avec de vrais cas.

Date, identifiant de l'exécution et source du déclenchement
Entrée envoyée au modèle et sortie brute reçue
Décision prise et action exécutée
Durée, tokens consommés et statut (succès, relance, escalade)

Un prompt système court et testable

Mon prompt système tient en quatre blocs : le rôle, les règles, le format de sortie, et deux ou trois exemples. Je le versionne comme du code. Avant chaque modification, je rejoue un jeu d'une vingtaine de cas réels tirés du journal et je compare les décisions avant et après.

Checklist

La sortie du modèle est en JSON et validée avant toute action
Les actions sensibles passent par une validation humaine
Un seuil de confiance bloque les réponses incertaines
Les nœuds d'API ont un timeout et des nouvelles tentatives
Chaque exécution est journalisée avec son coût
Le prompt est versionné et testé sur des cas réels