---
title: Concepts
sidebarTitle: Concepts
seoTitle: Prompt Management Concepts
description: Core concepts of Langfuse Prompt Management including prompt types, versioning, labels, and configuration.
---

# Core Concepts

This page discusses prompt management concepts and best practices. If you haven't already, check out the [overview](/docs/prompt-management/overview) page on why it's valuable for observability of your application.

Ready to start? Check out the [Get Started guide](/docs/prompt-management/get-started) to create your first prompt.

## The Prompt Object

Langfuse considers a prompt to be a combination of both the instructions for the LLM (this can be a single string or an array of messages) and, optionally, [additional configuration](/docs/prompt-management/features/config) that influences the behavior.

The prompt object also has a couple of attributes for managing different versions, variants, and deployments. This page will guide you through the most important principles of how to use prompts productively.

For detailed information about all prompt object fields and methods, see the [SDK reference documentation](https://langfuse-js-git-main-langfuse.vercel.app/interfaces/_langfuse_core.Prompt.Chat.html).

### Chat vs Text Prompts [#text-vs-chat-prompts]

Langfuse supports two prompt types. The `type` field determines the format and cannot be changed after creation.

**Text prompts** are single strings, ideal for simple use cases or when you only need a system message.

**Chat prompts** are arrays of messages with specific roles (system, user, assistant), useful when you want to manage complete conversation structures, include example exchanges, or handle chat history.

```json filename="Text prompt example"
{
  "name": "movie-critic",
  "type": "text",
  "prompt": "As a movie critic, do you like Dune 2?",
  "version": 1
}
```

```json filename="Chat prompt example"
{
  "name": "movie-critic-chat",
  "type": "chat",
  "prompt": [
    {
      "role": "system",
      "content": "You are a movie critic."
    },
    {
      "role": "user",
      "content": "Do you like Dune 2?"
    }
  ],
  "version": 1
}
```

**When to use chat prompts:** Most applications start with a text prompt. As you build more complex logic that requires managing multiple messages, role-based structures, or chat history, it makes sense to switch to chat prompts. This allows you to manage the complete conversation structure in your prompt management system.

### Dynamic rendering of prompts [#dynamic-rendering-of-prompts]

You can add variables to your prompts that can be dynamically filled out at runtime. There are different types of variables you can use, explained below.

Prompts support three ways to insert dynamic content at runtime:

| Type                                                                          | Use Case                                                                  |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [Variables](/docs/prompt-management/features/variables)                       | Insert dynamic text into messages                                         |
| [Prompt References](/docs/prompt-management/features/composability)           | Reuse prompts across other prompts, avoid duplicating common instructions |
| [Message Placeholders](/docs/prompt-management/features/message-placeholders) | Insert arrays of messages (e.g., chat history)                            |

## Prompt Caching [#prompt-caching]

Langfuse Prompt Management uses cached prompts for 2 main reasons

1. it adds no latency to your application.
2. it removes availability risk.

This means your first few traces after updating a prompt might still be using the old version. If immediate updates are critical for your use case, you can disable caching or configure a shorter TTL (time-to-live).

See the [caching documentation](/docs/prompt-management/features/caching) for details on how caching works and how to configure it.

## Versioning and Labels

Understanding how versions and labels work together is essential for managing prompts in production. They serve different but complementary purposes.

**Versions** provide an immutable history of every prompt change. Each update creates a new version (1, 2, 3...).

**Labels** are pointers to specific versions. Your code would typically point to labels. Common labels include:

- `production` - Default label, used by production applications
- `latest` - Always points to the newest version
- Custom labels - Create labels for staging, testing, tenants, or A/B tests

Learn more about [versioning and labels](/docs/prompt-management/features/prompt-version-control).

```mermaid
graph LR
    subgraph "Prompt Management"
      subgraph "Prompt Version History"
          V1["Version 1"]
          V2["Version 2"]
          V3["Version 3"]
          V4["Version 4"]
          V1 -.-> V2
          V2 -.-> V3
          V3 -.-> V4
      end

      subgraph "Prompt Labels"
        PROD["🏷️ production<br/>(default)"]
        LATEST["🏷️ latest<br/>(auto-updated)"]
        TENANT["🏷️ tenant-b<br/>(custom)"]
      end
    end

    PROD -->|targets| V2
    LATEST -->|targets| V4
    TENANT -->|targets| V4

    SDK["SDK Request<br/>get_prompt('movie-critic')"] -->|resolves via| PROD

    SDK2["SDK Request<br/>get_prompt('movie-critic', label='latest')"] -->|resolves via| LATEST

    class V1,V2,V3,V4 version
    class PROD,LATEST,TENANT label
    class SDK sdk,sdk2
```

### Deployment Workflow

Here's a typical workflow for deploying prompt changes:

1. **Create and test:** Create a new prompt version (automatically gets the `latest` label)
2. **Validate:** Test the new version in your development environment or using the playground
3. **Deploy:** Update the `production` label to point to the new version
4. **Monitor:** Your production application automatically picks up the new version on the next fetch
5. **Rollback if needed:** Simply reassign the `production` label back to a previous version

Since your code references the labels, all this happens without changing code.

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/docs/prompt-management/data-model.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.