DEV Community

Flux Intelligent
Flux Intelligent

Posted on

Tutoriel n8n : tenir un journal de chaque décision d'un agent IA (traçabilité, relecture et amélioration)

Un agent IA en production pose vite une question simple : « Pourquoi a-t-il répondu ça ? ». Sans trace, impossible de répondre. On relit l'historique des exécutions de n8n, on cherche la bonne, et on découvre qu'elle a été purgée ou que les données utiles sont noyées dans des dizaines de nœuds.

Ce tutoriel montre comment ajouter un journal de décisions à un workflow n8n qui utilise le nœud AI Agent : une ligne par exécution, lisible par un humain, qui permet de relire, corriger et améliorer l'agent. Les noms exacts des options peuvent varier selon votre version de n8n ; la logique reste la même.

1. Ce qu'on veut garder (et ce qu'on ne veut pas garder)

Un bon journal répond à cinq questions :

  • Quand ? horodatage et identifiant d'exécution ($execution.id) ;
  • Quoi en entrée ? un résumé de la demande, pas forcément le texte complet ;
  • Qu'a décidé l'agent ? la catégorie, l'action choisie, les outils appelés ;
  • Avec quel résultat ? succès, erreur, ou transmis à un humain ;
  • Quelle version ? du prompt et du workflow, pour comparer dans le temps.

Ce qu'on évite : copier des données personnelles inutiles (numéros de téléphone, pièces d'identité, coordonnées bancaires). Si vous travaillez au Maroc, la loi 09-08 et la CNDP s'appliquent aussi à vos journaux : un log est une base de données comme une autre. Masquez ou tronquez ce qui n'est pas nécessaire.

2. Demander à l'agent une sortie structurée

Le plus simple pour journaliser une décision, c'est que l'agent la rende sous une forme prévisible. Activez une sortie structurée (par exemple avec un Structured Output Parser) et demandez un objet comme celui-ci :

{
  "categorie": "demande_devis",
  "action": "creer_tache_commerciale",
  "besoin_humain": false,
  "resume": "Demande de devis pour un chatbot WhatsApp, 2 points de vente",
  "reponse_client": "Merci, nous revenons vers vous aujourd'hui..."
}
Enter fullscreen mode Exit fullscreen mode

La réponse au client et la décision sont séparées : on journalise la seconde, on envoie la première.

3. Construire la ligne de journal avec un nœud Set (Edit Fields)

Juste après l'agent, ajoutez un nœud Edit Fields (Set) qui prépare une ligne propre :

horodatage      = {{ $now.toISO() }}
execution_id    = {{ $execution.id }}
workflow        = {{ $workflow.name }}
version_prompt  = v3
canal           = {{ $('Webhook').item.json.body.canal }}
entree_resume   = {{ $('Webhook').item.json.body.message.slice(0, 200) }}
categorie       = {{ $json.output.categorie }}
action          = {{ $json.output.action }}
besoin_humain   = {{ $json.output.besoin_humain }}
statut          = ok
Enter fullscreen mode Exit fullscreen mode

Deux remarques :

  • version_prompt est une simple valeur que vous changez à la main quand vous modifiez le prompt système. C'est elle qui vous permettra de dire « depuis la v3, l'agent classe mieux les réclamations ».
  • La troncature (slice(0, 200)) limite la quantité de texte stockée.

4. Écrire la ligne : Google Sheets pour démarrer, Postgres ensuite

Google Sheets suffit pour commencer : nœud Google Sheets → Append Row, une colonne par champ. L'équipe peut filtrer, commenter, et ajouter une colonne « correction » à remplir lors de la relecture.

Quand le volume grandit, passez à Postgres (ou toute base SQL) :

CREATE TABLE journal_agent (
  id            BIGSERIAL PRIMARY KEY,
  horodatage    TIMESTAMPTZ NOT NULL DEFAULT now(),
  execution_id  TEXT,
  workflow      TEXT,
  version_prompt TEXT,
  canal         TEXT,
  entree_resume TEXT,
  categorie     TEXT,
  action        TEXT,
  besoin_humain BOOLEAN,
  statut        TEXT,
  correction    TEXT
);
Enter fullscreen mode Exit fullscreen mode

Astuce : activez l'option Continue On Fail (ou la sortie d'erreur) sur le nœud d'écriture du journal. Un journal indisponible ne doit jamais bloquer la réponse au client.

5. Journaliser aussi les échecs

Les exécutions qui échouent sont souvent les plus instructives. Deux façons de les capter :

  1. Sortie d'erreur du nœud AI Agent : branchez-la sur le même nœud Set, avec statut = erreur et le message d'erreur ({{ $json.error.message }}).
  2. Error Workflow : un workflow séparé démarré par un Error Trigger, qui écrit une ligne avec statut = crash et l'identifiant d'exécution. Vous le déclarez dans les paramètres du workflow principal.

Ainsi, le journal contient tout : les réussites, les transmissions à un humain et les plantages.

6. Relire chaque semaine, corriger, mesurer

Un journal ne sert à rien s'il n'est jamais lu. Une routine simple :

  • chaque semaine, filtrer les lignes besoin_humain = true et statut != ok ;
  • relire un échantillon de lignes « ok » au hasard ;
  • noter dans correction ce que l'agent aurait dû faire ;
  • regrouper les corrections par type et ajuster le prompt ou les descriptions d'outils ;
  • incrémenter version_prompt et comparer la semaine suivante.

Vous pouvez même automatiser le résumé : un second workflow planifié lit les lignes de la semaine et envoie un récapitulatif (nombre d'exécutions par catégorie, nombre de transmissions humaines, erreurs). Ici, pas besoin d'IA : un nœud Summarize fait très bien le travail.

7. Garder le contrôle sur la durée de conservation

Fixez une durée de conservation et tenez-vous-y : par exemple, supprimer ou anonymiser les lignes après quelques mois avec un workflow planifié (DELETE ... WHERE horodatage < now() - interval '90 days', durée à adapter à vos obligations). Pensez aussi aux réglages d'historique d'exécution de n8n, qui conservent de leur côté les données brutes.

En résumé

  • Une sortie structurée rend la décision de l'agent facile à enregistrer.
  • Un nœud Set construit une ligne propre, versionnée et sans données superflues.
  • Google Sheets pour démarrer, Postgres quand le volume augmente.
  • Les erreurs vont dans le même journal.
  • La relecture hebdomadaire transforme le journal en outil d'amélioration.

C'est ce type de garde-fou que nous mettons en place chez Flux Intelligent quand nous déployons des agents IA pour des PME au Maroc : l'agent agit, mais chaque décision reste traçable et relue par un humain.

Top comments (0)