> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Playground

> Re-run production traces with modified prompts. Edit skills, compare outputs, and iterate on agent behavior — all with your own API keys.

The Playground page lets you experiment with your agent's prompts in a safe sandbox. Re-run real production traces with modified instructions, compare outputs side-by-side, and save successful edits as new skill versions.

<Note>
  Playground uses **your own LLM API keys** (BYOK — Bring Your Own Key). DecimalAI doesn't subsidize LLM calls — you pay your provider directly. Configure keys in **Settings → Credentials**.
</Note>

<Note>
  **Playground vs. skillevaluation.** The Playground is for **interactive, single-trace** exploration — re-run one trace, eyeball the side-by-side, iterate by hand. To measure whether a skill actually helps **across a batch** of cases (a with-skill vs. without-skill A/B that produces a SkillScore), use the skillevaluation benchmark instead — see [Skills](/guides/skills). Use the Playground to form a hypothesis; use a benchmark to prove it.
</Note>

***

## Getting Started

Navigate to the Playground page from the sidebar, or open it contextually:

* **From a trace:** Click **"Open in Playground"** on any trace detail page
* **From a skill:** Click **"Test in Playground"** on any skill detail page
* **Direct URL:** `/playground` or `/playground?skill=code-review`

***

## Three Modes

The Playground runs in one of three modes — pick the one that matches what you're iterating on.

<Tabs>
  <Tab title="Import from Trace">
    Re-run a production trace with modifications:

    1. Select an **agent** from the dropdown
    2. Select a **trace** — the system prompt and user message auto-populate
    3. The **original output** appears on the right for comparison
    4. Edit the system prompt or user message
    5. Choose a model and temperature
    6. Click **Run** (or press `⌘+Enter`)
    7. Compare the new output against the original side-by-side

    This is the default mode — ideal for debugging unexpected outputs or testing prompt changes against real conversations.
  </Tab>

  <Tab title="Skill Testing">
    Test skill body edits against production traces:

    1. Navigate from a skill page via **"Test in Playground"**, or use `/playground?skill=my-skill-name`
    2. The **skill body editor** shows the editable portion of the skill
    3. A **trace selector** shows recent traces where this skill was activated
    4. Edit the skill body (e.g., add instructions, refine examples)
    5. Click **Run** — the platform reconstructs the full system prompt with your edited skill body swapped in
    6. Review the side-by-side comparison
    7. If satisfied, click **"Save as New Version"** — this creates a new `SkillVersion` with your edited body

    <Tip>
      The skill editor highlights only the skill's body within the larger system prompt. Your edits are surgically inserted at the correct position, preserving all other prompt context.
    </Tip>
  </Tab>

  <Tab title="Scratch Pad">
    Test prompts from scratch:

    1. Switch to the **Scratch Pad** tab
    2. Write a system prompt and user message
    3. Select a model
    4. Click **Run**
    5. View the output

    No trace import, no skill context — just a blank canvas for rapid prototyping.
  </Tab>
</Tabs>

***

## Model Selection

The Playground page supports multiple LLM providers:

| Provider      | Models                                                | API Key Env Var     |
| ------------- | ----------------------------------------------------- | ------------------- |
| **OpenAI**    | gpt-4o, gpt-4o-mini, gpt-4-turbo, o1-preview, o3-mini | `OPENAI_API_KEY`    |
| **Google**    | gemini-3.5-flash, gemini-2.5-pro                      | `GEMINI_API_KEY`    |
| **Anthropic** | claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5  | `ANTHROPIC_API_KEY` |

Select a provider and model from the dropdowns. If no API key is configured for the selected provider, you'll see a friendly error with a link to Settings.

<Note>
  All three providers run directly in the Playground with your own keys (BYOK) — set each provider's key in Settings. `gemini-3.5-flash` is the default model.
</Note>

***

## Temperature Control

Adjust the temperature slider (0.0–2.0) to control output randomness:

| Temperature | Behavior                                                    |
| ----------- | ----------------------------------------------------------- |
| **0.0**     | Deterministic — same output every time                      |
| **0.3–0.5** | Focused but varied — good for code and structured outputs   |
| **0.7**     | Default — balanced creativity and precision                 |
| **1.0–2.0** | More creative — good for brainstorming and open-ended tasks |

***

## Comparing Outputs

When importing from a trace or testing a skill, the page shows a side-by-side comparison:

| Left Panel                                                  | Right Panel                                                        |
| ----------------------------------------------------------- | ------------------------------------------------------------------ |
| **Original output** — what the agent produced in production | **New output** — what the agent produces with your modified prompt |

This makes it easy to spot differences and judge whether your changes improved the output.

***

## Saving Skill Changes

In **Skill Testing** mode, after running a modified skill body:

1. If the output improves, click **"Save as New Version"**
2. This creates a new `SkillVersion` with your edited body
3. The version is automatically tracked in the skill's version history
4. All future activations of this skill use the updated body

<Warning>
  Saving overwrites the skill's current body. The previous version is preserved in the version history — you can always revert from the Skills page.
</Warning>

***

## Keyboard Shortcuts

| Shortcut                             | Action         |
| ------------------------------------ | -------------- |
| `⌘+Enter` (Mac) / `Ctrl+Enter` (Win) | Run the prompt |

***

## Workflow Examples

### Debugging a Bad Output

<Steps>
  <Step title="Find the trace">
    Find a trace with a poor output in the Traces page.
  </Step>

  <Step title="Open in Playground">
    Click **"Open in Playground"** on the trace detail page.
  </Step>

  <Step title="Refine the prompt">
    Edit the system prompt to add more specific instructions.
  </Step>

  <Step title="Iterate">
    Run → compare → iterate until the output improves.
  </Step>

  <Step title="Apply the fix">
    Apply the improved prompt to your agent's configuration.
  </Step>
</Steps>

### Hand-Tuning a Skill Body

<Steps>
  <Step title="Open the skill">
    Open a skill → **"Test in Playground"**.
  </Step>

  <Step title="Pick a few traces">
    Select 3–5 recent traces from the trace dropdown to sanity-check your edit against real conversations.
  </Step>

  <Step title="Edit and compare">
    For each trace: edit the skill body → run → compare side-by-side.
  </Step>

  <Step title="Save a new version">
    When satisfied, click **"Save as New Version"**.
  </Step>

  <Step title="Confirm it helps">
    Monitor the new version's effectiveness on the Skills dashboard. To confirm the edit actually helps across a batch — not just on the handful you eyeballed — run a [skillevaluation benchmark](/guides/skills).
  </Step>
</Steps>

### Testing Different Models

<Steps>
  <Step title="Set up the prompt">
    Import a trace or write a scratch prompt.
  </Step>

  <Step title="Run the first model">
    Run with `gpt-4o` → note the output.
  </Step>

  <Step title="Run a second model">
    Switch to `claude-sonnet-4-6` → run again.
  </Step>

  <Step title="Choose the best fit">
    Compare outputs to choose the best model for your use case.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tracing" icon="route" href="/guides/tracing">
    Open any production trace in the playground to iterate on it.
  </Card>

  <Card title="Skills" icon="puzzle-piece" href="/guides/skills">
    Test skill changes in the playground before saving a new version.
  </Card>

  <Card title="Evaluations" icon="circle-check" href="/guides/evaluations">
    Score playground runs with the same evaluators used in production.
  </Card>
</CardGroup>