CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-langfuse--langfuse-java

Java client for the Langfuse API providing access to observability and analytics features for LLM applications

Overview
Eval results
Files

prompts.mddocs/

Prompts

The Prompts API provides management of prompt templates in both text and chat formats, with support for versioning, labels, and configuration. Prompts can be retrieved by name with optional version or label filters.

Capabilities

PromptsClient

Client for managing prompt templates.

/**
 * Get a prompt by name
 * Optionally filter by version or label
 *
 * @param promptName Name of the prompt
 * @param request Optional version/label filters
 * @param requestOptions Optional request configuration
 */
Prompt get(String promptName);
Prompt get(String promptName, GetPromptRequest request);
Prompt get(String promptName, GetPromptRequest request, RequestOptions requestOptions);

/**
 * List all prompts with metadata
 * Returns prompt names with their versions and labels
 *
 * @param request Optional filters (name, label, tag, date range, pagination)
 * @param requestOptions Optional request configuration
 */
PromptMetaListResponse list();
PromptMetaListResponse list(ListPromptsMetaRequest request);
PromptMetaListResponse list(ListPromptsMetaRequest request, RequestOptions requestOptions);

/**
 * Create a new version for a prompt
 * Creates a new version with the given name
 *
 * @param request Prompt definition (text or chat format)
 * @param requestOptions Optional request configuration
 */
Prompt create(CreatePromptRequest request);
Prompt create(CreatePromptRequest request, RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.prompts.requests.*;
import com.langfuse.client.resources.prompts.types.*;
import java.util.List;

LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .build();

// Get latest version of a prompt
Prompt prompt = client.prompts().get("summarization-prompt");

// Get specific version
GetPromptRequest request = GetPromptRequest.builder()
    .version(2)
    .build();
Prompt v2 = client.prompts().get("summarization-prompt", request);

// Get by label
GetPromptRequest prodRequest = GetPromptRequest.builder()
    .label("production")
    .build();
Prompt prodPrompt = client.prompts().get("summarization-prompt", prodRequest);

// List all prompts
PromptMetaListResponse prompts = client.prompts().list();
for (PromptMeta meta : prompts.getData()) {
    System.out.println(meta.getName() + " v" + meta.getVersion());
}

// Create text prompt
CreateTextPromptRequest textPrompt = CreateTextPromptRequest.builder()
    .name("summarization-prompt")
    .prompt("Summarize the following text: {{text}}")
    .labels(List.of("production"))
    .tags(List.of("summarization", "text"))
    .build();
Prompt created = client.prompts().create(CreatePromptRequest.text(textPrompt));

// Create chat prompt
CreateChatPromptRequest chatPrompt = CreateChatPromptRequest.builder()
    .name("chat-assistant")
    .prompt(List.of(
        ChatMessage.builder()
            .role("system")
            .content("You are a helpful assistant.")
            .build(),
        ChatMessage.builder()
            .role("user")
            .content("{{user_message}}")
            .build()
    ))
    .labels(List.of("production"))
    .build();
Prompt chatCreated = client.prompts().create(CreatePromptRequest.chat(chatPrompt));

PromptVersionClient

Client for updating specific prompt versions.

/**
 * Update labels for a specific prompt version
 *
 * @param name Prompt name
 * @param version Version number
 * @param request Update request with new labels
 * @param requestOptions Optional request configuration
 */
Prompt update(String name, int version, UpdatePromptRequest request);
Prompt update(String name, int version, UpdatePromptRequest request, RequestOptions requestOptions);

Usage Example:

import com.langfuse.client.resources.promptversion.requests.UpdatePromptRequest;

// Update labels for a specific version
UpdatePromptRequest updateRequest = UpdatePromptRequest.builder()
    .newLabels(List.of("production", "verified"))
    .build();

Prompt updated = client.promptVersion()
    .update("summarization-prompt", 2, updateRequest);

Request Types

GetPromptRequest

/**
 * Request parameters for getting a prompt
 * Use version OR label, not both
 */
public final class GetPromptRequest {
    Optional<Integer> getVersion();  // Specific version number
    Optional<String> getLabel();     // Label filter (e.g., "production")

    static Builder builder();
}

ListPromptsMetaRequest

import java.time.OffsetDateTime;

/**
 * Request parameters for listing prompts
 */
public final class ListPromptsMetaRequest {
    Optional<String> getName();                 // Filter by name
    Optional<String> getLabel();                // Filter by label
    Optional<String> getTag();                  // Filter by tag
    Optional<Integer> getPage();                // Page number (default: 1)
    Optional<Integer> getLimit();               // Items per page (default: 50)
    Optional<OffsetDateTime> getFromUpdatedAt(); // Filter from this datetime
    Optional<OffsetDateTime> getToUpdatedAt();   // Filter until this datetime

    static Builder builder();
}

CreatePromptRequest

Union type for creating text or chat prompts.

/**
 * Union type for creating prompts
 * Use factory methods to create text or chat prompts
 */
public final class CreatePromptRequest {
    static CreatePromptRequest text(CreateTextPromptRequest value);
    static CreatePromptRequest chat(CreateChatPromptRequest value);

    <T> T visit(Visitor<T> visitor);
}

CreateTextPromptRequest

/**
 * Request for creating a text prompt
 */
public final class CreateTextPromptRequest {
    String getName();                   // Prompt name
    String getPrompt();                 // Prompt template with {{variables}}
    Optional<Object> getConfig();       // Custom configuration
    Optional<List<String>> getLabels(); // Labels (e.g., "production")
    Optional<List<String>> getTags();   // Tags for categorization
    Optional<String> getCommitMessage(); // Commit message for this version

    static Builder builder();
}

CreateChatPromptRequest

/**
 * Request for creating a chat prompt
 */
public final class CreateChatPromptRequest {
    String getName();                    // Prompt name
    List<ChatMessage> getPrompt();       // Chat messages with roles
    Optional<Object> getConfig();        // Custom configuration
    Optional<List<String>> getLabels();  // Labels (e.g., "production")
    Optional<List<String>> getTags();    // Tags for categorization
    Optional<String> getCommitMessage(); // Commit message for this version

    static Builder builder();
}

UpdatePromptRequest

/**
 * Request for updating prompt labels
 */
public final class UpdatePromptRequest {
    List<String> getNewLabels();  // New labels to set

    static Builder builder();
}

Response Types

Prompt

Union type representing text or chat prompts. Use type checking methods and getters to safely access the underlying prompt type.

/**
 * Union type for prompts
 * Discriminated by type field: "text" or "chat"
 *
 * Usage pattern:
 *   - Check type with isText() or isChat()
 *   - Access with getText() or getChat() which return Optional<T>
 *   - Or use visit() for type-safe pattern matching
 */
public final class Prompt {
    // Factory methods
    static Prompt text(TextPrompt value);
    static Prompt chat(ChatPrompt value);

    // Type checking
    boolean isText();
    boolean isChat();

    // Safe getters (return Optional)
    Optional<TextPrompt> getText();
    Optional<ChatPrompt> getChat();

    // Visitor pattern for type-safe access
    <T> T visit(Visitor<T> visitor);
}

Usage Example:

Prompt prompt = client.prompts().get("prompt-name");

// Option 1: Check type and access
if (prompt.isText()) {
    TextPrompt textPrompt = prompt.getText().orElseThrow();
    System.out.println("Text prompt: " + textPrompt.getName());
    System.out.println("Template: " + textPrompt.getPrompt());
} else if (prompt.isChat()) {
    ChatPrompt chatPrompt = prompt.getChat().orElseThrow();
    System.out.println("Chat prompt: " + chatPrompt.getName());
    for (ChatMessage msg : chatPrompt.getPrompt()) {
        System.out.println(msg.getRole() + ": " + msg.getContent());
    }
}

// Option 2: Using visitor pattern
String promptInfo = prompt.visit(new Prompt.Visitor<String>() {
    @Override
    public String visitText(TextPrompt text) {
        return "Text: " + text.getName();
    }

    @Override
    public String visitChat(ChatPrompt chat) {
        return "Chat: " + chat.getName() + " with " + chat.getPrompt().size() + " messages";
    }

    @Override
    public String _visitUnknown(Object unknownType) {
        return "Unknown prompt type";
    }
});

TextPrompt

/**
 * Text-based prompt
 */
public final class TextPrompt {
    String getName();
    int getVersion();
    String getPrompt();                       // Template string with {{variables}}
    Object getConfig();                       // Custom configuration
    List<String> getLabels();
    List<String> getTags();
    Optional<String> getCommitMessage();      // Commit message
    Optional<Map<String, Object>> getResolutionGraph(); // Dependency resolution graph

    static Builder builder();
}

ChatPrompt

/**
 * Chat-based prompt with messages
 */
public final class ChatPrompt {
    String getName();
    int getVersion();
    List<ChatMessage> getPrompt();            // List of chat messages
    Object getConfig();                       // Custom configuration
    List<String> getLabels();
    List<String> getTags();
    Optional<String> getCommitMessage();      // Commit message
    Optional<Map<String, Object>> getResolutionGraph(); // Dependency resolution graph

    static Builder builder();
}

ChatMessage

/**
 * Individual chat message in a chat prompt
 */
public final class ChatMessage {
    String getRole();     // "system", "user", "assistant", etc.
    String getContent();  // Message content with optional {{variables}}

    static Builder builder();
}

PromptMetaListResponse

/**
 * Paginated list of prompt metadata
 */
public final class PromptMetaListResponse {
    List<PromptMeta> getData();
    MetaResponse getMeta();  // Pagination metadata

    static Builder builder();
}

PromptMeta

/**
 * Metadata for a prompt
 */
public final class PromptMeta {
    String getName();
    int getVersion();
    List<String> getLabels();
    List<String> getTags();

    static Builder builder();
}

Complete Prompt Management Example

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.prompts.requests.*;
import com.langfuse.client.resources.prompts.types.*;
import com.langfuse.client.resources.promptversion.requests.UpdatePromptRequest;
import java.util.List;

public class PromptManagementExample {
    public static void main(String[] args) {
        LangfuseClient client = LangfuseClient.builder()
            .url("https://cloud.langfuse.com")
            .credentials("pk-lf-...", "sk-lf-...")
            .build();

        // 1. Create a text prompt for summarization
        CreateTextPromptRequest textPrompt = CreateTextPromptRequest.builder()
            .name("article-summarizer")
            .prompt("Summarize the following article in {{max_words}} words or less:\n\n{{article_text}}")
            .labels(List.of("development"))
            .tags(List.of("summarization", "articles"))
            .build();

        Prompt created = client.prompts().create(CreatePromptRequest.text(textPrompt));
        System.out.println("Created prompt v" +
            ((TextPrompt) created.visit(Prompt.Visitor.text())).getVersion());

        // 2. Create a chat prompt for customer support
        CreateChatPromptRequest chatPrompt = CreateChatPromptRequest.builder()
            .name("support-bot")
            .prompt(List.of(
                ChatMessage.builder()
                    .role("system")
                    .content("You are a helpful customer support assistant for {{company_name}}. " +
                             "Be professional, empathetic, and concise.")
                    .build(),
                ChatMessage.builder()
                    .role("user")
                    .content("{{customer_query}}")
                    .build()
            ))
            .labels(List.of("development"))
            .tags(List.of("support", "chat"))
            .build();

        Prompt chatCreated = client.prompts().create(CreatePromptRequest.chat(chatPrompt));

        // 3. List all prompts
        ListPromptsMetaRequest listRequest = ListPromptsMetaRequest.builder()
            .limit(10)
            .build();

        PromptMetaListResponse prompts = client.prompts().list(listRequest);
        for (PromptMeta meta : prompts.getData()) {
            System.out.println("Prompt: " + meta.getName() +
                             " v" + meta.getVersion() +
                             " Labels: " + meta.getLabels());
        }

        // 4. Get specific prompt by label
        GetPromptRequest getRequest = GetPromptRequest.builder()
            .label("development")
            .build();

        Prompt devPrompt = client.prompts().get("article-summarizer", getRequest);

        // 5. Update prompt to production
        UpdatePromptRequest updateRequest = UpdatePromptRequest.builder()
            .newLabels(List.of("production", "verified"))
            .build();

        Prompt updated = client.promptVersion().update(
            "article-summarizer",
            1,
            updateRequest
        );

        // 6. Get production version
        GetPromptRequest prodRequest = GetPromptRequest.builder()
            .label("production")
            .build();

        Prompt prodPrompt = client.prompts().get("article-summarizer", prodRequest);

        // Access prompt template
        if (prodPrompt.visit(Prompt.Visitor.text()) != null) {
            TextPrompt textPromptData = prodPrompt.visit(Prompt.Visitor.text());
            System.out.println("Template: " + textPromptData.getPrompt());

            // Use template (replace variables manually or with a template engine)
            String rendered = textPromptData.getPrompt()
                .replace("{{max_words}}", "100")
                .replace("{{article_text}}", "...");
        }
    }
}

Best Practices

  1. Use Labels for Environments: Tag prompts with labels like "development", "staging", "production"
  2. Version Control: Create new versions instead of updating existing ones for reproducibility
  3. Template Variables: Use {{variable_name}} syntax for substitution points
  4. Tags for Organization: Use tags to categorize prompts by use case or feature
  5. Commit Messages: Use commit messages to document changes and rationale for each version
  6. Retrieve by Label: In production, retrieve prompts by label ("production") rather than version number
  7. Test Before Promotion: Test prompts with "development" label before promoting to "production"

Related Documentation

  • Common Types - Shared type definitions
  • Pagination - Pagination utilities

Install with Tessl CLI

npx tessl i tessl/maven-com-langfuse--langfuse-java

docs

client-configuration.md

comments-annotations.md

common-types.md

datasets.md

exceptions.md

health.md

index.md

ingestion.md

media.md

metrics.md

models.md

pagination.md

projects-organizations.md

prompts.md

scim.md

scores.md

sessions.md

traces-observations.md

tile.json