Create a prompt

Create, save, edit, and clone prompts in Phoenix with the Playground or the Phoenix client

This guide shows how to create a prompt and save its versions in Phoenix. You can use the Playground or the Phoenix client.

For the parts of a prompt and how versions work, see Prompts Concepts.

​

Using the Playground

1. Go to Prompts in the navigation.
2. Click the add prompt button at the top right. Phoenix opens the Playground.

Use the playground to develop your prompt. In the prompt section on the right, you can add messages, change the template format (f-string or mustache), and add an output schema (JSON mode).

​

Compose a prompt

Before you run the prompt, make sure that you set an API key for your LLM provider.

1. Enter sample inputs for your prompt variables on the right.
2. Run your prompt against a model.

​

Save the prompt

1. Click the save button in the header of the prompt on the right.
2. Name the prompt with alphanumeric characters and no spaces (for example, `my-first-prompt`).

Phoenix saves the model configuration that you selected in the Playground with the prompt. When you open the prompt again, Phoenix loads the model and its configuration with the prompt.

Once you are satisfied with your prompt in the playground, you can name it and save it

​

View your prompts

To view and search your prompts, go to Prompts in the UI.

To load a prompt back into the Playground, click open in playground. You can do this at any time.

You can quickly load in the latest version of a prompt into the playground

To see the details of a prompt, click the prompt name. The prompt details view shows all the saved parts of the prompt, for example the model and the invocation parameters.

The details of a prompt shows everything that is saved about a prompt

​

Making edits to a prompt

Use the Playground to edit a prompt. Select a method for the size of the change:

• For a small change, save a new prompt version.
• For a large change, clone the prompt.

​

Editing a prompt in the playground

1. In the prompt details view, click edit in Playground at the top right.
2. Make your changes.
3. Click save.
4. Enter a description of your changes.

Iterate on prompts in the playground and save when you are happy with the prompt

The description shows in the prompt history. Other users can read it to understand your change.

​

Cloning a prompt

Clone a prompt to change it without changes to the original version. Cloning is similar to forking a repository in Git. The clone keeps the history of the main prompt safe, so you can reverse your edits.

1. Clone the prompt.
2. Make and review your changes in the clone.
3. Keep the clone as a separate prompt, or merge your changes back into the main prompt.
4. To merge, load the cloned prompt in the Playground and save it as the main prompt.

​

Adding labels and metadata

🚧 Prompt labels and metadata are under construction.

​

Using the Phoenix Client

Use the Phoenix client to create and get prompts in code. Use this method to sync prompts with the Phoenix server from a program. Before you start, install the applicable phoenix-client.

The Python and TypeScript phoenix-client packages are in early development. Some features are not available yet. To request an enhancement, open an issue: https://github.com/Arize-ai/phoenix/issues

​

Compose a Prompt

Python

This example prompt summarizes articles as bullet points. Use the Phoenix client to store the prompt in the Phoenix server. The prompt name is an identifier. It can contain lowercase alphanumeric characters, hyphens, and underscores, and no spaces.

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

content = """\
You're an expert educator in {{ topic }}. Summarize the following article
in a few concise bullet points that are easy for beginners to understand.

{{ article }}
"""

prompt_name = "article-bullet-summarizer"
prompt = Client().prompts.create(
    name=prompt_name,
    version=PromptVersion(
        [{"role": "user", "content": content}],
        model_name="gpt-4o-mini",
    ),
)

To get a stored prompt, use its name. By default, the client gets the latest version. To get a specific version, use a version ID or a tag.

prompt = Client().prompts.get(prompt_identifier=prompt_name)

To get a version that has a tag, for example “production”, add the tag:

prompt = Client().prompts.get(prompt_identifier=prompt_name, tag="production")

TypeScript

This example prompt summarizes articles as bullet points. Use the Phoenix client to store the prompt in the Phoenix server. The prompt name is an identifier. It can contain lowercase alphanumeric characters, hyphens, and underscores, and no spaces.

import { createPrompt, promptVersion } from "@arizeai/phoenix-client/prompts";

const promptTemplate = `
You're an expert educator in {{ topic }}. Summarize the following article
in a few concise bullet points that are easy for beginners to understand.

{{ article }}
`;

const version = createPrompt({
  name: "article-bullet-summarizer",
  version: promptVersion({
    modelProvider: "OPENAI",
    modelName: "gpt-5.6-terra",
    template: [
      {
        role: "user",
        content: promptTemplate,
      },
    ],
  }),
});

To get a stored prompt, use its name. By default, the client gets the latest version. To get a specific version, use a version ID or a tag.

import { getPrompt } from "@arizeai/phoenix-client/prompts";

const prompt = await getPrompt({ prompt: { name: "article-bullet-summarizer" } });
// ^ you now have a strongly-typed prompt object, in the Phoenix SDK Prompt type

To get a version that has a tag, for example “production”, add the tag:

const promptByTag = await getPrompt({ prompt: { tag: "production", name: "article-bullet-summarizer" } });
// ^ you can optionally specify a tag to filter by