Tracer et scorer un agent avec Langfuse

Pourquoi un agent est une boîte noire

Un prompt, c’est un appel : entrée, sortie, facile à lire. Un agent, c’est un graphe — comme je le raconte dans d’un prompt à l’agentique : il va chercher du contexte, décide, appelle un ou plusieurs modèles, se relit, boucle. Quand la sortie est mauvaise, la vraie question est : quelle étape a dérapé ?

Le vocabulaire, en 4 mots

Avant d’instrumenter, quatre notions suffisent à tout comprendre.

Instrumenter en trois lignes

On installe le SDK Langfuse et son intégration LangChain, puis on pose les clés — celles de ton instance.

$ npm i langfuse langfuse-langchain @langchain/langgraph @langchain/openai

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASEURL=https://langfuse.mondomaine.com   # ton instance auto-hebergee

L’instrumentation tient en un objet : le CallbackHandler de langfuse-langchain passé à graph.invoke relie chaque nœud du graphe — et chaque appel de modèle — à une seule trace. Pas de décorateur à poser partout.

// app/api/agent/route.ts
import { CallbackHandler } from "langfuse-langchain";
// un handler par run — relie chaque noeud LangGraph a une trace
const handler = new CallbackHandler({ sessionId });  // sessionId : optionnel
const result = await graph.invoke(
  { brief },
  { callbacks: [handler] },   // gather -> clarify -> draft -> review -> apply
);
const traceId = handler.getTraceId();   // pour y accrocher des scores ensuite

Chaque nœud qui appelle un ChatOpenAI apparaît alors comme une génération — prompt, réponse, tokens, coût — sans rien ajouter.

import { ChatOpenAI } from "@langchain/openai";
const model = new ChatOpenAI({ model: "gpt-4o" });
// un noeud du graphe : l'appel ChatOpenAI est trace comme "generation"
// (prompt, reponse, tokens, cout) sans une ligne de plus
async function draft(state: AgentState) {
  const res = await model.invoke(buildPrompt(state));
  return { draft: res.content };
}

Scorer : trois niveaux

Une trace te dit ce qui s’est passé. Un score te dit si c’était bon. Trois sources, du moins au plus automatique.

Règle métier et feedback utilisateur d’abord — simples, fiables, gratuits.

import { Langfuse } from "langfuse";
const langfuse = new Langfuse();
// 1. score programmatique (regle metier)
langfuse.score({
  traceId,
  name: "roadmap_valide",
  value: plan.milestones.length ? 1 : 0,
  comment: "au moins un jalon produit",
});
// 2. feedback utilisateur (pouce) — depuis une route API,
//    avec le traceId qu'on a renvoye au front
langfuse.score({
  traceId,
  name: "user_feedback",
  value: 1,               // 1 = pouce haut, 0 = pouce bas
  dataType: "BOOLEAN",
});

LLM-as-a-judge

Pour la qualité subjective (fidélité, ton, pertinence), un LLM-as-a-judge note la sortie d’un autre. On le trace aussi — un juge qui déraille, ça se débogue comme le reste.

import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";
// un petit modele, en sortie structuree
const judge = new ChatOpenAI({ model: "gpt-4o-mini" }).withStructuredOutput(
  z.object({ score: z.number(), reason: z.string() }),
);
async function scoreOutput(question: string, answer: string, traceId: string) {
  const v = await judge.invoke(
    `Note la reponse de 1 a 5 sur sa fidelite au contexte.
Q: ${question}
R: ${answer}`,
  );
  langfuse.score({ traceId, name: "fidelite", value: v.score, comment: v.reason });
  return v;
}

Boucler : datasets & experiments

Le vrai gain arrive quand tu rejoues un jeu de cas figé à chaque changement, via les datasets & experiments de Langfuse. Tu figes une trentaine de briefs représentatifs, et avant chaque déploiement tu relances l’agent dessus, noté par le juge. Une régression se voit avant la prod, pas après.

// rejouer un jeu de cas fige AVANT de deployer -> pas de regression
const dataset = await langfuse.getDataset("briefs-de-reference");
for (const item of dataset.items) {
  const handler = new CallbackHandler();
  const output = await graph.invoke(
    { brief: item.input },
    { callbacks: [handler] },
  );
  await item.link(handler, "v2-review-loop");   // rattache le cas au run
  await scoreOutput(item.input, output, handler.getTraceId());
}
await langfuse.flushAsync();   // vide le buffer avant la fin du process
// -> compare v1 vs v2 dans l'onglet Experiments

En prod — les pièges

Rattacher les traces au réel : sessions, users, versions

Une trace isolée répond à « ce run a-t-il marché ? ». Mais en prod, la vraie question est « ce run a-t-il marché *pour ce user*, dans *cette conversation*, sur *cette version* de l’agent ? ». Trois attributs suffisent à passer d’un tas de runs anonymes à quelque chose que tu peux filtrer et agréger.

Avec le CallbackHandler, rien de neuf à installer : tu passes ces attributs dans le `metadata` de l’invocation, et Langfuse les remonte au niveau de la trace. Les sessions acceptent n’importe quelle chaîne US-ASCII de moins de 200 caractères comme identifiant.

const handler = new CallbackHandler();
await graph.invoke(
  { brief },
  {
    callbacks: [handler],
    metadata: {
      langfuseSessionId: conversationId, // regroupe la conversation / groups the conversation
      langfuseUserId: user.id,           // segmente par user / segments by user
      langfuseTags: ["prod", "agent-v3"],
    },
  },
);

Le prompt comme objet versionné, pas comme string en dur

Tant que ton prompt vit dans le code, changer une consigne = redéployer. Le prompt management de Langfuse le sort du code : chaque édition crée une version immuable (1, 2, 3…), et un label mobile (`production`, `staging`) pointe vers la version active. Tu peux rollback en réassignant le label `production` à l’ancienne version, sans toucher au code. Le SDK met le prompt en cache côté client, donc zéro latence ajoutée.

Passer à l’échelle : OTel, échantillonnage, alertes

Trois problèmes apparaissent quand le trafic monte : s’intégrer à une stack d’observabilité existante, ne pas exploser le volume, et être prévenu quand ça part en vrille sans regarder le dashboard toute la journée.

OpenTelemetry : Langfuse comme backend OTLP

Si tu as déjà un collecteur OpenTelemetry, tu n’as pas à choisir. Langfuse est OTel-natif : il expose un endpoint OTLP sur `/api/public/otel/v1/traces` (HTTP, JSON ou protobuf — pas de gRPC pour l’instant). Tu ajoutes Langfuse comme *exporter* de ton collecteur, et les spans émis par n’importe quelle librairie instrumentée OTel se nichent automatiquement dans la bonne trace.

Échantillonnage : garder 20 % plutôt que tout

À gros volume, tout tracer coûte du stockage et noie le signal. L’échantillonnage est géré côté client : tu poses `LANGFUSE_SAMPLE_RATE` (ou `sampleRate` au constructeur) entre 0 et 1. La décision se prend *au niveau de la trace* — si une trace est retenue, toutes ses observations et scores le sont ; sinon rien ne part. Pas de trace à moitié envoyée.

# Garde 20% des traces en prod haut-volume / keep 20% of traces at high volume
LANGFUSE_SAMPLE_RATE=0.2

Alertes : ne plus fixer le dashboard

Un dashboard, personne ne le regarde à 3 h du matin. Les monitors & alertes déclenchent sur un seuil — coût moyen, p95 de latence, ou un agrégat de qualité — et notifient via Slack, webhook ou un déclencheur GitHub Actions. « p95 latence > 8 s » ou « coût moyen par trace > 0,05 $ » te pinguent avant que l’utilisateur ne râle.

Sources & ressources