03 Gestión de prompts

El material del workshop se mantiene en el repositorio público langfuse/langfuse-workshop. Usa el repositorio para ejecutar la aplicación, acceder a las ramas de checkpoint y realizar la configuración local.

Ver este archivo Markdown

Punto de partida

git checkout checkpoint/03-prompt-management

Tienes una aplicación funcional con tracing. El prompt de sistema vive en la constante SYSTEM_PROMPT de src/server/support-agent.ts y se utiliza directamente como mensaje de sistema.

En este capítulo llevamos ese prompt a Langfuse para versionarlo y editarlo desde la interfaz, y lo recuperamos en cada solicitud. La constante local permanece en el archivo como fallback cuando Langfuse no está disponible.

Comprueba que .env contiene:

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

Por qué gestionar prompts

Mantener el prompt de sistema en el código convierte cada cambio de prompt en un cambio de código: pull request, revisión, build y despliegue. Con la gestión de prompts de Langfuse, el prompt vive en Langfuse —versionado, etiquetado y editable desde la interfaz— y la aplicación lo recupera en cada solicitud. Así, personas no técnicas pueden iterar, los cambios se publican fuera del ciclo de releases y cada versión se conserva y se vincula a los traces que produjo.

Más información en la documentación de prompts de Langfuse.

Objetivo

Dos pasos:

1. Publicar el prompt de sistema en Langfuse para conservar una copia versionada.
2. Recuperarlo en cada solicitud y vincular cada generation de OpenAI con la versión que la produjo.

Paso 1 — Publicar el prompt (interfaz de Langfuse)

La forma más directa de crear un prompt es añadirlo manualmente en la interfaz: es el mismo flujo que utilizará tu equipo en cada iteración futura.

1. En Langfuse, abre Prompts → New prompt.
2. En Name, usa dad-it-support-agent (igual que LANGFUSE_PROMPT_NAME en .env).
3. En Type, elige text.
4. En Paste, pega el cuerpo de SYSTEM_PROMPT desde src/server/support-agent.ts.
5. En Label, usa production (igual que LANGFUSE_PROMPT_LABEL en .env).
6. Pulsa Save.

Alternativa: publicar mediante un script. scripts/publish-prompt.ts envía la constante SYSTEM_PROMPT a Langfuse (npm run prompt:publish). El resultado es el mismo.

Paso 2 — Recuperar el prompt de Langfuse

Añade el import en src/server/support-agent.ts:

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

Crea el cliente en el ámbito del módulo:

const langfuse = new LangfuseClient();

Añade un helper getPrompt que recupere el prompt y devuelva null ante cualquier fallo, permitiendo al chat usar el SYSTEM_PROMPT local:

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

Úsalo en runSupportConversation: recupera el prompt y utiliza la constante local si el resultado es nulo:

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

Envía systemPrompt como mensaje de sistema. Busca esta línea en la conversación unas líneas más abajo:

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

y cámbiala por:

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

Sin este cambio, el modelo sigue recibiendo la constante local. La insignia Prompt del paso siguiente seguiría apareciendo, pero editar el prompt en Langfuse no afectaría a las respuestas.

Pasa langfusePrompt a la llamada existente de observeOpenAI para vincular la generation con la versión publicada, solo cuando exista una:

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

Tres detalles importantes:

• La llamada observeOpenAI(new OpenAI(...)) no cambió: es el mismo wrapper inline del paso 02. Solo añadimos un segundo argumento condicional que lleva langfusePrompt.
• La constante local SYSTEM_PROMPT permanece como fallback. Si Langfuse está mal configurado o el prompt aún no está publicado, el chat sigue funcionando; simplemente no mostrará la insignia Prompt en ese turno.
• Pasar langfusePrompt a observeOpenAI hace que cada generation de ese cliente lleve la insignia Prompt, vinculada a la versión publicada exacta.

Verificación

npm run dev

Haz una pregunta y, en Langfuse:

• Abre el trace y selecciona la generation de OpenAI. Debe mostrar una insignia Prompt vinculada a dad-it-support-agent en la versión publicada.
• En la vista Prompts de dad-it-support-agent, desplázate hasta "Used in"; allí aparecerá tu trace.

Cierre

La gestión de prompts cierra el ciclo trace ↔ prompt. Cada versión se conserva, cada generation conoce la versión que la produjo y puedes iterar prompts de forma independiente a los despliegues de código.

Una forma más directa de conectar la gestión de prompts según las prácticas recomendadas es la skill de Langfuse (/langfuse). Aplica los patrones recomendados a tu código sin que implementes cada pieza a mano. Este recorrido existe para que entiendas lo que hace la skill por debajo.

Estado final

Este es el punto de partida para 04-monitoring.