How do I version agent prompts, tools, and harness configurations?

Summary

• Version prompts in the MLflow Prompt Registry. The MLflow Prompt Registry (Beta) gives prompts auto-incrementing, immutable versions with commit messages, tags, and rollback.
• Deploy with aliases, not code changes. Mutable aliases like production or staging point to a specific prompt version, so re-aliasing flips the live prompt without editing agent code.
• Version the agent separately. Use MLflow to mark the active agent version; bump it when the agent's code, tools, or underlying model change, while prompt changes are versioned on their own track.
• Governed in Unity Catalog. Prompts, agent tools built as Unity Catalog functions, and registered models are all named, permissioned assets in Unity Catalog.
• Automatic lineage. MLflow links prompt versions to agent/application versions and to evaluation results, viewable in the MLflow experiment UI.

How do I version agent prompts, tools, and harness configurations?

Production agents change constantly: you tune the system prompt, swap a tool, or move to a new model. To do that safely you need to version each of these independently, promote changes without editing code, and roll back when something regresses. On Databricks, MLflow provides prompt versioning through the Prompt Registry and agent versioning through logged models, and Unity Catalog stores prompts, tools, and models as governed, versioned assets. Databricks Agent Bricks builds on this foundation, so agents you create are tracked the same way.

Why Databricks and MLflow for versioning agents

• MLflow Prompt Registry for prompts. Registering a prompt creates an immutable snapshot with an auto-incrementing version number, a commit message, and version-specific tags, so you get version control and rollback for prompt text. Use mlflow.genai.register_prompt() to create a prompt or add a version, mlflow.genai.load_prompt() to retrieve one, and mlflow.genai.search_prompts() to find prompts by name, tags, or metadata.
• Aliases for safe promotion. Aliases are mutable pointers — such as production or staging — that reference a specific version. Agents load a prompt with a reference like prompts:/<name>@production, so promoting a new version is just moving the alias with mlflow.genai.set_prompt_alias(); the deployed prompt changes without touching agent code, which makes staged rollouts and rollback straightforward.
• Agent versioning decoupled from prompts. Mark the active agent version with mlflow.set_active_model(); every trace produced afterward links back to that version through its model ID. The rule of thumb is to bump the agent version when the agent's code, tools, or model change, and to version prompt changes separately — so you always know which combination produced a given result.
• Tools and configurations as governed assets. Agent tools implemented as Unity Catalog functions are named, permissioned objects in Unity Catalog. Because a change to the agent's tools or code triggers a new agent version, your tool and harness configuration are captured alongside the agent version rather than left untracked. You can also log configuration as parameters on the agent's logged model.
• Unity Catalog governance. Prompts are stored as named entities in Unity Catalog and registering them requires CREATE FUNCTION, EXECUTE, and MANAGE privileges on the schema, so prompt, tool, and model versioning all inherit Unity Catalog access control and auditability.
• Automatic lineage and evaluation links. MLflow automatically creates lineage between prompt versions and the application/agent versions that use them, and links prompts to experiments and evaluation results. You can review this in the MLflow experiment UI under the Versions tab to see exactly which prompt and agent version produced which outcome.

The MLflow Prompt Registry and Agent Bricks are in Beta; capabilities may change.

Getting started

• Read the MLflow Prompt Registry overview and the Prompt Registry SDK.
• Follow Track prompt versions alongside application versions.
• See the MLflow GenAI prompt management API reference.
• For a worked example of registering prompts and re-aliasing without redeploying, read Building a self-optimizing chatbot with domain experts on Databricks.

FAQs

How do I version a prompt on Databricks?

Register it with mlflow.genai.register_prompt() in the MLflow Prompt Registry. Each registration creates an immutable, auto-incrementing version with a commit message and tags, and you can roll back to any prior version.

How do I promote a new prompt without changing agent code?

Use aliases. Point an alias like production at a version, have the agent load prompts:/<name>@production, then move the alias to a new version with mlflow.genai.set_prompt_alias() to change the live prompt.

Should the agent version change when I edit a prompt?

No. Prompt changes are versioned in the Prompt Registry. Bump the agent version (via mlflow.set_active_model()) when the agent's code, tools, or model change.

Where are prompts and tools stored?

Prompts are stored as named entities in Unity Catalog, and agent tools built as Unity Catalog functions are governed there too, so versioning inherits Unity Catalog access control and lineage.