Implementation:Langfuse Langfuse CreatePrompt

Knowledge Sources	Langfuse
Domains	Prompt Management, Version Control
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete tool for creating new prompt versions with automatic version numbering, dependency validation, label management, and cache invalidation provided by Langfuse.

Description

The createPrompt function is the primary write-path entry point for prompt authoring in Langfuse. When invoked, it performs the following orchestration:

1. Fetches the latest existing version of the prompt by name within the project to determine the next version number and to inherit tags if none are provided.
2. Validates type consistency: If previous versions exist, the new version must match their prompt type (Text or Chat). Mixing types is rejected with an InvalidRequestError.
3. Validates variable-placeholder disjointness (Chat type only): Extracts both text variable names ({{var}} patterns) and placeholder names from chat messages and ensures they do not overlap.
4. Parses dependency tags: Scans the prompt content for @@@langfusePrompt:...@@@ references and extracts them as structured dependency descriptors.
5. Validates the dependency graph: Calls buildAndResolvePromptGraph to ensure all referenced prompts exist, are of type "text", do not form cycles, and do not exceed the maximum nesting depth of 5.
6. Prepares labels: Appends the "latest" label to the provided labels (newly created prompts always carry "latest"). Removes these labels from all previous versions since labels must be unique across versions.
7. Synchronizes tags: If the provided tags differ from the latest version's tags, propagates the new tag set to all existing versions.
8. Locks and invalidates the Redis cache for the prompt name before the database write to prevent stale reads.
9. Executes a database transaction that atomically creates the prompt record and all dependency records.
10. Unlocks the cache after the transaction commits.
11. Fires event sourcing events for both the newly created prompt and any previously existing versions that were modified (label removal, tag updates).

Usage

Import and call this function from tRPC mutation handlers or public API routes when a user creates a new prompt version through the Langfuse web UI or the REST API. It is also used internally by the prompt duplication flow (though that has its own dedicated function).

Code Reference

Source Location

• Repository: langfuse
• File: web/src/features/prompts/server/actions/createPrompt.ts
• Lines: 60-221

Signature

export const createPrompt = async ({
  projectId,
  name,
  prompt,
  type = PromptType.Text,
  labels = [],
  config,
  createdBy,
  prisma,
  tags,
  commitMessage,
}: CreatePromptParams) => Promise<Prompt>

Import

import { createPrompt } from "@/src/features/prompts/server/actions/createPrompt";

I/O Contract

Inputs

Name	Type	Required	Description
projectId	string	Yes	The ID of the project that owns this prompt.
name	string	Yes	The prompt name. All versions of a prompt share this name. Maximum 255 characters; cannot contain the pipe character.
prompt	string | any[]	Yes	The prompt content. A plain string for Text type prompts, or an array of chat message objects for Chat type prompts.
type	PromptType	No	Either "text" or "chat". Defaults to PromptType.Text. Must match the type of any existing versions with the same name.
labels	string[]	No	Labels to assign to this version (e.g., "production", "staging"). The "latest" label is always added automatically. Labels are removed from previous versions. Each label: max 36 chars, lowercase alphanumeric with underscores, hyphens, or periods.
config	unknown	No	Arbitrary JSON configuration associated with this prompt version (e.g., model parameters, temperature). Validated through jsonSchema.parse.
createdBy	string	Yes	Identifier of the user or API key that created this prompt version.
prisma	PrismaClient	Yes	The Prisma client instance for database operations.
tags	string[]	No	Tags for organizational grouping. If omitted, tags are inherited from the latest existing version. Tags are synchronized across all versions of the same prompt name.
commitMessage	string	No	Optional human-readable description of what changed in this version.

Outputs

Name	Type	Description
prompt	Prompt	The created Prisma Prompt record, including all fields: id (UUID v4), projectId, name, version (auto-incremented), prompt (content), type, labels, tags, config, createdBy, commitMessage, createdAt, updatedAt.

Usage Examples

Create a Text Prompt

const newPrompt = await createPrompt({
  projectId: "proj_abc123",
  name: "summarization-system",
  prompt: "You are a helpful assistant that summarizes text. User input: {{text}}",
  type: PromptType.Text,
  labels: ["production"],
  config: { temperature: 0.3 },
  createdBy: "user_xyz",
  prisma: prismaClient,
  tags: ["summarization", "gpt-4"],
  commitMessage: "Improved instruction clarity for summarization",
});
// newPrompt.version === 1 (if first version) or latestVersion + 1
// newPrompt.labels === ["production", "latest"]

Create a Chat Prompt with Dependencies

const chatPrompt = await createPrompt({
  projectId: "proj_abc123",
  name: "customer-support-chat",
  prompt: [
    { role: "system", content: "@@@langfusePrompt:name=base-persona|label=production@@@ Answer customer questions." },
    { role: "user", content: "{{user_question}}" },
  ],
  type: PromptType.Chat,
  labels: [],
  createdBy: "user_xyz",
  prisma: prismaClient,
});
// The dependency on "base-persona" (production label) is automatically parsed and validated.
// newPrompt.labels === ["latest"] (always added)

Create a New Version Inheriting Tags

// If the previous version had tags: ["rag", "production-ready"]
// and no tags parameter is provided, the new version inherits them.
const v2 = await createPrompt({
  projectId: "proj_abc123",
  name: "summarization-system",
  prompt: "Updated instructions: {{text}}",
  createdBy: "user_xyz",
  prisma: prismaClient,
  // tags is omitted: inherits from latest version
});
// v2.tags === ["rag", "production-ready"]

Related Pages

Implements Principle

• Principle:Langfuse_Langfuse_Prompt_Authoring_and_Versioning
• Environment:Langfuse_Langfuse_PostgreSQL_17