03 プロンプト管理
トレースされたアプリがあります。システムプロンプトは src/server/support-agent.ts の SYSTEMPROMPT という定数に存在し、システムメッセージとして直接使用されます。
ワークショップマテリアルは公開 langfuse/langfuse-workshop リポジトリで保守されています。実行可能なアプリ、チェックポイントブランチ、ローカルセットアップについてはリポジトリを使用してください。
開始ポイント
git checkout checkpoint/03-prompt-managementトレースされたアプリがあります。システムプロンプトは src/server/support-agent.ts の SYSTEM_PROMPT という定数に存在し、システムメッセージとして直接使用されます。
このチャプターでは、そのプロンプトをLangfuseに移動して、UIでバージョン管理と編集できるようにし、要求時に取得します。ローカル定数は、Langfuseに到達できない場合のフォールバックとしてファイルに残ります。
.env に次が含まれていることを確認します:
LANGFUSE_PROMPT_NAME=dad-it-support-agent
LANGFUSE_PROMPT_LABEL=productionプロンプト管理が必要な理由
システムプロンプトをコードに保持すると、すべてのプロンプト変更はコード変更になります: pull request、review、build、deploy。Langfuse プロンプト管理では、プロンプトはLangfuse内に存在します — バージョン管理、ラベル付き、UIで編集可能 — アプリは要求時にそれを取得します。これは、非エンジニアがプロンプトを反復処理でき、変更がリリースサイクルとは独立してシップでき、すべてのバージョンが保持され、トレースにリンクされることを意味します。
Langfuse プロンプト ドキュメント でさらに詳しく学びます。
ゴール
2つのステップ:
- システムプロンプトをLangfuseに公開して、バージョン管理されたコピーがそこに存在するようにします。
- 要求時にそれを取得し、各OpenAI世代を、それを生成したバージョンにリンクします。
ステップ1 — プロンプトを公開する (Langfuse UI)
プロンプトを作成する最も直接的な方法は、UI で手動で追加することです — これは、チームが将来の反復ごとに使用するのと同じワークフローです。
- Langfuse で、Prompts → New prompt を開きます。
- それを
dad-it-support-agentと 名前付けする (.envのLANGFUSE_PROMPT_NAMEと一致)。 - Type は
textです。 src/server/support-agent.tsからSYSTEM_PROMPTの本体を 貼り付けます。- バージョンを
productionと ラベル付けしてください (.envのLANGFUSE_PROMPT_LABELと一致)。 - 保存します。
💡 代替 — スクリプト経由で公開します。
scripts/publish-prompt.tsはSYSTEM_PROMPT定数をLangfuse にプッシュアップします (npm run prompt:publish)。同じ結果。
ステップ2 — Langfuse からプロンプトを取得します
src/server/support-agent.ts に インポートを追加します:
import { LangfuseClient } from "@langfuse/client";モジュールスコープでクライアントを構築します:
const langfuse = new LangfuseClient();Langfuse から取得する getPrompt ヘルパーを追加します。失敗時に null を返し、チャットがローカル SYSTEM_PROMPT にフォールバックできるようにします:
async function getPrompt() {
try { return await langfuse.prompt.get(env.langfusePromptName); }
catch { return null; }
}runSupportConversation で使用します — 取得してから、フェッチが null を返した場合はローカル定数にフォールバックします:
const langfusePrompt = await getPrompt();
const systemPrompt = langfusePrompt?.prompt ?? SYSTEM_PROMPT;systemPrompt をシステムメッセージとして送信します。 トランスクリプトのすぐ下の何行か下にこの行を見つけます:
{ role: "system", content: SYSTEM_PROMPT },これに変更してください:
{ role: "system", content: systemPrompt },この変更がなければ、モデルはローカル定数を受け取り続けます — 次のステップのプロンプトバッジは依然として表示されますが、Langfuse のプロンプトを編集しても答えには効果がありません。
langfusePrompt を既存の observeOpenAI 呼び出しに渡して、世代が公開されたプロンプトバージョンにリンクされるようにします — 実際に1つある場合のみ:
const openai = observeOpenAI(
new OpenAI({ apiKey: env.openaiApiKey }),
langfusePrompt ? { langfusePrompt } : undefined
);注意する3つのこと:
observeOpenAI(new OpenAI(...))呼び出し自体は変更されませんでした — ステップ02からの同じインラインラップ。単にプロンプトlangfusePromptを保持する条件付き2番目の引数を追加しました。- ローカル
SYSTEM_PROMPT定数はファイルにフォールバックとして残ります。Langfuse が設定ミスであるか、プロンプトがまだ公開されていない場合、チャットは機能し続けます — そのターンにプロンプトバッジを持つだけではありません。 langfusePromptをobserveOpenAIに渡すことで、そのクライアント内で出力されるすべての世代が Prompt バッジを自動的に取得します。
確認
npm run dev1つの質問を尋ねてから、Langfuse で:
- トレースを開き、OpenAI 世代をクリックします。公開した
dad-it-support-agentバージョンにリンクする Prompt バッジが表示されます。 dad-it-support-agentの Prompts ビューで、"Used in" までスクロールして、トレースが表示されます。
ラップアップ
プロンプト管理は、トレース ↔ プロンプト ループを閉じるものです。すべてのプロンプトバージョンが保存され、すべての世代がそれを生成したバージョンを知っており、コード展開とは独立してプロンプトを反復できます。
Langfuse のベストプラクティスに沿ったプロンプト管理を配線する直接的な方法は、Langfuse スキル(/langfuse) です。スキルは、各部品を手動でロールしずに推奨パターンをコードベースに適用します。このチュートリアルが存在するのは、スキルが何をしているかを理解するためです。
最終状態
これは 04-monitoring の開始ポイントです。