The deployment pipeline

Manage versions, testing, and deploying updates.

Two environments on Agent Builder: Sandbox, where your changes land for testing, and Live, where real callers reach your agent. You publish a version into Sandbox, test it, then promote it to Live when you’re happy.

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

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.

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.

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.

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.

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

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

Confirm

Complete

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

Confirm

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.

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 exposes publish, promote, and rollback as the CI-friendly equivalents of the UI actions above.

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"

Related pages

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.