Implementation:Arize ai Phoenix Prompts Create

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

Overview

Concrete tool for creating and persisting LLM prompt versions provided by the arize-phoenix-client Python package.

Description

The Prompts.create() method registers a new prompt version in the Phoenix server. If a prompt with the given name already exists, the call appends a new immutable version to that prompt's history. If no prompt with the name exists, a new prompt is created and the supplied version becomes its first entry.

The method accepts a PromptVersion object that encapsulates the full prompt configuration: message template, model name, model provider, invocation parameters, tool definitions, and response format. The server persists this configuration, assigns a unique version identifier, and returns the enriched PromptVersion with the server-assigned ID.

Usage

Use Prompts.create() when:

• Authoring a new prompt for a feature or experiment.
• Adding a revised version of an existing prompt after iterating on the template or model configuration.
• Programmatically registering prompts generated by optimization or evaluation pipelines.
• Converting prompts from native SDK formats (OpenAI, Anthropic, Google) into Phoenix-managed assets.

Code Reference

Source Location

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

Signature

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

PromptVersion Constructor

class PromptVersion:
    def __init__(
        self,
        prompt: Sequence[v1.PromptMessage],
        /,
        *,
        model_name: str,
        description: Optional[str] = None,
        model_provider: Literal[
            "OPENAI", "AZURE_OPENAI", "ANTHROPIC", "GOOGLE",
            "DEEPSEEK", "XAI", "AWS", "OLLAMA"
        ] = "OPENAI",
        template_format: Literal["F_STRING", "MUSTACHE", "NONE"] = "MUSTACHE",
    ) -> None

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 prompt version object containing the template, model configuration, invocation parameters, tools, and response format.
name	str	Yes	The identifier for the prompt. Must begin with an alphanumeric character and may contain alphanumeric characters, hyphens, and underscores. If a prompt with this name exists, a new version is appended; otherwise a new prompt is created.
prompt_description	Optional[str]	No	An optional description for the prompt. If the prompt already exists, this value is ignored by the server.
prompt_metadata	Optional[dict[str, Any]]	No	An optional metadata dictionary for the prompt. If the prompt already exists, this value is ignored by the server.

PromptVersion Constructor Inputs

Name	Type	Required	Description
prompt	Sequence[PromptMessage]	Yes (positional)	A sequence of prompt messages. Each message is a dict with keys such as role and content.
model_name	str	Yes	The name of the target model (e.g., "gpt-4o", "claude-3-5-sonnet").
description	Optional[str]	No	Human-readable description of this prompt version.
model_provider	Literal["OPENAI", "AZURE_OPENAI", "ANTHROPIC", "GOOGLE", "DEEPSEEK", "XAI", "AWS", "OLLAMA"]	No	The model provider. Defaults to "OPENAI".
template_format	Literal["F_STRING", "MUSTACHE", "NONE"]	No	The template variable syntax. Defaults to "MUSTACHE" (double curly braces).

Outputs

Name	Type	Description
return value	PromptVersion	The created prompt version with a server-assigned id property. Contains the persisted template, model configuration, invocation parameters, tools, and response format.

Usage Examples

Create a Simple Prompt

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

client = Client()

# Define a prompt version with a Mustache-style template
version = PromptVersion(
    [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Summarize the following text: {{text}}"},
    ],
    model_name="gpt-4o",
    model_provider="OPENAI",
    template_format="MUSTACHE",
    description="Summarization prompt v1",
)

# Create the prompt (or add a version if it already exists)
created = client.prompts.create(
    name="text-summarizer",
    version=version,
    prompt_description="General-purpose text summarization prompt",
)

print(f"Created version ID: {created.id}")

Create a Prompt with Metadata

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

client = Client()

version = PromptVersion(
    [
        {"role": "system", "content": "Classify the sentiment of the text as positive, negative, or neutral."},
        {"role": "user", "content": "Text: {{input_text}}\n\nSentiment:"},
    ],
    model_name="gpt-4o-mini",
    model_provider="OPENAI",
)

created = client.prompts.create(
    name="sentiment-classifier",
    version=version,
    prompt_description="Sentiment classification prompt",
    prompt_metadata={"category": "classification", "team": "nlp"},
)

Create a Prompt from an OpenAI Request

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

client = Client()

# Convert an OpenAI-style completion params dict into a PromptVersion
openai_params = {
    "model": "gpt-4o",
    "messages": [
        {"role": "system", "content": "You are a coding assistant."},
        {"role": "user", "content": "Explain {{concept}} in simple terms."},
    ],
    "temperature": 0.7,
}

version = PromptVersion.from_openai(openai_params)

created = client.prompts.create(
    name="code-explainer",
    version=version,
)

Create a Prompt Targeting Anthropic

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

client = Client()

version = PromptVersion(
    [
        {"role": "system", "content": "You are an expert data analyst."},
        {"role": "user", "content": "Analyze the following dataset description: {{dataset_info}}"},
    ],
    model_name="claude-3-5-sonnet",
    model_provider="ANTHROPIC",
    template_format="MUSTACHE",
)

created = client.prompts.create(
    name="data-analyst",
    version=version,
)

API Endpoint

The method issues an HTTP POST request to the v1/prompts endpoint. The request body contains:

{
  "prompt": {
    "name": "text-summarizer",
    "description": "optional prompt description",
    "metadata": {}
  },
  "version": {
    "model_provider": "OPENAI",
    "model_name": "gpt-4o",
    "template": {
      "type": "chat",
      "messages": [...]
    },
    "template_type": "CHAT",
    "template_format": "MUSTACHE",
    "invocation_parameters": { "type": "openai", "openai": {} }
  }
}

The response body contains a data key with the created PromptVersion data, including the server-assigned version id.

Error Handling

• httpx.HTTPStatusError -- raised if the server returns a non-success HTTP status code (e.g., 400 for invalid prompt name format, 500 for server errors).
• Validation errors -- the prompt name must begin with an alphanumeric character and may only contain alphanumeric characters, hyphens, and underscores.

Related Pages

Implements Principle

• Principle:Arize_ai_Phoenix_Prompt_Creation