MLflow Prompt Registry: Prompt Versioning, Aliases and Lifecycle

1.The Prompt Registry's Git-like model

Prompts written as string literals inside application code are hard to track. You can't easily see which wording is running in production, you can't roll back without a code release, and a domain expert can't make a change without an engineer. The MLflow Prompt Registry fixes this. It is a central store for prompt templates that versions every change, lets you reference prompts by name, and lets non-engineers edit prompts through the UI. Because the registry is integrated with Unity Catalog, access control and audit trails come from the same governance layer as your tables and models. The feature is currently in Beta, and workspace admins enable it from the Previews page.

Every prompt is stored in a Unity Catalog schema, so its full name has three parts, such as main.default.summarization_prompt. Prompt names can contain only letters, numbers, hyphens, underscores and dots. To use the SDK you install mlflow[databricks]. The overview page asks for version 3.1.0 or later, and the create-and-edit guide asks for 3.14.0 or later. To avoid typing the schema every time, you can tag an MLflow experiment with mlflow.promptRegistryLocation set to catalog.schema. SDKs and tools then infer the schema for that experiment automatically.

Sources12

2.Registering prompts and creating new versions

A single function, mlflow.genai.register_prompt(), creates a prompt and also adds every later version. The first call with a new name creates version 1. Each later call with the same name creates the next version. commit_message and tags are optional, but they act as your change log: the commit message records why a version exists, and tags such as author or use_case let you filter later. Template variables use double braces, for example {{content}}, and you fill them in at runtime with prompt.format(...). In the UI, you open your experiment's Prompts tab, choose a target schema and select a prompt type. Text is a single template, and Chat is a list of role-based messages.

Suppose you want better instructions in an existing prompt. Versions are immutable, so you can't open version 1 and edit it. You call register_prompt() again under the existing name with the new template, and MLflow stores it as version 2. Version 1 stays unchanged, which is what makes rollback possible.

# Register a new version
updated_prompt = mlflow.genai.register_prompt(
    name=f"{uc_schema}.{prompt_name}",
    template=new_template,
    commit_message="Added detailed instructions for better output quality",
    tags={
        "author": "data-science-team@company.com",
        "improvement": "Added specific guidelines for summary quality"
    }
)

The UI follows the same rule. You edit a prompt from the Prompts tab and click Save, which creates a new version. The Compare button shows a text diff between two versions' templates. A text diff can't tell you which version gives better answers, though. For that, the documentation says to evaluate both versions on the same dataset and judges, which is covered in a separate lesson on evaluation.

Sources2

3.Loading, searching and using prompts in frameworks

The registry API has six functions. Two of them, register_prompt() and set_prompt_alias(), you have already met. The others load, search and delete. Notice which delete function removes what, because the difference is easy to miss.

load_prompt() accepts three forms. You can use a URI with a version number (prompts:/name/2), a plain name plus a version argument, or a URI with an alias (prompts:/name@production). The first two pin an exact version, which suits experiments and lineage tracking. The alias form is the one to use in deployed applications, as the next section explains.

# Load a specific version using URI syntax
prompt = mlflow.genai.load_prompt(name_or_uri=f"prompts:/{uc_schema}.{prompt_name}/2")

# Or load from specific version
prompt = mlflow.genai.load_prompt(name_or_uri=f"{uc_schema}.{prompt_name}", version="2")

With Unity Catalog, search_prompts() must be scoped to a schema. The documentation marks the filter "catalog = 'main' AND schema = 'default'" as the required format, and you can add max_results to limit how many results come back. To use a prompt with another framework, keep in mind that MLflow templates use double braces. LangChain and LlamaIndex expect single-brace, f-string-style templates. Call to_single_brace_format() on the loaded prompt and pass the result to the framework's template class.

# Load from registry
mlflow_prompt = mlflow.genai.load_prompt("prompts:/mycatalog.myschema.chat@production")

# Convert to LangChain format
langchain_template = mlflow_prompt.to_single_brace_format()
chat_prompt = ChatPromptTemplate.from_template(langchain_template)

Sources21

4.Deploying with aliases and promoting across environments

For deployed agents, the guidance is to load prompts through aliases rather than hard-coded version numbers. The URI format is prompts:/{catalog}.{schema}.{prompt_name}@{alias}. The documentation also recommends reading the alias and the prompt name from environment variables, so the same code can run against dev, staging or production depending on its configuration. Loading from the registry at runtime doesn't slow the agent down, because the MLflow client caches the prompt template.

mlflow.genai. ? (
    name="docs.default.customer_support",
    alias="production",
    version=1
)

Aliases also give you a promotion workflow. During development, each iteration registers a new version and moves a dev alias to it, so testers always get the latest draft. To promote, you look up the version that the source alias points to and point the target alias at the same version. Promotion never copies or edits the prompt text. It only moves a pointer, so the version you promote is byte-for-byte the one you tested.

def promote_prompt(name: str, from_env: str, to_env: str):
    """Promote prompt from one environment to another."""

    # Get current version in source environment
    source = mlflow.genai.load_prompt(f"prompts:/{name}@{from_env}")

    # Point target environment to same version
    mlflow.genai.set_prompt_alias(
        name=name,
        alias=to_env,
        version=source.version
    )

Sources3

5.Tracking prompt versions alongside application versions

Aliases tell you which prompt is live now. Lineage tells you which prompt version a given application version used in the past, which you need when you investigate a regression. MLflow records this link when you call mlflow.set_active_model(). That call creates a LoggedModel for the application version. The LoggedModel doesn't store your code. It is a metadata hub that points to external code, such as a Git commit, records configuration parameters logged with mlflow.log_model_params(), and tracks the registry prompts your app loads.

# Set the new active model
active_model_info_v2 = mlflow.set_active_model(name=new_logged_model_name)

The order of the calls matters. The documentation's example notes that loading the prompt after calling set_active_model() is what lets MLflow link the prompt version to the LoggedModel automatically. Traces from a function decorated with @mlflow.trace are then linked to that LoggedModel, which is in turn linked to the prompt version. To see the linked prompt version, open the experiment and go to the Versions tab. When you register an improved prompt, you set a new active model, such as customer_support_agent-v2-improved-prompt, and load the new version, so each application version records exactly which prompt it ran.

Sources4

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.You can edit an existing prompt version in place to fix its wording.Why is that wrong?

   Versions are immutable. Any change, whether made in the UI or through register_prompt() with the existing name, creates a new version, and the old version stays available for rollback.

   Covered in Registering prompts and creating new versions

2. 2.delete_prompt_alias() removes the version that the alias points to.Why is that wrong?

   delete_prompt_alias() removes only the pointer, and every version remains. To remove versions or a whole prompt, you use delete_prompt().

   Covered in Loading, searching and using prompts in frameworks

3. 3.Production agents should hard-code a version number, and moving to a new prompt requires redeploying the agent.Why is that wrong?

   Deployed agents should load prompts through an alias. Reassigning the alias changes the prompt the agent uses without any code change or redeployment.

   Covered in Deploying with aliases and promoting across environments

4. 4.Loading prompts from the registry at runtime adds a network round trip to every agent request.Why is that wrong?

   The MLflow client caches prompt templates, so the registry doesn't add latency to the agent.

   Covered in Deploying with aliases and promoting across environments

5. 5.Lineage is recorded whenever a prompt is loaded, no matter when set_active_model() is called.Why is that wrong?

   The prompt must be loaded after set_active_model() is called. That ordering is what links the prompt version to the LoggedModel automatically.

   Covered in Tracking prompt versions alongside application versions

Practise it for real

Take a prompt through its lifecycle: register it, point a dev alias at it, load it by alias, and promote it to production without changing any consuming code.

1. 1.In a schema where you hold CREATE FUNCTION, EXECUTE and MANAGE, call mlflow.genai.register_prompt() with a name such as main.default.summarization_prompt, a template containing {{num_sentences}} and {{content}}, and a commit_message.

   Why: Registering under a new name creates the prompt entity and its first immutable version.

   You should see: prompt.version prints 1.

2. 2.Call register_prompt() again with the same name and a revised template, then call set_prompt_alias() with alias="dev" and that new version number.

   Why: Edits become new versions, and the dev alias tracks the latest draft for testers.

   You should see: Version 2 exists, and the dev alias points to it. Version 1 is unchanged.

3. 3.Load the prompt with mlflow.genai.load_prompt("prompts:/main.default.summarization_prompt@dev") and call .format(num_sentences=1, content="...").

   Why: Consumers reference the alias, not the version number.

   You should see: The formatted string uses the version 2 template.

4. 4.Load the prompt through @dev, read its .version, and call set_prompt_alias() with alias="production" and that version, as promote_prompt() does. Then load through @production.

   Why: Promotion only moves a pointer, so production gets the exact version you tested.

   You should see: Loading through @production returns version 2. No new version was created.