03 Gestion des prompts

Le contenu du workshop est maintenu dans le dépôt public langfuse/langfuse-workshop. Utilisez ce dépôt pour exécuter l’application, accéder aux branches de checkpoint et effectuer la configuration locale.

Afficher ce fichier Markdown

Point de départ

git checkout checkpoint/03-prompt-management

Vous disposez d’une application fonctionnelle avec tracing. Le prompt système réside dans la constante SYSTEM_PROMPT de src/server/support-agent.ts et sert directement de message système.

Dans ce chapitre, nous déplaçons ce prompt dans Langfuse afin de le versionner et de le modifier depuis l’interface, puis nous le récupérons à chaque requête. La constante locale reste dans le fichier comme fallback lorsque Langfuse n’est pas accessible.

Vérifiez que .env contient :

LANGFUSE_PROMPT_NAME=dad-it-support-agent
LANGFUSE_PROMPT_LABEL=production

Pourquoi gérer les prompts

Conserver le prompt système dans le code transforme chaque modification en changement de code : pull request, révision, build et déploiement. Avec la gestion des prompts Langfuse, le prompt réside dans Langfuse — versionné, labellisé et modifiable dans l’interface — et l’application le récupère à chaque requête. Les personnes non techniques peuvent ainsi itérer, les changements sont publiés indépendamment des releases et chaque version est conservée et reliée aux traces qu’elle a produits.

Pour en savoir plus, consultez la documentation Langfuse sur les prompts.

Objectif

Deux étapes :

1. Publier le prompt système dans Langfuse afin d’y conserver une copie versionnée.
2. Le récupérer à chaque requête et relier chaque generation OpenAI à la version qui l’a produite.

Étape 1 — Publier le prompt (interface Langfuse)

La méthode la plus directe consiste à l’ajouter manuellement dans l’interface — le même processus que votre équipe utilisera pour les prochaines itérations.

1. Dans Langfuse, ouvrez Prompts → New prompt.
2. Dans Name, saisissez dad-it-support-agent (comme LANGFUSE_PROMPT_NAME dans .env).
3. Dans Type, choisissez text.
4. Dans Paste, collez le corps de SYSTEM_PROMPT depuis src/server/support-agent.ts.
5. Dans Label, saisissez production (comme LANGFUSE_PROMPT_LABEL dans .env).
6. Cliquez sur Save.

Alternative — publier avec un script. scripts/publish-prompt.ts envoie la constante SYSTEM_PROMPT vers Langfuse (npm run prompt:publish). Le résultat est identique.

Étape 2 — Récupérer le prompt depuis Langfuse

Ajoutez l’import dans src/server/support-agent.ts :

import { LangfuseClient } from "@langfuse/client";

Construisez le client au niveau du module :

const langfuse = new LangfuseClient();

Ajoutez un helper getPrompt qui récupère le prompt et renvoie null en cas d’échec, afin que le chat puisse utiliser le SYSTEM_PROMPT local :

async function getPrompt() {
  try { return await langfuse.prompt.get(env.langfusePromptName); }
  catch { return null; }
}

Utilisez-le dans runSupportConversation — récupérez le prompt, puis revenez à la constante locale si le résultat est nul :

const langfusePrompt = await getPrompt();
const systemPrompt = langfusePrompt?.prompt ?? SYSTEM_PROMPT;

Envoyez systemPrompt comme message système. Recherchez cette ligne dans la conversation, quelques lignes plus bas :

{ role: "system", content: SYSTEM_PROMPT },

et remplacez-la par :

{ role: "system", content: systemPrompt },

Sans ce changement, le modèle continue de recevoir la constante locale. Le badge Prompt de l’étape suivante apparaîtrait quand même, mais modifier le prompt dans Langfuse n’aurait aucun effet sur les réponses.

Transmettez langfusePrompt à l’appel observeOpenAI existant afin de relier la generation à la version publiée, uniquement lorsqu’elle existe :

const openai = observeOpenAI(
  new OpenAI({ apiKey: env.openaiApiKey }),
  langfusePrompt ? { langfusePrompt } : undefined
);

Trois points à retenir :

• L’appel observeOpenAI(new OpenAI(...)) n’a pas changé : il s’agit du même wrapper inline qu’à l’étape 02. Nous avons seulement ajouté un second argument conditionnel contenant langfusePrompt.
• La constante locale SYSTEM_PROMPT reste dans le fichier comme fallback. Si Langfuse est mal configuré ou si le prompt n’est pas encore publié, le chat continue de fonctionner ; il n’affiche simplement pas le badge Prompt pendant ce tour.
• Transmettre langfusePrompt à observeOpenAI fait porter à chaque generation de ce client le badge Prompt, relié à la version publiée exacte.

Vérification

npm run dev

Posez une question, puis dans Langfuse :

• Ouvrez le trace et cliquez sur la generation OpenAI. Elle doit afficher un badge Prompt relié à dad-it-support-agent dans la version publiée.
• Dans la vue Prompts de dad-it-support-agent, faites défiler jusqu’à "Used in" ; votre trace y apparaît.

Conclusion

La gestion des prompts referme la boucle trace ↔ prompt. Chaque version est conservée, chaque generation connaît la version qui l’a produite et vous pouvez faire évoluer les prompts indépendamment des déploiements de code.

Une méthode plus directe pour intégrer la gestion des prompts selon les bonnes pratiques est la skill Langfuse (/langfuse). Elle applique les modèles recommandés à votre code sans vous obliger à les réaliser manuellement. Ce parcours existe pour vous montrer ce qu’elle fait en coulisses.

État final

C’est le point de départ de 04-monitoring.