Chat Prompt Configuration#

Chat prompts in Langfuse are structured as an ordered list of typed messages. Each message is either a content message (with a role and content string) or a placeholder message (a named slot for dynamically injected message sequences at compile time). The core type definitions and Zod schemas live in packages/shared/src/server/llm/types.ts.

Message Types#

ChatMessageType enum#

The ChatMessageType enum defines all message variants:

Each standard role has its own schema (e.g., SystemMessageSchema, UserMessageSchema); all require a matching type literal plus a content string.

ChatMessageSchema union#

ChatMessageSchema is a discriminated union covering the standard roles, plus a fallback branch that accepts {role: string, content: any} and tags the result as PublicAPICreated. PlaceholderMessage is intentionally excluded from this union; it is added separately via ChatMessageWithId.

Prompt-level schemas#

PromptChatMessageSchema is the union used when storing or validating a prompt's message list — it accepts either {role, content} or a PlaceholderMessage. PromptChatMessageListSchema is z.array(PromptChatMessageSchema) and is what PromptContentSchema branches on for chat prompts 1.

Placeholder Messages#

Schema and naming constraints#

PlaceholderMessageSchema:

{ type: "placeholder", name: string }

The name field must match /^[a-zA-Z][a-zA-Z0-9_]*$/ — i.e., start with an ASCII letter, followed by zero or more alphanumeric characters or underscores. No spaces, no leading digits, no Unicode beyond ASCII. 2

Note: this is more restrictive than the VARIABLE_REGEX used for {{variable}} interpolation, which uses Unicode property escapes (\p{L}, \p{N}) and allows non-ASCII letters. See stringChecks.ts.

Compile-time expansion#

extractPlaceholderNames() in compileChatMessages.ts filters an array of prompt messages for entries with type === "placeholder" and returns their names. This drives downstream injection of runtime message sequences into placeholder slots.

Variable Extraction and Collision Detection#

Prompt content uses mustache syntax ({{variable_name}}) for text interpolation. The shared extractVariables() function parses these with MUSTACHE_REGEX (/{{([^{}]*)}}+/g) and filters results through VARIABLE_REGEX.

Variable names and placeholder names must not overlap. Server-side, createPrompt.ts enforces this on every write:

1. extractChatVariableAndPlaceholderNames() collects variables from each message's content field and placeholder names from the message list.
2. If any variable name appears in the placeholder list, createPrompt throws an InvalidRequestError listing the conflicting names.

Frontend Validation#

The UI form schema at web/src/features/prompts/components/NewPromptForm/validation.ts adds two refinements on the chatPrompt array 3:

1. Every message with type === "placeholder" must pass PlaceholderMessageSchema.safeParse().
2. Every non-placeholder message must have a non-empty content string.

MCP Integration#

The MCP createChatPrompt tool (PR #13323) added placeholder message support via a two-schema design required by MCP client limitations with oneOf/anyOf in array items:

• Base schema: flat, permissive object with all fields optional (for MCP client display).
• Input schema: enforces the content-vs-placeholder contract using .superRefine(), re-parsing with PromptChatMessageSchema before passing to createPromptAction. The variable-placeholder collision check runs at the action layer, same as all other entry points.

Key Source Files#