Implementation:Arize ai Phoenix Prompts Create Version

Knowledge Sources	Phoenix
Domains	Prompt Engineering, Version Control, Python API
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete tool for creating versioned LLM prompts provided by the arize-phoenix-client Python package, using the same Prompts.create() method with upsert semantics to automatically append new versions to existing prompts.

Description

Prompt versioning in Phoenix is implemented through the same Prompts.create() endpoint used for prompt creation. The versioning behavior is implicit: when create() is called with a name that matches an existing prompt, the supplied PromptVersion is appended as a new immutable version to that prompt's history. No separate "add version" API exists because the creation endpoint handles both cases transparently.

Each version captures the full prompt state: message template, model name, model provider, template format, invocation parameters, tools, response format, and description. Versions are immutable once created and are assigned a unique server-generated identifier. The version history forms a linear, append-only sequence ordered by creation time.

Additionally, the PromptVersion class provides factory methods for creating versions from native SDK objects, making it straightforward to version prompts that originate from different model providers.

Usage

Use the versioning pattern when:

• Iterating on an existing prompt's template or model configuration.
• Running A/B experiments where each variant is a distinct version under the same prompt name.
• Building automated prompt optimization pipelines that persist each candidate as a new version.
• Converting prompts between providers (e.g., migrating from OpenAI to Anthropic) while preserving version history.

Code Reference

Source Location

• Repository: Phoenix
• File: packages/phoenix-client/src/phoenix/client/resources/prompts/__init__.py (lines 126-160)
• PromptVersion class: packages/phoenix-client/src/phoenix/client/types/prompts.py

Signature (Prompts.create)

def create(
    self,
    *,
    version: PromptVersion,
    name: str,
    prompt_description: Optional[str] = None,
    prompt_metadata: Optional[dict[str, Any]] = None,
) -> PromptVersion

Factory Methods for Multi-Provider Versioning

# From OpenAI completion params
PromptVersion.from_openai(
    obj: CompletionCreateParamsBase,
    /,
    *,
    template_format: Literal["F_STRING", "MUSTACHE", "NONE"] = "MUSTACHE",
    description: Optional[str] = None,
    model_provider: Literal["OPENAI", "AZURE_OPENAI", "DEEPSEEK", "XAI", "OLLAMA"] = "OPENAI",
) -> PromptVersion

# From Anthropic message params
PromptVersion.from_anthropic(
    obj: MessageCreateParamsBase,
    /,
    *,
    template_format: Literal["F_STRING", "MUSTACHE", "NONE"] = "MUSTACHE",
    description: Optional[str] = None,
    model_provider: Literal["ANTHROPIC"] = "ANTHROPIC",
) -> PromptVersion

# From Google Generative AI params
PromptVersion.from_google_generativeai(
    obj: Any,
    /,
    *,
    template_format: Literal["F_STRING", "MUSTACHE", "NONE"] = "MUSTACHE",
    description: Optional[str] = None,
    model_provider: Literal["GOOGLE"] = "GOOGLE",
) -> PromptVersion

Import

from phoenix.client import Client
from phoenix.client.types.prompts import PromptVersion

I/O Contract

Inputs

Name	Type	Required	Description
version	PromptVersion	Yes	The new prompt version object. Contains the complete prompt configuration to be persisted.
name	str	Yes	The prompt name. If a prompt with this name already exists, a new version is appended to its history. If not, a new prompt is created.
prompt_description	Optional[str]	No	Description for the prompt. Ignored by the server if the prompt already exists.
prompt_metadata	Optional[dict[str, Any]]	No	Metadata dictionary for the prompt. Ignored by the server if the prompt already exists.

Outputs

Name	Type	Description
return value	PromptVersion	The newly created version with a server-assigned id. The id property uniquely identifies this version in the version history.

Usage Examples

Iterating on a Prompt Template

from phoenix.client import Client
from phoenix.client.types.prompts import PromptVersion

client = Client()

# Version 1: Initial prompt
v1 = PromptVersion(
    [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Summarize: {{text}}"},
    ],
    model_name="gpt-4",
    model_provider="OPENAI",
    description="Initial summarization prompt",
)

created_v1 = client.prompts.create(name="summarizer", version=v1)
print(f"Version 1 ID: {created_v1.id}")

# Version 2: Improved instructions
v2 = PromptVersion(
    [
        {"role": "system", "content": "You are an expert summarizer. Be concise and accurate."},
        {"role": "user", "content": "Please summarize the following text in 2-3 sentences:\n\n{{text}}"},
    ],
    model_name="gpt-4o",
    model_provider="OPENAI",
    description="Improved summarization with explicit length guidance",
)

created_v2 = client.prompts.create(name="summarizer", version=v2)
print(f"Version 2 ID: {created_v2.id}")

Versioning from an OpenAI SDK Object

from phoenix.client import Client
from phoenix.client.types.prompts import PromptVersion

client = Client()

# Suppose you have an OpenAI completion params dict that works well
openai_params = {
    "model": "gpt-4o",
    "messages": [
        {"role": "system", "content": "You are a translation expert."},
        {"role": "user", "content": "Translate to {{target_language}}: {{text}}"},
    ],
    "temperature": 0.3,
    "max_tokens": 1000,
}

# Convert to a PromptVersion and persist
version = PromptVersion.from_openai(
    openai_params,
    description="Translation prompt from OpenAI config",
)

created = client.prompts.create(name="translator", version=version)
print(f"Created version: {created.id}")

Versioning from an Anthropic SDK Object

from phoenix.client import Client
from phoenix.client.types.prompts import PromptVersion

client = Client()

anthropic_params = {
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "system": "You are a creative writing assistant.",
    "messages": [
        {"role": "user", "content": "Write a short story about: {{topic}}"},
    ],
}

version = PromptVersion.from_anthropic(
    anthropic_params,
    description="Creative writing prompt via Anthropic",
)

created = client.prompts.create(name="story-writer", version=version)

Automated Versioning in an Optimization Loop

from phoenix.client import Client
from phoenix.client.types.prompts import PromptVersion

client = Client()

# Hypothetical prompt optimization loop
candidate_templates = [
    "Classify the sentiment as positive, negative, or neutral: {{text}}",
    "Determine the emotional tone (positive/negative/neutral) of: {{text}}",
    "Read the text and output the sentiment label: {{text}}",
]

for i, template in enumerate(candidate_templates):
    version = PromptVersion(
        [{"role": "user", "content": template}],
        model_name="gpt-4o-mini",
        model_provider="OPENAI",
        description=f"Optimization candidate {i + 1}",
    )
    created = client.prompts.create(name="sentiment-v2", version=version)
    print(f"Candidate {i + 1} persisted with ID: {created.id}")

Key Versioning Behaviors

Behavior	Description
Upsert semantics	Calling create() with an existing prompt name appends a new version. Calling with a new name creates both the prompt and its first version.
Immutability	Created versions cannot be modified. Any change requires creating a new version.
Full-state capture	Each version stores the complete prompt configuration (template, model, parameters, tools, response format) -- not a diff from the previous version.
Automatic ordering	Versions are sequenced by creation time. The most recent version is retrievable via Prompts.get(prompt_identifier="name") without specifying a version ID.
Server-assigned IDs	The server generates a unique identifier for each version, accessible via the id property of the returned PromptVersion.

Related Pages

Implements Principle

• Principle:Arize_ai_Phoenix_Prompt_Versioning