Observabilité des agents IA dans n8n avec LangSmith : tracer via l'API REST

Un AI Agent n8n qui répond depuis une base documentaire ou trie des emails enchaîne plusieurs appels de modèle et d'outils dont l'ordre varie à chaque exécution. Notre guide sur Langfuse couvrait déjà comment brancher ce type d'agent sur un outil d'observabilité dédié — mais si votre équipe utilise déjà LangChain, LangGraph ou le Prompt Hub de LangSmith côté Python, la question se pose différemment : peut-on faire remonter les exécutions n8n dans ce même système de traces, déjà en place ailleurs dans la stack ? La réponse est oui, mais avec une différence structurelle importante par rapport à Langfuse : il n'existe pas de community node de tracing pour LangSmith. Tout passe par son API REST.

Pourquoi LangSmith plutôt qu'un autre outil

LangSmith est la plateforme d'observabilité et d'évaluation développée par l'équipe LangChain. Elle a du sens en particulier si une partie de vos agents IA vit déjà dans cet écosystème (agents Python en LangGraph, prompts gérés via le Prompt Hub) : brancher n8n dessus fait remonter vos workflows dans le même tableau de bord que le reste de votre stack IA, plutôt que d'ajouter un outil isolé propre à n8n. Si ce n'est pas votre cas, Langfuse — avec son community node de tracing prêt à l'emploi — demande nettement moins de plomberie manuelle pour un résultat comparable ; la section comparative plus bas détaille ce choix.

Pas de community node de tracing : direction l'API REST

Un seul community node existe côté LangSmith pour n8n : n8n-nodes-langsmith-prompt, qui expose une opération « Fill Prompt Template » — il récupère un prompt versionné par son nom depuis le Prompt Hub et y injecte vos variables. C'est utile pour la gestion de prompts, mais ça ne trace rien : aucune exécution n'est envoyée à LangSmith avec ce node. Pour tracer un AI Agent — coût, latence, inputs/outputs de chaque run — la voie disponible aujourd'hui consiste à appeler directement les endpoints /runs de l'API REST LangSmith (https://api.smith.langchain.com) avec deux nodes HTTP Request : un pour démarrer le run, un pour le clôturer.

Créer un projet et récupérer une clé API

Sur smith.langchain.com, un compte gratuit (quota mensuel de traces suffisant pour tester) donne accès à Settings → API Keys, où générer une clé. Contrairement à Langfuse qui distingue Public Key et Secret Key, LangSmith n'utilise qu'une seule clé, envoyée dans l'en-tête x-api-key de chaque requête. Stockez-la dans un credential HTTP Header Auth n8n plutôt que dans un champ statique du node — le même principe que celui détaillé dans notre guide pour sécuriser les credentials API.

Démarrer un run : POST /runs

En entrée de votre AI Agent (ou juste avant, sur son trigger), un premier node HTTP Request envoie une requête POST https://api.smith.langchain.com/runs avec un corps JSON du type :

{
  "id": "{{ $json.runId }}",
  "name": "tri-email-agent",
  "run_type": "chain",
  "inputs": { "email": "{{ $json.emailBody }}" },
  "start_time": "{{ $now.toUTC().toISO() }}",
  "session_name": "flowkit-inbox-ia",
  "tags": ["n8n", "pack-inbox-ia"]
}

Le champ id doit être un UUID généré côté n8n — un node Code placé juste avant, avec crypto.randomUUID(), suffit et permet de réutiliser cette même valeur pour le PATCH de clôture. Le champ run_type prend les valeurs chain, llm ou tool selon ce que représente le run ; pour tracer l'agent dans son ensemble, chain est le choix naturel. session_name détermine le projet LangSmith dans lequel la trace apparaît : s'il n'existe pas encore, LangSmith le crée automatiquement — inutile de le préconfigurer depuis l'interface.

Clôturer le run : PATCH /runs/{run_id}

En sortie de l'agent, un second node HTTP Request envoie PATCH https://api.smith.langchain.com/runs/{{ $json.runId }} avec la sortie et l'horodatage de fin :

{
  "outputs": { "categorie": "{{ $json.categorie }}", "urgence": "{{ $json.urgence }}" },
  "end_time": "{{ $now.toUTC().toISO() }}"
}

C'est ce PATCH, et lui seul, qui referme visuellement le run dans l'interface LangSmith. Un piège fréquent (détaillé plus bas) consiste à ne le brancher que sur le chemin de succès : sur une branche d'erreur, il faut aussi appeler ce PATCH, avec un champ error renseigné plutôt que outputs, faute de quoi le run reste affiché « en cours » indéfiniment — exactement le type d'échec silencieux que notre guide sur l'Error Workflow recommande de router explicitement plutôt que de laisser filer.

Nester les appels d'outils : une limite pratique à connaître

L'API REST accepte un champ parent_run_id pour rattacher un run enfant (un appel d'outil précis) à un run parent (l'agent dans son ensemble), reconstituant ainsi une hiérarchie de traces. En pratique, le faire à la main pour chaque appel d'outil d'un AI Agent n8n (recherche RAG, appel HTTP, écriture Supabase) demande d'entourer chacun d'un couple POST/PATCH avec le bon parent_run_id — ce que les SDK Python/JS de LangSmith automatisent nativement, mais que rien n'automatise côté n8n aujourd'hui. Pour la plupart des workflows, tracer uniquement le run de haut niveau (la chaîne complète, avec ses inputs et outputs finaux) apporte déjà l'essentiel : le détail interne outil-par-outil reste consultable dans le log natif n8n ou dans intermediateSteps, comme décrit dans notre guide sur la journalisation des décisions d'un agent IA. Réserver le nesting complet aux agents dont le comportement multi-outils est réellement le point à surveiller évite un montage disproportionné par rapport au bénéfice.

Ce modèle de traces en arbre parent/enfant n'est pas propre à LangSmith : il reprend directement celui popularisé par Dapper, le système de tracing distribué interne de Google décrit par Sigelman et ses coauteurs dans Dapper, a Large-Scale Distributed Systems Tracing Infrastructure (Google, 2010), qui a posé les bases du couple span parent/span enfant repris depuis par la quasi-totalité des outils d'observabilité modernes, y compris pour les agents IA.

Bonus : tirer vos prompts versionnés avec le community node dédié

Si vos prompts vivent déjà dans le Prompt Hub de LangSmith — pratique courante pour une équipe qui versionne ses prompts comme du code — le community node n8n-nodes-langsmith-prompt (installable via Settings → Community Nodes sur une instance self-hosted) permet de les récupérer directement dans un workflow n8n avec l'opération « Fill Prompt Template », plutôt que de dupliquer le texte du prompt entre votre code Python et vos workflows n8n.

LangSmith ou Langfuse ?

• Déjà dans l'écosystème LangChain/LangGraph, prompts gérés via le Prompt Hub → LangSmith, pour centraliser toutes les traces au même endroit.
• Stack n8n pure, envie d'un montage prêt à l'emploi sans plomberie HTTP manuelle → Langfuse, dont le community node de tracing capture automatiquement générations et appels d'outils.
• Besoin de garder les traces sur votre propre infrastructure → Langfuse self-hosted plutôt que LangSmith, qui reste un service cloud (offre Enterprise self-hosted à part).

Les deux ne sont d'ailleurs pas exclusifs : rien n'empêche de tracer un agent n8n vers LangSmith pour le faire cohabiter avec des agents Python existants, tout en gardant Langfuse pour d'autres workflows purement n8n.

Pièges fréquents

• Oublier le PATCH sur la branche d'erreur : un run jamais clôturé reste « en cours » indéfiniment et fausse toute lecture agrégée des durées.
• Régénérer un nouvel UUID au lieu de réutiliser celui du POST : sans le même id, le PATCH crée un second run orphelin au lieu de clôturer le premier.
• Oublier le fuseau UTC : start_time et end_time doivent être au format ISO UTC ; un horodatage local non converti fausse les durées calculées.
• Coder la clé API en dur dans le node HTTP Request plutôt que dans un credential dédié — le même risque que pour n'importe quelle clé API n8n.

Pour aller plus loin

Le Pack Assistant RAG (119 €) et le Pack Conformité & Audit (149 €) reposent tous deux sur un agent conversationnel dont la qualité de réponse mérite d'être suivie dans la durée, pas seulement testée une fois — un complément naturel à notre guide sur n8n Evaluations pour objectiver les scores, une démarche dont l'intérêt rejoint celui du LLM-as-judge documenté par Zheng et ses coauteurs dans Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena (NeurIPS, 2023 — voir l’étude). Si l'observabilité de vos automatisations IA est un sujet transverse à toute votre pile, le Bundle FlowKit Complet (269 €) réunit les trois packs sur cette même exigence de base.