Langfuse Prompt Migration

Prerequisites

echo $LANGFUSE_PUBLIC_KEY   # pk-...
echo $LANGFUSE_SECRET_KEY   # sk-...
echo $LANGFUSE_HOST         # https://cloud.langfuse.com or self-hosted

Migration Flow

1. Scan codebase for prompts
2. Analyze templating compatibility
3. Propose structure (names, subprompts, variables)
4. User approves
5. Create prompts in Langfuse
6. Refactor code to use get_prompt()
7. Link prompts to traces (if tracing enabled)
8. Verify application works

Step 1: Find Prompts

messages=[{"role": "system", "content": "..."}]

system="..."

ChatPromptTemplate

SystemMessage

system: "..."

prompt: "..."

Step 2: Check Templating Compatibility

{{variable}}

{{variable}}

{var}

${var}

{{var}}

{% if %}

{% for %}

{{ var | filter }}

Decision Tree

Contains {% if %}, {% for %}, or filters?
├─ No → Direct migration
└─ Yes → Choose:
    ├─ Option A (RECOMMENDED): Move logic to code, pass pre-computed values
    └─ Option B: Store raw template, compile client-side with Jinja2
        └─ ⚠️ Loses: Playground preview, UI experiments

Simplifying Complex Templates

# Instead of {% if user.is_premium %}...{% endif %} in prompt
# Use {{tier_message}} and compute value in code before compile()

# Instead of {% for tool in tools %}...{% endfor %} in prompt
# Use {{tools_list}} and format the list in code before compile()

Step 3: Propose Structure

Naming Conventions

chat-assistant

ChatAssistant_v2

document-summarizer

prompt1

support/triage

supportTriage

_

_base-personality

shared-personality

Identify Subprompts

• Same text in 2+ prompts
• Represents distinct component (personality, safety rules, format)
• Would need to change together

Variable Extraction

{{user_name}}

{{context}}

{{query}}

{{company_name}}

Step 4: Present Plan to User

Found N prompts across M files:

src/chat.py:
  - System prompt (47 lines) → 'chat-assistant'

src/support/triage.py:
  - Triage prompt (34 lines) → 'support/triage'
    ⚠️ Contains {% if %} - will simplify

Subprompts to extract:
  - '_base-personality' - used by: chat-assistant, support/triage

Variables to add:
  - {{user_name}} - hardcoded in 2 prompts

Proceed?

Step 5: Create Prompts in Langfuse

langfuse.create_prompt()

• name

  : Your chosen name

• prompt

  : Template text (or message array for chat type)

• type

  :

  "text"

  or

  "chat"

• labels

  :

  ["production"]

  (they're already live)

• config

  : Optional model settings

• production

  → All migrated prompts

• staging

  → Add later for testing

• latest

  → Auto-applied by Langfuse

Step 6: Refactor Code

prompt = langfuse.get_prompt("name", label="production")
messages = prompt.compile(var1=value1, var2=value2)

• Always use

  label="production"

  (not

  latest

  ) for stability
• Call

  .compile()

  to substitute variables
• For chat prompts, result is message array ready for API

Step 7: Link Prompts to Traces

Detect Existing Tracing

• @observe()

  decorators

• langfuse.trace()

  calls

• from langfuse.openai import openai

  (instrumented client)

Link Methods

@observe()

langfuse_context.update_current_observation(prompt=prompt)

trace.generation(prompt=prompt, ...)

openai.chat.completions.create(..., langfuse_prompt=prompt)

Verify in UI

1. Go to Traces → select a trace
2. Click on Generation
3. Check Prompt field shows name and version

Step 8: Verify Migration

Checklist

• All prompts created with

  production

  label
• Code fetches with

  label="production"

• Variables compile without errors
• Subprompts resolve correctly
• Application behavior unchanged
• Generations show linked prompt in UI (if tracing)

Common Issues

PromptNotFoundError

{{var}}

{var}

.compile()

Out of Scope

• Prompt engineering (writing better prompts)
• Evaluation setup
• A/B testing workflow
• Non-LLM string templates