> 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.

# Deployments

> Ship safely: branch, promote, A/B test, and roll back from one timeline.

Studio Assistant uses two environments: **Sandbox** for testing changes, and **Live** where real callers reach your agent. Publish a version to Sandbox, validate it, then promote it to Live.

```mermaid
stateDiagram-v2
    [*] --> Draft: Make changes
    Draft --> Sandbox: Publish
    Sandbox --> Live: Promote

    Live --> Sandbox: Rollback

    note right of Draft: Edits in progress
    note right of Sandbox: Testing
    note right of Live: Production
```

> **Warning**
>
> **Publishing isn't the same as going live.** Drafts must be **published** to Sandbox first. They only reach your callers when you **promote** to Live.

## Publish a draft to Sandbox

Whenever you make changes (via Studio Assistant or directly), a draft banner appears at the top of the page with two options:

* **Delete** reverts to the most recent published version.
* **Publish** saves the draft as a version. Add a short description if you want a note for future you.

![delete-publish](/_fern-files/_img/312eeb6ce348e11f2453f838ffc443abe49df02881b962db803f7c1cfe9f6637.webp)

Once published, the version becomes your active **Sandbox** deployment. Find it under **Deployments** in the sidebar.

## Test in Sandbox

Click **Test** in the top-right of any page to open the Agent Debugging panel. Choose **Call agent** or **Webchat**, pick **Sandbox** from the environment dropdown, and try the scenario you're worried about. Every test call lands in [Conversations](/agent-studio/conversations/overview) with a transcript.

If something looks off, the [iterate-after-a-call](/academy/maintain/iterate-after-a-call) flow walks through fixing it.

## Promote to Live

When the Sandbox version handles real scenarios properly, promote it.

1. Open **Deployments** in the sidebar.
2. In the **Sandbox** tab, click the overflow menu (three dots) next to the version.
3. Select **Promote to Live**.
4. Tick the confirmation box and click **Promote**.

![Deployments page in Studio Assistant mode showing the Sandbox tab with a list of published versions](/_fern-files/_img/9db278a0f78f9e1bb57f830291350785ca11d0db2842c695c9a4f2236a036272.webp)

![Promote version live confirmation modal warning that the version will receive live customer traffic, with an 'I understand and wish to continue' checkbox and a Promote button](/_fern-files/_img/f8c373cf929a45a6da5b59a049d87b5156d19ca32f8c09f67b82c57e863202c6.webp)

Once it's Live, every new caller (via Web Calling, the shareable link, or anywhere else you've placed the agent) hits the promoted version immediately.

## Roll back

If a Live version is causing problems, roll back.

1. Open **Deployments > Live** in the sidebar.
2. Open the overflow menu on the version you want to roll back.
3. Click **Rollback**, then confirm.

The previous version becomes Live again. You can promote forward whenever you're ready.

## Compare versions

Side-by-side diffs let you check what changed between two versions before you promote. Open **Deployments** or **Project History**, select a version, and click **Compare**. Sorting is newest-first.

![Version comparison view showing two deployments side by side with line-level diffs across Functions, Variables, Flows, and other agent settings](/_fern-files/_img/e4c46eaf03ae8b9725e457ed8c38d475e7a55d6408fa2ed321376a8297b1e0a7.webp)

[Tracking changes →](/agent-studio/deployments/compare-versions)

Test agent changes before they reach live callers. Draft → Sandbox → Pre-release → Live.

> **Note**
>
> **New to environments?** Start with the [Environments tutorial](/academy/poly-academy/poly-academy-level-1/environments) for a hands-on introduction. For detailed workflows and best practices, see [Version management](/academy/maintain/version-management).

> **Tip**
>
> **Studio Assistant edits on branches.** Changes from [Studio Assistant](/agent-studio/studio-assistant/overview) land on a branch off `Main`. Once merged, they flow through this same Draft → Sandbox → Pre-release → Live pipeline. Promotion is always manual.

> **Warning**
>
> **Saving is not the same as going live.** Saved changes are drafts. Drafts must be **published** to Sandbox, then **promoted** through Pre-release to Live. Unpublished changes don't appear in any environment.

```mermaid
stateDiagram-v2
    [*] --> Draft: Make changes
    Draft --> Sandbox: Publish
    Sandbox --> PreRelease: Promote
    PreRelease --> Live: Promote
    
    Live --> PreRelease: Rollback
    PreRelease --> Sandbox: Rollback
    
    note right of Draft: Development
    note right of Sandbox: Testing
    note right of PreRelease: UAT staging
    note right of Live: Production
```

## Creating a version

A

draft

version
is created whenever changes are made to an agent. A draft banner appears at the top of the page, allowing you to:

* **Delete**: Revert to the most recent published version.

* **Publish**: Save the draft as a version, optionally adding a description highlighting changes made and any notes for future
  collaborators.

![delete-publish](/_fern-files/_img/312eeb6ce348e11f2453f838ffc443abe49df02881b962db803f7c1cfe9f6637.webp)

Once published, the version becomes your active

Sandbox

deployment
and you can access it from **Deployments** in the sidebar.

![active-publish](/_fern-files/_img/e4344ebcfbedd37323b978551915234040c87b3f9af5dc21c08b5121197a657b.webp)

## Promoting a version

Promotion moves a version from one environment to the next. The environments include Sandbox,

Pre-release

,
and

Live

.

### Pre-release

Staging environment for user acceptance testing (UAT).

1. Go to **Deployments** in the sidebar.

2. Click the **Options Menu** next to the desired version.

3. Select **Promote to Pre-release**.

### Live

Production. Changes affect all active calls immediately.

1. Go to the **Pre-release** tab in **Deployments**.

2. Click the overflow menu (three vertical dots) next to the version.

3. Select **Promote to Live**.

4. Confirm your selection by checking the box and clicking **Promote**.

#### Confirm

![initiate release](/_fern-files/_img/2cba00c362a6eebb8fd96c9b2f782ba030be9f3192ecdd673ec8b60b4f69b2f6.webp)

#### Complete

![release confirmed and live](/_fern-files/_img/b033e8827625d91f52d94024e0d4459f49604baad7450930e3f04e10295c1f4a.webp)

## Comparing versions and environments

Before promoting changes, you can compare versions across environments using a side-by-side diff view.

1. Go to the **Deployments** section and open **Environments** or **Project History**.

2. Select a version and click **Compare** to view differences between **Sandbox**, **Pre-release**, and **Live**.

3. Versions appear in **reverse chronological order** (newest first) for easier navigation.

For detailed information on tracking changes between versions, see [Tracking changes](/agent-studio/deployments/compare-versions).

## Rolling back to a previous version

Roll back to a previous version if needed:

1. Go to **Deployments** in the sidebar.

2. Select the **Options Menu** for the desired version.

3. Click **Rollback**.

4. Confirm the rollback.

The system confirms when the rollback is complete.

#### Initiate

![initiate rollback](/_fern-files/_img/2eed7cbd948a974e8c3cbd4407b4591357df5cb6a09f455ff37d9cc3291cbd0d.webp)

#### Confirm

![confirm rollback](/_fern-files/_img/8c7b5ebe8d6afaaf62557b2fa7c3f4bd2a304c7df648efaa6e5d4e0c9c73e95e.webp)

## Testing your agent

Main page: [Quickstart: test your agent](/agent-studio/get-started/quickstart#test-your-agent)

Test your agent in any environment:

1. Click the **Play Chat** icon in the top-right corner of the screen.

2. Select the environment containing the version you want to test.

## Assigning phone numbers

Each environment can have its own phone number. To assign:

1. Go to **Voice > Numbers** in the sidebar.

Assign phone numbers and SIP headers per version.

![assign version phone numbers](/_fern-files/_img/67fe9d35116c2259f2fbb267c952f1130cca636a2875fe11af6fad8935e5fb0d.webp)

## Automate with the Agents API

The same pipeline is available programmatically, which is useful for wiring deployments into CI or orchestrating releases across many agents.

#### Deploy via the Agents API

The [Agents API](/api-reference/build-deploy/agents-api/overview) exposes [publish](/api-reference/api-reference/agents/deployments/publish), [promote](/api-reference/api-reference/agents/deployments/promote), and [rollback](/api-reference/api-reference/agents/deployments/rollback) as the CI-friendly equivalents of the UI actions above.

**`curl`**

```bash curl
# Publish the current draft to sandbox
curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/deployments/publish \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "environment": "sandbox" }'

# Promote a sandbox deployment to pre-release
curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/deployments/DEPLOYMENT_ID/promote \
  -H "x-api-key: $POLYAI_API_KEY"
```

**`Python`**

```python Python
import os, requests

BASE = "https://api.us.poly.ai"
HEADERS = {"x-api-key": os.environ["POLYAI_API_KEY"]}

# Publish the current draft to sandbox
resp = requests.post(
    f"{BASE}/v1/agents/{AGENT_ID}/deployments/publish",
    headers=HEADERS,
    json={"environment": "sandbox"},
)
deployment_id = resp.json()["id"]

# Promote to pre-release once sandbox checks pass
requests.post(
    f"{BASE}/v1/agents/{AGENT_ID}/deployments/{deployment_id}/promote",
    headers=HEADERS,
)
```

## Related pages

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

Side-by-side diff of any two versions before promoting.

#### [Project history](/agent-studio/deployments/project-history)

Audit trail of all published versions and changes.

#### [Testing](/agent-studio/testing/simulation-tests)

Run regression tests against Draft or Sandbox.

#### [Deployments endpoints](/api-reference/api-reference/agents/deployments/publish)

Publish, promote, and rollback from the Agents API.