03 Gerenciamento de prompts

O material do workshop é mantido no repositório público langfuse/langfuse-workshop. Use o repositório para executar a aplicação, acessar os branches de checkpoint e fazer a configuração local.

Ver este arquivo Markdown

Ponto de partida

git checkout checkpoint/03-prompt-management

Você tem uma aplicação funcional com tracing. O prompt de sistema está na constante SYSTEM_PROMPT em src/server/support-agent.ts e é usado diretamente como mensagem de sistema.

Neste capítulo, movemos esse prompt para o Langfuse, onde ele será versionado e editável pela interface, e o buscamos novamente a cada requisição. A constante local permanece no arquivo como fallback quando o Langfuse não estiver acessível.

Confirme que .env contém:

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

Por que gerenciar prompts

Manter o prompt de sistema no código transforma cada alteração de prompt em uma alteração de código: pull request, revisão, build e deploy. Com o gerenciamento de prompts do Langfuse, o prompt fica no Langfuse — versionado, rotulado e editável pela interface — e a aplicação o busca a cada requisição. Assim, pessoas não técnicas podem iterar, mudanças são publicadas fora do ciclo de releases e cada versão é preservada e vinculada aos traces que produziu.

Saiba mais na documentação de prompts do Langfuse.

Objetivo

Duas etapas:

1. Publicar o prompt de sistema no Langfuse para manter uma cópia versionada.
2. Buscá-lo a cada requisição e vincular cada generation da OpenAI à versão que a produziu.

Etapa 1 — Publicar o prompt (interface do Langfuse)

A forma mais direta de criar um prompt é adicioná-lo manualmente na interface — o mesmo fluxo que sua equipe usará em iterações futuras.

1. No Langfuse, abra Prompts → New prompt.
2. Em Name, use dad-it-support-agent (igual a LANGFUSE_PROMPT_NAME em .env).
3. Em Type, escolha text.
4. Em Paste, cole o corpo de SYSTEM_PROMPT de src/server/support-agent.ts.
5. Em Label, use production (igual a LANGFUSE_PROMPT_LABEL em .env).
6. Clique em Save.

Alternativa — publicar por script. scripts/publish-prompt.ts envia a constante SYSTEM_PROMPT ao Langfuse (npm run prompt:publish). O resultado é o mesmo.

Etapa 2 — Buscar o prompt do Langfuse

Adicione o import em src/server/support-agent.ts:

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

Crie o cliente no escopo do módulo:

const langfuse = new LangfuseClient();

Adicione um helper getPrompt que busca no Langfuse e retorna null em qualquer falha, permitindo que o chat use o SYSTEM_PROMPT local:

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

Use-o em runSupportConversation — busque e use a constante local se o resultado for nulo:

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

Envie systemPrompt como mensagem de sistema. Encontre esta linha na conversa, algumas linhas abaixo:

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

e altere para:

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

Sem essa mudança, o modelo continua recebendo a constante local. O badge Prompt da etapa seguinte ainda apareceria, mas editar o prompt no Langfuse não mudaria as respostas.

Passe langfusePrompt para a chamada existente de observeOpenAI, vinculando a generation à versão publicada somente quando houver uma:

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

Observe três pontos:

• A chamada observeOpenAI(new OpenAI(...)) não mudou — é o mesmo wrapper inline da etapa 02. Apenas adicionamos um segundo argumento condicional com langfusePrompt.
• A constante local SYSTEM_PROMPT continua no arquivo como fallback. Se o Langfuse estiver mal configurado ou o prompt ainda não estiver publicado, o chat continua funcionando; somente não exibirá o badge Prompt naquele turno.
• Passar langfusePrompt para observeOpenAI faz cada generation desse cliente carregar o badge Prompt, vinculado à versão publicada exata.

Verificação

npm run dev

Faça uma pergunta e, no Langfuse:

• Abra o trace e clique na generation da OpenAI. Ela deve mostrar um badge Prompt vinculado a dad-it-support-agent na versão publicada.
• Na visualização Prompts de dad-it-support-agent, vá até "Used in"; seu trace aparecerá ali.

Encerramento

O gerenciamento de prompts fecha o ciclo trace ↔ prompt. Cada versão é preservada, cada generation sabe qual versão a produziu e você pode iterar prompts independentemente de deploys de código.

Uma forma mais direta de conectar o gerenciamento de prompts seguindo as práticas recomendadas é a skill do Langfuse (/langfuse). Ela aplica os padrões recomendados à sua base sem que você implemente cada parte manualmente. Este passo a passo existe para mostrar o que a skill faz por baixo dos panos.

Estado final

Este é o ponto de partida para 04-monitoring.