03 Manajemen Prompt

Materi workshop dikelola di repositori publik langfuse/langfuse-workshop. Gunakan repositori untuk aplikasi yang dapat dijalankan, cabang checkpoint, dan setup lokal.

Lihat file Markdown ini

Titik awal

git checkout checkpoint/03-prompt-management

Anda memiliki aplikasi yang terlacak dengan baik. Prompt sistem hidup sebagai konstanta bernama SYSTEM_PROMPT di src/server/support-agent.ts dan digunakan langsung sebagai pesan sistem.

Dalam bab ini kami memindahkan prompt itu ke Langfuse sehingga versioned dan dapat diedit di UI, dan kami mengambilnya kembali pada waktu permintaan. Konstanta lokal tetap dalam file sebagai fallback untuk ketika Langfuse tidak dapat dijangkau.

Pastikan .env memiliki:

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

Mengapa mengelola prompt

Menyimpan prompt sistem dalam kode berarti setiap perubahan prompt adalah perubahan kode: pull request, review, build, deploy. Dengan manajemen prompt Langfuse prompt hidup di Langfuse — versioned, labeled, dan dapat diedit di UI — dan aplikasi mengambilnya pada waktu permintaan. Itu berarti non-insinyur dapat melakukan iterasi pada prompt, perubahan pengiriman independen dari siklus rilis, dan setiap versi disimpan dan ditautkan ke jejak yang dihasilkannya.

Pelajari lebih lanjut di dokumen prompt Langfuse.

Tujuan

Dua langkah:

1. Publikasikan prompt sistem ke Langfuse sehingga salinan versioned hidup di sana.
2. Ambilnya kembali pada waktu permintaan, dan tautkan setiap generasi OpenAI ke versi yang menghasilkannya.

Langkah 1 — Publikasikan prompt (Langfuse UI)

Cara paling langsung untuk membuat prompt adalah menambahkannya secara manual di UI — ini adalah alur kerja yang sama yang akan digunakan tim Anda untuk setiap iterasi di masa depan.

1. Di Langfuse, buka Prompts → New prompt.
2. Namakan dad-it-support-agent (mencocokkan LANGFUSE_PROMPT_NAME dalam .env Anda).
3. Tipe adalah text.
4. Tempel badan SYSTEM_PROMPT dari src/server/support-agent.ts.
5. Label versi production (mencocokkan LANGFUSE_PROMPT_LABEL dalam .env Anda).
6. Simpan.

💡 Alternatif — publikasikan via skrip. scripts/publish-prompt.ts mendorong konstanta SYSTEM_PROMPT ke atas ke Langfuse (npm run prompt:publish). Hasil yang sama.

Langkah 2 — Ambil prompt dari Langfuse

Tambahkan impor di src/server/support-agent.ts:

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

Buat klien di ruang lingkup modul:

const langfuse = new LangfuseClient();

Tambahkan pembantu getPrompt yang mengambil dari Langfuse, mengembalikan null pada kegagalan apa pun sehingga chat dapat kembali ke SYSTEM_PROMPT lokal:

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

Gunakan di runSupportConversation — ambil, kemudian kembali ke konstanta lokal jika pengambilan mengembalikan null:

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

Kirim systemPrompt sebagai pesan sistem. Temukan baris ini dalam transkrip beberapa baris di bawah:

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

dan ubah menjadi:

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

Tanpa perubahan ini model terus menerima konstanta lokal — lencana Prompt di langkah berikutnya akan tetap muncul, tetapi mengedit prompt di Langfuse tidak akan berpengaruh pada jawaban.

Lewatkan langfusePrompt ke panggilan observeOpenAI yang ada sehingga generasi mendapat tautkan ke versi prompt yang dipublikasikan — hanya ketika kami benar-benar memilikinya:

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

Tiga hal yang perlu diperhatikan:

• Panggilan observeOpenAI(new OpenAI(...)) itu sendiri tidak berubah — pembungkus inline yang sama dari langkah 02. Kami hanya menambahkan argumen kedua kondisional yang membawa langfusePrompt.
• Konstanta SYSTEM_PROMPT lokal tetap dalam file sebagai fallback. Jika Langfuse salah konfigurasi atau prompt belum dipublikasikan, chat terus bekerja — itu hanya tidak akan membawa lencana Prompt pada giliran itu.
• Melewatkan langfusePrompt ke observeOpenAI adalah yang membuat setiap generasi di bawah klien itu membawa lencana Prompt yang menautkan kembali ke versi yang dipublikasikan dengan tepat.

Verifikasi

npm run dev

Tanyakan satu pertanyaan, kemudian di Langfuse:

• Buka jejak, klik generasi OpenAI. Itu harus menampilkan lencana Prompt yang menautkan ke dad-it-support-agent pada versi yang Anda publikasikan.
• Dalam tampilan Prompts untuk dad-it-support-agent, gulir ke "Used in" dan jejak Anda muncul.

Kesimpulan

Manajemen prompt adalah apa yang menutup loop jejak ↔ prompt. Setiap versi prompt disimpan, setiap generasi tahu versi mana yang menghasilkannya, dan Anda dapat melakukan iterasi prompt independen dari deploy kode.

Cara yang lebih mudah untuk kabel manajemen prompt sesuai dengan praktik terbaik Langfuse adalah keterampilan Langfuse (/langfuse). Keterampilan menerapkan pola yang direkomendasikan ke basis kode Anda tanpa Anda menggulung setiap bagian dengan tangan. Panduan ini ada sehingga Anda dapat melihat apa yang dilakukan keterampilan di bawah tenda.

Status akhir

Ini adalah titik awal untuk 04-monitoring.