Get Started with Prompt Management

This quickstart helps you to create your first prompt and use it in your application.

Get API keys

Create Langfuse account or self-host Langfuse.
Create new API credentials in the project settings.

Create a prompt

Use the Langfuse UI to create a new prompt or update an existing one.

Use the Python SDK to create a new prompt or update an existing one.

# Create a text prompt
langfuse.create_prompt(
    name="movie-critic",
    type="text",
    prompt="As a {{criticlevel}} movie critic, do you like {{movie}}?",
    labels=["production"],  # directly promote to production
    config={
        "model": "gpt-4o",
        "temperature": 0.7,
        "supported_languages": ["en", "fr"],
    },  # optionally, add configs (e.g. model parameters or model tools) or tags
)
 
# Create a chat prompt
langfuse.create_prompt(
    name="movie-critic-chat",
    type="chat",
    prompt=[
      { "role": "system", "content": "You are an {{criticlevel}} movie critic" },
      { "role": "user", "content": "Do you like {{movie}}?" },
    ],
    labels=["production"],  # directly promote to production
    config={
        "model": "gpt-4o",
        "temperature": 0.7,
        "supported_languages": ["en", "fr"],
    },  # optionally, add configs (e.g. model parameters or model tools) or tags
)

If you already have a prompt with the same name, the prompt will be added as a new version.

Use the JS/TS SDK to create a new prompt or update an existing one.

// Create a text prompt
await langfuse.createPrompt({
  name: "movie-critic",
  type: "text",
  prompt: "As a {{criticlevel}} critic, do you like {{movie}}?",
  labels: ["production"], // directly promote to production
  config: {
    model: "gpt-4o",
    temperature: 0.7,
    supported_languages: ["en", "fr"],
  }, // optionally, add configs (e.g. model parameters or model tools) or tags
});
 
// Create a chat prompt
await langfuse.createPrompt({
  name: "movie-critic-chat",
  type: "chat",
  prompt: [
    { role: "system", content: "You are an {{criticlevel}} movie critic" },
    { role: "user", content: "Do you like {{movie}}?" },
  ],
  labels: ["production"], // directly promote to production
  config: {
    model: "gpt-4o",
    temperature: 0.7,
    supported_languages: ["en", "fr"],
  }, // optionally, add configs (e.g. model parameters or model tools) or tags
});

If you already have a prompt with the same name, the prompt will be added as a new version.

Use the Public API to create a new prompt or update an existing one.

curl https://cloud.langfuse.com/api/public/v2/prompts \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "chat",
  "name": "",
  "prompt": [
    {
      "type": "chatmessage",
      "role": "",
      "content": ""
    }
  ],
  "config": null,
  "labels": [
    ""
  ],
  "tags": [
    ""
  ],
  "commitMessage": null
}'

API Reference

Use prompt

At runtime, you can fetch the latest production version from Langfuse. Learn more about control (versions/labels) here.

from langfuse import get_client
 
# Initialize Langfuse client
langfuse = get_client()

Text prompt

# Get current `production` version of a text prompt
prompt = langfuse.get_prompt("movie-critic")
 
# Insert variables into prompt template
compiled_prompt = prompt.compile(criticlevel="expert", movie="Dune 2")
# -> "As an expert movie critic, do you like Dune 2?"

Chat prompt

# Get current `production` version of a chat prompt
chat_prompt = langfuse.get_prompt("movie-critic-chat", type="chat") # type arg infers the prompt type (default is 'text')
 
# Insert variables into chat prompt template
compiled_chat_prompt = chat_prompt.compile(criticlevel="expert", movie="Dune 2")
# -> [{"role": "system", "content": "You are an expert movie critic"}, {"role": "user", "content": "Do you like Dune 2?"}]

Optional parameters

# Get specific version
prompt = langfuse.get_prompt("movie-critic", version=1)
 
# Get specific label
prompt = langfuse.get_prompt("movie-critic", label="staging")
 
# Get latest prompt version. The 'latest' label is automatically maintained by Langfuse.
prompt = langfuse.get_prompt("movie-critic", label="latest")

Attributes

# Raw prompt including {{variables}}. For chat prompts, this is a list of chat messages.
prompt.prompt
 
# Config object
prompt.config

import { Langfuse } from "langfuse";
 
// Iniitialize the Langfuse client
const langfuse = new Langfuse();

Text prompt

// Get current `production` version
const prompt = await langfuse.getPrompt("movie-critic");
 
// Insert variables into prompt template
const compiledPrompt = prompt.compile({
  criticlevel: "expert",
  movie: "Dune 2",
});
// -> "As an expert movie critic, do you like Dune 2?"

Chat prompt

// Get current `production` version of a chat prompt
const chatPrompt = await langfuse.getPrompt("movie-critic-chat", undefined, {
  type: "chat",
}); // type option infers the prompt type (default is 'text')
 
// Insert variables into chat prompt template
const compiledChatPrompt = chatPrompt.compile({
  criticlevel: "expert",
  movie: "Dune 2",
});
// -> [{"role": "system", "content": "You are an expert movie critic"}, {"role": "user", "content": "Do you like Dune 2?"}]

Optional parameters

// Get specific version of a prompt (here version 1)
const prompt = await langfuse.getPrompt("movie-critic", 1);
 
// Get specific label
const prompt = await langfuse.getPrompt("movie-critic", undefined, {
  label: "staging",
});
 
// Get latest prompt version. The 'latest' label is automatically maintained by Langfuse.
const prompt = await langfuse.getPrompt("movie-critic", undefined, {
  label: "latest",
});

Attributes

// Raw prompt including {{variables}}. For chat prompts, this is a list of chat messages.
prompt.prompt;
 
// Config object
prompt.config;

As Langfuse and Langchain process input variables of prompt templates differently ({} instead of {{}}), we provide the prompt.get_langchain_prompt() method to transform the Langfuse prompt into a string that can be used with Langchain’s PromptTemplate. You can pass optional keyword arguments to prompt.get_langchain_prompt(**kwargs) in order to precompile some variables and handle the others with Langchain’s PromptTemplate.

from langfuse import Langfuse
from langchain_core.prompts import ChatPromptTemplate
 
# Initialize Langfuse client
langfuse = Langfuse()

Text prompt

# Get current `production` version
langfuse_prompt = langfuse.get_prompt("movie-critic")
 
# Example using ChatPromptTemplate
langchain_prompt = ChatPromptTemplate.from_template(langfuse_prompt.get_langchain_prompt())
 
# Example using ChatPromptTemplate with pre-compiled variables.
langchain_prompt = ChatPromptTemplate.from_template(langfuse_prompt.get_langchain_prompt(strictness='tough'))

Chat prompt

# Get current `production` version of a chat prompt
langfuse_prompt = langfuse.get_prompt("movie-critic-chat", type="chat")
 
# Create a Langchain ChatPromptTemplate from the Langfuse prompt chat messages
langchain_prompt = ChatPromptTemplate.from_messages(langfuse_prompt.get_langchain_prompt())

Optional parameters

# Get specific version
prompt = langfuse.get_prompt("movie-critic", version=1)
 
# Get specific label
prompt = langfuse.get_prompt("movie-critic", label="staging")
 
# Get latest prompt version. The 'latest' label is automatically maintained by Langfuse.
prompt = langfuse.get_prompt("movie-critic", label="latest")

Attributes

# Raw prompt including {{variables}}. For chat prompts, this is a list of chat messages.
prompt.prompt
 
# Config object
prompt.config

As Langfuse and Langchain process input variables of prompt templates differently ({} instead of {{}}), we provide the prompt.getLangchainPrompt() method to transform the Langfuse prompt into a string that can be used with Langchain’s PromptTemplate.

import { Langfuse } from "langfuse";
import { ChatPromptTemplate } from "@langchain/core/prompts";
 
const langfuse = new Langfuse();

Text prompt

// Get current `production` version
const langfusePrompt = await langfuse.getPrompt("movie-critic");
 
// Example using ChatPromptTemplate
const promptTemplate = PromptTemplate.fromTemplate(
  langfusePrompt.getLangchainPrompt()
);

Chat prompt

// Get current `production` version of a chat prompt
const langfusePrompt = await langfuse.getPrompt(
  "movie-critic-chat",
  undefined,
  { type: "chat" }
);
 
// Example using ChatPromptTemplate
const promptTemplate = ChatPromptTemplate.fromMessages(
  langfusePrompt.getLangchainPrompt().map((msg) => [msg.role, msg.content])
);

Optional parameters

// Get specific version of a prompt (here version 1)
const prompt = await langfuse.getPrompt("movie-critic", 1);
 
// Get specific label
const prompt = await langfuse.getPrompt("movie-critic", undefined, {
  label: "staging",
});
 
// Get latest prompt version. The 'latest' label is automatically maintained by Langfuse.
const prompt = await langfuse.getPrompt("movie-critic", undefined, {
  label: "latest",
});

Attributes

// Raw prompt including {{variables}}. For chat prompts, this is a list of chat messages.
prompt.prompt;
 
// Config object
prompt.config;

Link with Langfuse Tracing (optional)

You can link the prompt to the LLM generation span that used the prompt. This linkage enables tracking of metrics by prompt version and name directly in the Langfuse UI and see which prompt performed best.

Decorators

from langfuse import observe, get_client
 
langfuse = get_client()
 
@observe(as_type="generation")
def nested_generation():
    prompt = langfuse.get_prompt("movie-critic")
 
    langfuse.update_current_generation(
        prompt=prompt,
    )
 
@observe()
def main():
  nested_generation()
 
main()

Context Managers

from langfuse import get_client
 
langfuse = get_client()
 
prompt = langfuse.get_prompt("movie-critic")
 
with langfuse.start_as_current_generation(
    name="movie-generation",
    model="gpt-4o",
    prompt=prompt
) as generation:
    # Your LLM call here
    generation.update(output="LLM response")

langfuse.generation({
    ...
+   prompt: prompt
    ...
})

from langfuse.openai import openai
from langfuse import get_client
 
langfuse = get_client()
 
prompt = langfuse.get_prompt("calculator")
 
openai.chat.completions.create(
  model="gpt-4o",
  messages=[
    {"role": "system", "content": prompt.compile(base=10)},
    {"role": "user", "content": "1 + 1 = "}],
  langfuse_prompt=prompt
)

import { observeOpenAI } from "langfuse";
import OpenAI from "openai";
 
const langfusePrompt = await langfuse.getPrompt("prompt-name"); // Fetch a previously created prompt
 
const res = await observeOpenAI(new OpenAI(), {
  langfusePrompt,
}).completions.create({
  prompt: langfusePrompt.prompt,
  model: "gpt-4o",
  max_tokens: 300,
});

from langfuse import get_client
from langfuse.langchain import CallbackHandler
from langchain_core.prompts import ChatPromptTemplate, PromptTemplate
from langchain_openai import ChatOpenAI, OpenAI
 
langfuse = get_client()
 
# Initialize the Langfuse handler
langfuse_handler = CallbackHandler()

Text prompts

langfuse_text_prompt = langfuse.get_prompt("movie-critic")
 
## Pass the langfuse_text_prompt to the PromptTemplate as metadata to link it to generations that use it
langchain_text_prompt = PromptTemplate.from_template(
    langfuse_text_prompt.get_langchain_prompt(),
    metadata={"langfuse_prompt": langfuse_text_prompt},
)
 
## Use the text prompt in a Langchain chain
llm = OpenAI()
completion_chain = langchain_text_prompt | llm
 
completion_chain.invoke({"movie": "Dune 2", "criticlevel": "expert"}, config={"callbacks": [langfuse_handler]})

Chat prompts

langfuse_chat_prompt = langfuse.get_prompt("movie-critic-chat", type="chat")
 
## Manually set the metadata on the langchain_chat_prompt to link it to generations that use it
langchain_chat_prompt = ChatPromptTemplate.from_messages(
    langfuse_chat_prompt.get_langchain_prompt()
)
 
langchain_chat_prompt.metadata = {"langfuse_prompt": langfuse_chat_prompt}
 
## or use the ChatPromptTemplate constructor directly.
## Note that using ChatPromptTemplate.from_template led to issues in the past
## See: https://github.com/langfuse/langfuse/issues/5374
langchain_chat_prompt = ChatPromptTemplate(
    langfuse_chat_prompt.get_langchain_prompt(),
    metadata={"langfuse_prompt": langfuse_chat_prompt}
)
 
## Use the chat prompt in a Langchain chain
chat_llm = ChatOpenAI()
chat_chain = langchain_chat_prompt | chat_llm
 
chat_chain.invoke({"movie": "Dune 2", "criticlevel": "expert"}, config={"callbacks": [langfuse_handler]})

If you use the with_config method on the PromptTemplate to create a new Langchain Runnable with updated config, please make sure to pass the langfuse_prompt in the metadata key as well.

Set the langfuse_prompt metadata key only on PromptTemplates and not additionally on the LLM calls or elsewhere in your chains.

import { Langfuse } from "langfuse";
import { PromptTemplate } from "@langchain/core/prompts";
import { ChatOpenAI, OpenAI } from "@langchain/openai";
import { CallbackHandler } from "langfuse-langchain";
 
const langfuseHandler = new CallbackHandler({
  secretKey: "sk-lf-...",
  publicKey: "pk-lf-...",
  baseUrl: "https://cloud.langfuse.com", // 🇪🇺 EU region
  // baseUrl: "https://us.cloud.langfuse.com", // 🇺🇸 US region
});
 
const langfuse = new Langfuse();

Text prompts

const langfuseTextPrompt = await langfuse.getPrompt("movie-critic"); // Fetch a previously created text prompt
 
// Pass the langfuseTextPrompt to the PromptTemplate as metadata to link it to generations that use it
const langchainTextPrompt = PromptTemplate.fromTemplate(
  langfuseTextPrompt.getLangchainPrompt()
).withConfig({
  metadata: { langfusePrompt: langfuseTextPrompt },
});
 
const model = new OpenAI();
const chain = langchainTextPrompt.pipe(model);
 
await chain.invoke({ movie: "Dune 2", criticlevel: "expert" }, { callbacks: [langfuseHandler] });

Chat prompts

const langfuseChatPrompt = await langfuse.getPrompt(
  "movie-critic-chat",
  undefined,
  {
    type: "chat",
  }
); // type option infers the prompt type as chat (default is 'text')
 
const langchainChatPrompt = ChatPromptTemplate.fromMessages(
  langfuseChatPrompt.getLangchainPrompt().map((m) => [m.role, m.content])
).withConfig({
  metadata: { langfusePrompt: langfuseChatPrompt },
});
 
const chatModel = new ChatOpenAI();
const chatChain = langchainChatPrompt.pipe(chatModel);
 
await chatChain.invoke({ movie: "Dune 2", criticlevel: "expert" }, { callbacks: [langfuseHandler] });

Link Langfuse prompts to Vercel AI SDK generations by setting the langfusePrompt property in the metadata field:

import { generateText } from "ai";
import { Langfuse } from "langfuse";
 
const langfuse = new Langfuse();
 
const fetchedPrompt = await langfuse.getPrompt("my-prompt");
 
const result = await generateText({
  model: openai("gpt-4o"),
  prompt: fetchedPrompt.prompt,
  experimental_telemetry: {
    isEnabled: true,
    metadata: {
      langfusePrompt: fetchedPrompt.toJSON(),
    },
  },
});

If a fallback prompt is used, no link will be created.

End-to-end examples

The following example notebooks include end-to-end examples of prompt management:

Example OpenAI Functions Example Langchain (Python)Example Langchain (JS/TS)

We also used Prompt Management for our Docs Q&A Chatbot and traced it with Langfuse. You can get view-only access to the project by signing up to the public demo.

Overview Data Model

Was this page helpful?

Support