开始使用 Prompt 管理
本指南将带你创建并使用一个 Litefuse 的 prompt。如果你想先了解什么是 prompt 管理以及它为什么重要，可以先看 Prompt 管理概览。关于 prompt 在 Litefuse 中的结构以及背后的工作原理，参见核心概念。
获取 API Key
- 创建 Litefuse 账号 或自托管 Litefuse。
- 在项目设置中创建新的 API 凭证。
配置你的 AI agent
在编辑器的 agent 模式中使用 Litefuse Skill，可以自动创建、编辑和使用 prompt。
什么是 Skill？它是面向 AI 编码 agent 的可复用指令包，开箱即用地为你的 agent 提供 Litefuse 专属工作流和最佳实践。
Install the Litefuse Skill in your coding tool:
Litefuse has a Cursor Plugin that includes the skill automatically.
Claude stores its skills in a .claude/skills directory, you can install skills either globally or per project.
Copy the Litefuse Skill to your local claude skills folder. We’d recommend using a symlink to keep the skill up to date.
You can do this using npm (skills CLI):
npx skills add litefuse/skills --skill "litefuse" --agent "claude-code"Alternatively you can do this manually
- Clone repo somewhere stable
git clone https://github.com/litefuse/skills.git /path/to/litefuse-skills- Make sure Claude skills dir exists (common location)
mkdir -p ~/.claude/skills- Symlink the skill folder
ln -s /path/to/litefuse-skills/skills/litefuse ~/.claude/skills/litefuseCodex stores its skills in a .agents/skills directory, you can install skills either globally or per project. See Codex docs: Where to save skills.
Copy the Litefuse Skill to your local codex skills folder. We’d recommend using a symlink to keep the skill up to date.
You can do this using npm (skills CLI):
npx skills add litefuse/skills --skill "litefuse" --agent "codex"Alternatively you can do this manually
- Clone repo somewhere stable
git clone https://github.com/litefuse/skills.git /path/to/litefuse-skills- Make sure Codex skills dir exists (common location)
mkdir -p ~/.agents/skills- Symlink the skill folder
ln -s /path/to/litefuse-skills/skills/litefuse ~/.agents/skills/litefuseFor other AI coding agents, the skill folder structure is:
<agent-skill-root> depends on your tool. The npm command below installs to the correct location automatically.
For other AI coding agents, install via npm (skills CLI):
npx skills add litefuse/skills --skill "litefuse"If you want to target a specific agent directly:
npx skills add litefuse/skills --skill "litefuse" --agent "<agent-id>"Alternatively you can do this manually
- Clone repo somewhere stable
git clone https://github.com/litefuse/skills.git /path/to/litefuse-skills- Make sure your agent’s skills dir exists
mkdir -p /path/to/<agent-skill-root>/skills- Symlink the skill folder
ln -s /path/to/litefuse-skills/skills/litefuse /path/to/<agent-skill-root>/skills/litefuse创建一个 prompt
开启一个新的 agent 会话，然后让它创建你的 prompt：
"Create a prompt in Litefuse called 'movie-critic' that takes a movie name
and critic level as variables."或者让它把现有的 prompt 迁移到 Litefuse：
"Migrate the hardcoded prompts in this codebase to Litefuse."在代码中使用 prompt
如果还没开启新的 agent 会话，先开一个，然后让它接入 prompt 获取逻辑：
"Fetch the 'movie-critic' prompt, production version, from Litefuse
and use it in my application."获取 API Key
- 创建 Litefuse 账号 或自托管 Litefuse。
- 在项目设置中创建新的 API 凭证。
创建一个 prompt
Use the Litefuse UI to create a new prompt or update an existing one. You’ll need to select the prompt type, you can’t change this afterwards.
pip install langfuseAdd your Litefuse credentials as environment variables so the SDK knows which project to create the prompt in.
LANGFUSE_SECRET_KEY = "sk-lf-..."
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_BASE_URL = "https://litefuse.cloud"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"] # optionally, directly promote to production
)
# 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"] # optionally, directly promote to production
)If you already have a prompt with the same name, the prompt will be added as a new version.
npm i @langfuse/clientAdd your Litefuse credentials as environment variables so the SDK knows which project to create the prompt in.
LANGFUSE_SECRET_KEY = "sk-lf-..."
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_BASE_URL = "https://litefuse.cloud"import { LangfuseClient } from "@langfuse/client";
const langfuse = new LangfuseClient();Use the JS/TS SDK to create a new prompt or update an existing one.
// Create a text prompt
await langfuse.prompt.create({
name: "movie-critic",
type: "text",
prompt: "As a {{criticlevel}} critic, do you like {{movie}}?",
labels: ["production"] // optionally, directly promote to production
});
// Create a chat prompt
await langfuse.prompt.create({
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"] // optionally, directly promote to production
});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 -X POST "https://litefuse.cloud/api/public/v2/prompts" \
-u "your-public-key:your-secret-key" \
-H "Content-Type: application/json" \
-d '{
"type": "chat",
"name": "movie-critic",
"prompt": [
{ "role": "system", "content": "You are an {{criticlevel}} movie critic" },
{ "role": "user", "content": "Do you like {{movie}}?" }
]
}'
If you have prompts in your existing codebase, you can migrate them to Litefuse programmatically.
Using the Litefuse Skill
- Install the Litefuse Skill:
# Cursor plugin
/add-plugin litefuse
# skills CLI
npx skills add litefuse/skills --skill "litefuse"
# Manual: clone and symlink
git clone https://github.com/litefuse/skills.git /path/to/litefuse-skills
ln -s /path/to/litefuse-skills/skills/litefuse ~/.skills/litefuse- Ask the agent to migrate your prompts:
Migrate the hardcoded prompts in this codebase to Litefuse prompt management.Using the API
You can write a script that reads your existing prompts and creates them in Litefuse using the Public API. This is ideal for bulk migrations or CI/CD integration.
Things to look out for
- Litefuse uses a specific syntax for variables, prompt references, and message placeholders. Make sure to update your prompts to use the correct format, if you want to use Litefuse’s dynamic rendering capabilities.
在代码中使用 prompt
At runtime, you can fetch the prompt from Litefuse. We recommend using the production label to fetch the version intentionally chosen for production. Learn more about control (versions/labels) here.
from langfuse import get_client
# Initialize Langfuse client
langfuse = get_client()Below are code examples for both a text type prompt and a chat type prompt. Learn more about prompt types here.
Text prompt
# By default, the production version is fetched.
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
# By default, the production version of a chat prompt is fetched.
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?"}]import { LangfuseClient } from "@langfuse/client";
// Initialize the Langfuse client
const langfuse = new LangfuseClient();Below are code examples for both a text type prompt and a chat type prompt. Learn more about prompt types here.
Text prompt
// By default, the production version of a text prompt is fetched.
const prompt = await langfuse.prompt.get("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
// By default, the production version of a chat prompt is fetched.
const chatPrompt = await langfuse.prompt.get("movie-critic-chat", {
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?"}]Use the Public API to fetch a prompt at runtime. By default, the prompt labeled production is returned.
curl "https://litefuse.cloud/api/public/v2/prompts/movie-critic?label=production" \
-u "your-public-key:your-secret-key"For fetching a specific version instead of a label:
curl "https://litefuse.cloud/api/public/v2/prompts/movie-critic?version=1" \
-u "your-public-key:your-secret-key"pip install langfuse openaiimport openai
from langfuse import get_client
# Initialize Langfuse client
langfuse = get_client()Below are code examples for both a text type prompt and a chat type prompt. Learn more about prompt types here.
Text prompt
# By default, the production version of a text prompt is fetched.
prompt = langfuse.get_prompt("movie-critic")
# Compile the prompt with variables
compiled_prompt = prompt.compile(criticlevel="expert", movie="Dune 2")
# Use with OpenAI - prompt is a string
completion = openai.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": compiled_prompt}]
)Chat prompt
# By default, the production version of a chat prompt is fetched.
chat_prompt = langfuse.get_prompt("movie-critic-chat", type="chat")
# Compile the prompt with variables - returns a list of message dicts
compiled_chat_prompt = chat_prompt.compile(criticlevel="expert", movie="Dune 2")
# Use with OpenAI - prompt is a list of messages
completion = openai.chat.completions.create(
model="gpt-4o",
messages=compiled_chat_prompt
)Example notebook
npm install @langfuse/openai openaiimport { observeOpenAI } from "@langfuse/openai";
import { LangfuseClient } from "@langfuse/client";
import OpenAI from "openai";
// Initialize Langfuse client
const langfuse = new LangfuseClient();
// Wrap OpenAI client
const openai = observeOpenAI(new OpenAI());Below are code examples for both a text type prompt and a chat type prompt. Learn more about prompt types here.
Text prompt
// By default, the production version of a text prompt is fetched.
const prompt = await langfuse.prompt.get("movie-critic", {
type: "text",
});
// Compile the prompt with variables
const compiledPrompt = prompt.compile({
criticlevel: "expert",
movie: "Dune 2",
});
// Use with OpenAI - prompt is a string
const completion = await openai.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: compiledPrompt }],
});Chat prompt
// By default, the production version of a chat prompt is fetched.
const chatPrompt = await langfuse.prompt.get("movie-critic-chat", {
type: "chat",
});
// Compile the prompt with variables - returns an array of messages
const compiledChatPrompt = chatPrompt.compile({
criticlevel: "expert",
movie: "Dune 2",
});
// Use with OpenAI - prompt is an array of messages
const completion = await openai.chat.completions.create({
model: "gpt-4o",
messages: compiledChatPrompt,
});from langfuse import Langfuse
from langchain_core.prompts import ChatPromptTemplate
# Initialize Langfuse client
langfuse = Langfuse()Below are code examples for both a text type prompt and a chat type prompt. Learn more about prompt types here.
These examples contain variables. As Litefuse and Langchain process input variables of prompt templates differently ({} instead of {{}}), we provide the prompt.get_langchain_prompt() method to transform the Litefuse 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.
Text prompt
# By default, the production version of a text prompt is fetched.
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
# By default, the production version of a chat prompt is fetched.
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())Example notebook
import { LangfuseClient } from "@langfuse/client";
import { ChatPromptTemplate } from "@langchain/core/prompts";
const langfuse = new LangfuseClient();Below are code examples for both a text type prompt and a chat type prompt. Learn more about prompt types here.
These examples contain variables. As Litefuse and Langchain process input variables of prompt templates differently ({} instead of {{}}), we provide the prompt.get_langchain_prompt() method to transform the Litefuse 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.
Text prompt
// Get current `production` version
const langfusePrompt = await langfuse.prompt.get("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.prompt.get(
"movie-critic-chat",
{ type: "chat" }
);
// Example using ChatPromptTemplate
const promptTemplate = ChatPromptTemplate.fromMessages(
langfusePrompt.getLangchainPrompt().map((msg) => [msg.role, msg.content])
);Example notebook
Use Litefuse Prompt Management with the Vercel AI SDK.
npm install @langfuse/client aiimport { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { LangfuseClient } from "@langfuse/client";
// Initialize Langfuse client
const langfuse = new LangfuseClient();Below are code examples for both a text type prompt and a chat type prompt. Learn more about prompt types here.
Text prompt
// By default, the production version of a text prompt is fetched.
const prompt = await langfuse.prompt.get("movie-critic", {
type: "text",
});
// Compile the prompt with variables
const compiledPrompt = prompt.compile({
criticlevel: "expert",
movie: "Dune 2",
});
// Use with Vercel AI SDK
const result = await generateText({
model: openai("gpt-4o"),
prompt: compiledPrompt,
experimental_telemetry: {
isEnabled: true,
},
});Chat prompt
// By default, the production version of a chat prompt is fetched.
const chatPrompt = await langfuse.prompt.get("movie-critic-chat", {
type: "chat",
});
// Compile the prompt with variables - returns an array of messages
const compiledChatPrompt = chatPrompt.compile({
criticlevel: "expert",
movie: "Dune 2",
});
// Use with Vercel AI SDK
const result = await generateText({
model: openai("gpt-4o"),
messages: compiledChatPrompt,
experimental_telemetry: {
isEnabled: true,
},
});Not seeing your latest version? This might be because of the caching behavior. See prompt caching for more details.
没有看到预期结果？
后续步骤
现在你已经使用过第一个 prompt 了，建议接下来做这两件事，更充分地用好 Litefuse Prompt 管理：
- 将 prompt 关联到 trace，按 prompt 版本分析效果
- 使用版本管理和标签管理跨环境的部署
想找特定主题？查看 Features 下针对具体主题的指南。