Skip to main content
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.
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 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 Once published, the version becomes your active deployment and you can access it from Deployments > Environments in the sidebar. active-publish

​
Promoting a version

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

​
Pre-release

Staging environment for user acceptance testing (UAT).
  1. Go to Deployments > Environments 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 > Environments.
  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

​
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 > Environments 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

​
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 Configure > Numbers in the sidebar.
Assign phone numbers and SIP headers per version. assign version phone numbers

​
Automate with the Agents API

The same pipeline is available programmatically — 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.

Test suite

Run regression tests against Draft or Sandbox.

Deployments endpoints

Publish, promote, and rollback from the Agents API.
Last modified on April 22, 2026