Skip to navigation
Deployments

Deployments

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.

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
Removing a draft from a version line

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 with a transcript.

If something looks off, the 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
Deployments page in Studio Assistant mode showing the Sandbox tab with a list of published versions
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
Promote version live confirmation modal with an 'I understand and wish to continue' checkbox and a Promote button

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
Version comparison view showing two deployments side by side with line-level diffs across Functions, Variables, Flows, and other agent settings

Tracking changes →

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

New to environments? Start with the Environments tutorial for a hands-on introduction. For detailed workflows and best practices, see Version management.

Studio Assistant edits on branches. Changes from Studio Assistant land on a branch off Main. Once merged, they flow through this same Draft → Sandbox → Pre-release → Live pipeline. Promotion is always manual.

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.

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
Removing a draft from a version line

Once published, the version becomes your active Sandbox deployment and you can access it from Deployments in the sidebar.

active-publish
Promoting a version across environments

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.

initiate release
initiate release

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.

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 rollback
initiate rollback

Testing your agent

Main page: 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
assign version phone numbers

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.

The Agents API exposes publish, promote, and rollback as the CI-friendly equivalents of the UI actions above.

# 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"
Compare versions

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

Project history

Audit trail of all published versions and changes.

Testing

Run regression tests against Draft or Sandbox.

Deployments endpoints

Publish, promote, and rollback from the Agents API.