Tutorial: Environments and versions

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.

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

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

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 smoke test 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

1. Make changes

   Work in Draft mode

2. Publish

   Click Publish and add a clear description

3. Version appears in Sandbox

   Test thoroughly in Sandbox environment

4. Promote to Pre-release

   Move to staging for QA review

5. Test and review

   Complete full regression testing

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

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

Verification checklist

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.

Try it yourself

1. 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 full smoke 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

Go deeper

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

Environments reference

Full reference for environments and version management

Version diffs

How to compare versions side-by-side before promoting

Version management

Best practices for maintaining versions in a live project

---

← Previous: Edit voice settings

Lesson 4 of 6

Next: Conversation reviews →

Lesson 6 – see what your agent actually did