/playground

name: playground
description: Author, edit, or iterate on prompts in the Phoenix prompt playground, including running experiments over a dataset. Load before any playground `ui.*` operation call, including single-shot prompt rewrites.
summary: Author, edit, run, compare, and improve prompts in the Phoenix playground.

Prompt Playground

The prompt playground is a tool for authoring and optimizing prompts. It supports two different ways of working: fast manual prompt iteration without a dataset, and dataset-backed prompt experimentation with evaluators and experiments. Choose the workflow that matches the user's current goal and the UI context they have mounted.

The playground actions named below are `ui.*` operations, called from `execute_browser_action` scripts as `await ui.<operation>(input)` (for example `await ui.playground.run({})`). Confirm exact input shapes with `search_browser_actions` before first use, and prefer one small script that chains related steps over many single-call scripts.

Workflow: Create And Iterate Without A Dataset

Use this workflow when the user wants to draft, rewrite, or manually improve a prompt and no dataset-backed evaluation loop is in scope.

1. Clarify the task the prompt must perform: input variables, expected output shape, audience, constraints, and examples of good or bad behavior when available. 2. If a playground prompt already exists, call `ui.playground.prompt.read` before proposing changes so you have the current messages, message IDs, labels, and revision. 3. Draft or revise the prompt so it clearly states the task, required context, output contract, and success criteria. Keep the prompt directly tied to the user's stated goal. 4. Use `ui.playground.prompt.edit` for changes to the mounted prompt so the user can review the diff before accepting it. 5. Use `ui.playground.instance.add` when the user wants a fresh comparison instance that starts from the default prompt messages. Use `ui.playground.instance.clone` when comparing alternatives should preserve existing prompt content as the starting point. Discuss variants by their alphabetic labels, but pass numeric instance IDs to operations. After adding, use the returned `addedInstance` snapshot for follow-up edits. 6. Use `ui.playground.variables.set` when the user provides manual values for prompt template variables. 7. Use `ui.playground.repetitions.set` before running when the user is concerned about flakes, structured output consistency, tool-call reliability, or whether the prompt is ready to save. LLM outputs are nondeterministic; repetitions build confidence by checking the same task across multiple runs instead of trusting one successful response. 8. Call `ui.playground.run` only when the user asks to run, try, test, or compare the current prompt. Treat the output as qualitative feedback rather than dataset-backed evidence. One script can run and read in sequence: `const run = await ui.playground.run({}); if (!run.ok) return run; return await ui.playground.run.readOutput({});` 9. After the run finishes, call `ui.playground.run.readOutput` to inspect raw output and get the traceId for trace analysis when needed. If the run used multiple repetitions, inspect every repetition before summarizing confidence or recommending that the user save. 10. Call `ui.playground.prompt.save` only when the user explicitly asks to save or confirms that the current prompt should be persisted. For a first-time save of an unsaved prompt, omit `name` unless the user provided one; the operation will derive a valid Phoenix prompt name from the prompt content. Always pass a save description; it should read like a clear, short git commit message. Treat tags like releases and do not promote tags unless the user asks. 11. Inspect the output with the user, identify the next concrete improvement, and repeat the edit or comparison loop until the prompt is useful for the task.

Workflow: Iterate Over A Dataset With Evaluators And Experiments

Use this workflow when the user wants evidence that a prompt is improving across a dataset, or when they are comparing prompt variants using evaluator results. Running a prompt over a dataset is implicitly an experiment: consult the `experiments` skill before designing the run, not only after results arrive — it owns the iteration methodology end to end (what to stage at creation, how to read and compare results, when an evaluator is warranted), and the `evaluators` skill owns designing the evaluators that score them. This workflow covers only the playground mechanics of setting up and starting a recorded run.

1. Load the dataset with `ui.playground.dataset.load` if it isn't already loaded. If the user named a dataset but no split and the dataset has splits, name them and ask whether to scope to one or load the whole dataset — then load once. 2. Make sure the starting prompt is well formed before running it: it should define the task, relevant variables, output format, and any constraints needed for consistent evaluation. 3. Use `ui.playground.experiment.setRecording` before running when the user wants the next dataset-backed playground run recorded, persisted, or saved as an experiment, or wants to name, describe, or attach metadata (such as a hypothesis or the variable being changed) to the next experiment. Set `recordExperiments` to false only when the user explicitly asks for a temporary, throwaway, unrecorded, or ephemeral run. Call this operation only when the requested recording mode or scaffold fields differ from the advertised `recordExperiments` and `nextExperimentScaffold` values; the staged scaffold applies to that one run and is consumed when it starts. This is separate from `ui.playground.prompt.save`, which saves prompt versions rather than run results. 4. Use `ui.playground.repetitions.set` before running when the user needs confidence across repea