> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# Tutorial: Environments

> PolyAcademy Level 1 – Understand Draft, Published, and Environment stages to safely promote changes to production.

**Lesson 5 of 6** – Before your agent goes live, you need to understand environments. This is how you test safely – so changes never reach real users until you're ready.

> **Lesson**
>
> Level 1 · Beginner · 15 min

Think of environments as stages: **Sandbox** (your workspace) → **Pre-release** (QA review) → **Live** (real users). Each stage runs a specific published version of your agent.

## How environments work

Think of environments as **checkpoints**, not branches.

#### Draft

Your working state. Changes exist only for you.

#### Published version

A snapshot of the agent at a moment in time.

#### Environment

A place where a specific version is running and can receive traffic.

Multiple environments can point to the same version, but **only one version per environment** is active at any time.

## The full promotion flow

```mermaid
flowchart TD
    A[Make changes in Draft] --> B[Publish version]
    B --> C[Test in Sandbox]
    C --> D{Tests pass?}
    D -->|Yes| E[Promote to Pre-release]
    D -->|No| F[Fix in Draft]
    F --> B
    E --> G{UAT approved?}
    G -->|Yes| H[Promote to Live]
    G -->|No| F
    H --> I[Monitor first calls]
```

## The Environments page

This page shows every published version of your agent and where it is currently deployed.

#### What you'll see

* Version name or description
* Author and timestamp
* Which environments it's active in (Sandbox / Pre-release / Live)
* An overflow menu for actions

#### Key actions

* **Preview version** – load the agent exactly as that version behaves
* **Compare versions** – open a side-by-side diff
* **Rollback to this version** – immediately restore a previous state

#### Check your understanding

#### Version 14 is active in Sandbox. You publish version 15 and promote it to Sandbox. What happens to version 14?

* It keeps running alongside version 15 until manually removed
* It is replaced – version 15 becomes the only active version in Sandbox
* Both versions run simultaneously for a short overlap period
* Version 14 is automatically promoted to Pre-release

**Answer:** It is replaced – version 15 becomes the only active version in Sandbox

Only one version per environment is active at any time. Promoting version 15 to Sandbox replaces version 14 immediately. Multiple environments can each point to the same version, but each environment runs exactly one.

> **Try it**
>
> Clicking Publish creates a \_\_\_\_\_ of the agent at that point in time. It does not push to any environment automatically.
>
> **Answer:** `version, snapshot, Version, Snapshot`

## Environment types

#### Sandbox

Sandbox is your **development and testing environment**.

**Use Sandbox for:**

* Writing or editing KB topics
* Adjusting rules and behavior
* Changing voice settings
* Wiring or modifying actions, SMS, or handoffs

#### Best practices

* Confirm you are in **Sandbox** before editing
* Publish frequently with short, descriptive notes
* Test after every meaningful change

**Example publish note:**
"Clarified late checkout KB and added SMS consent language"

#### Verification

* Chat testing reflects your latest changes
* Test calls hit Sandbox numbers, not Live numbers
* Conversation Review shows the Sandbox environment tag

#### Pre-release

Pre-release is your **staging / UAT environment**.

It should be treated as:

* Stable
* Reviewable
* Close to production

**Use Pre-release for:**

* Final review and approval
* QA review
* Final voice and pacing checks
* Regression testing

#### Best practices

* Promote to Pre-release only after Sandbox tests pass
* Re-run your tests for what you've built so far:
  * Simple FAQ (Chat and Call)
  * Voice and greeting
  * Out-of-scope refusal
  * Any topics or actions you've added
* Review Conversation Review data again

**Example UAT checklist:**

* Do your FAQ topics still trigger correctly?
* Does voice sound identical to Sandbox?
* Are there any unexpected regressions?

#### Verification

* No unexpected KB topics are triggered
* No new hallucinations appear
* Behavior matches expectations across channels

#### Live

Live is **production**. Real users are here.

**Rules for Live:**

* Never edit directly
* Never "just test something quickly"
* Always know exactly what version is live

#### Best practices

* Promote to Live only from Pre-release
* Confirm promotion explicitly in the dialog
* Monitor first calls after release

**Example safe release habit:**
Promote → make one test call → open Conversation Review → confirm behavior → continue monitoring

## Publishing and promotion flow

#### Make changes

Work in Draft mode

#### Publish

Click **Publish** and add a clear description

#### Version appears in Sandbox

Test thoroughly in Sandbox environment

#### Promote to Pre-release

Move to staging for QA review

#### Test and review

Complete full regression testing

#### Promote to Live

Deploy to production

Nothing skips steps. If it does, something is wrong.

## Comparing versions

The **Compare versions** view is your primary safety tool.

#### What it shows

* Added KB topics
* Modified content
* Removed actions
* Function wiring changes
* Sample question edits

#### When to use it

Before every promotion to verify all changes are intentional

**Example comparison insight:**

* Late checkout KB text changed
* New SMS action added
* No rule or voice changes

If you can't explain every change in the diff, don't promote.

## Rollbacks

Rollbacks are instant and safe.

#### When to use rollback

* A KB topic misfires
* Voice sounds wrong
* Handoffs spike unexpectedly
* A release introduces confusion

#### How to rollback

1. Select a known-good version
2. Click rollback
3. Confirm rollback
4. Verify with a live test call

Rollback restores behavior immediately without deleting newer versions.

## Phone numbers and environments

Each environment can have its own phone number.

#### Sandbox number

Internal testing only

#### Pre-release number

QA and acceptance testing

#### Live number

Public traffic

This prevents accidental testing on production users.

## Common mistakes

> **Warning**
>
> **Avoid these pitfalls:**
>
> * Editing while in Live without noticing
> * Forgetting to publish before testing
> * Assuming KB edits propagate automatically
> * Skipping version comparison
> * Using vague publish notes like "updates"

#### Check your understanding

#### What does clicking 'Publish' do?

* Pushes the agent live immediately
* Sends the agent to Pre-release for QA
* Creates a snapshot (version) of the agent
* Notifies your team of pending changes

**Answer:** Creates a snapshot (version) of the agent

Publish creates a snapshot (version) of the agent at that moment. It does not push to Live – you still need to promote the version to an environment separately.

## Verification checklist

> **Tip**
>
> You understand environments when:
>
> * You can say which version is live without checking
> * You know how to roll back in under a minute
> * You can explain what changed between two versions
> * You never feel tempted to "just tweak production"
>
> If environments feel slow, that usually means they're doing their job.

> **Challenge**
>
> **Scenario:** Your agent is live. The helpdesk reports that since last night's release, the agent incorrectly tells callers that refunds take 3 days — the real policy is 5 business days. Version 22 is currently live. Version 21 was working correctly. What do you do first, and why?
>
> **Hints:**
>
> * You have a way to restore correct behavior immediately, without building or testing a new version.
> * The Environments page shows all published versions and their current deployment status.
> * Restoring speed matters more than perfection right now — you can fix the root cause in Draft afterward.
>
> **Solution:** Roll back to version 21 immediately. Open the Environments page, locate version 21, click Rollback, and confirm. Make one test call to verify the correct refund policy is stated. Then fix the content error in Draft, publish version 23, test in Sandbox, and promote through Pre-release to Live as normal. Rollbacks are safe and instant — always prefer them over deploying a rushed fix under pressure.

## Try it yourself

#### Challenge: Pre-release checklist

You've made three changes in Sandbox: updated the pet policy topic, added a new SMS offer for late checkout, and changed the agent voice stability from 0.6 to 0.8.

List **at least 4 specific tests** you would run before promoting to Pre-release.

#### Hint

Think about each change you made and what could have broken. Also consider: what tests should always run, regardless of what changed?

#### Example solution

1. **Test pet policy topic** – ask "are dogs allowed?" in both Chat and Call; confirm the correct topic triggers.
2. **Test SMS consent flow** – ask "can you text me the late checkout info?" and confirm the agent asks for consent before sending.
3. **Make a test call** – listen for the voice stability change; confirm the agent sounds more consistent and no audio artifacts were introduced.
4. **Run a regression test** – test a simple FAQ, out-of-scope refusal, and a handoff to confirm nothing regressed from your other changes.
5. **Compare versions** – open the diff and confirm the three changes are the only ones present.

#### Check your understanding

#### Which environment should receive real user traffic?

* Sandbox – it's the most stable because it's been through the most testing
* Pre-release – it's the last step before Live, so it's safe for real users
* Live
* Either Pre-release or Live – the difference is just a naming convention

**Answer:** Live

Only Live should receive real user traffic. Sandbox is for development and initial testing; Pre-release is for QA and UAT with test users only. Exposing real callers to earlier environments risks hitting untested behavior.

## Go deeper

The Environments reference covers version diffs, project history, and advanced workflows:

#### [Environments reference](/agent-studio/deployments/overview)

Full reference for environments and version management

#### [Version diffs](/agent-studio/deployments/compare-versions)

How to compare versions side-by-side before promoting

#### [Version management](/academy/maintain/version-management)

Best practices for maintaining versions in a live project

---

#### [← Previous: Edit voice settings](/academy/poly-academy/poly-academy-level-1/edit-voice-settings)

Lesson 4 of 6

#### [Next: Conversation reviews →](/academy/poly-academy/poly-academy-level-1/conversation-reviews)

Lesson 6 – see what your agent actually did