Tutorial: Environments
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.
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
Version 14 is active in Sandbox. You publish version 15 and promote it to Sandbox. What happens to version 14?
- It keeps running alongside version 15 until manually removed
- It is replaced – version 15 becomes the only active version in Sandbox
- Both versions run simultaneously for a short overlap period
- Version 14 is automatically promoted to Pre-release
Answer: It is replaced – version 15 becomes the only active version in Sandbox
Only one version per environment is active at any time. Promoting version 15 to Sandbox replaces version 14 immediately. Multiple environments can each point to the same version, but each environment runs exactly one.
Clicking Publish creates a _____ of the agent at that point in time. It does not push to any environment automatically.
Answer: version, snapshot, Version, Snapshot
Environment types
Sandbox
Pre-release
Live
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
Publishing and promotion flow
Nothing skips steps. If it does, something is wrong.
Comparing versions
The Compare versions view is your primary safety tool.
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
- Select a known-good version
- Click rollback
- Confirm rollback
- 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.
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
What does clicking 'Publish' do?
- Pushes the agent live immediately
- Sends the agent to Pre-release for QA
- Creates a snapshot (version) of the agent
- Notifies your team of pending changes
Answer: Creates a snapshot (version) of the agent
Publish creates a snapshot (version) of the agent at that moment. It does not push to Live – you still need to promote the version to an environment separately.
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.
Scenario: Your agent is live. The helpdesk reports that since last night’s release, the agent incorrectly tells callers that refunds take 3 days — the real policy is 5 business days. Version 22 is currently live. Version 21 was working correctly. What do you do first, and why?
Hints:
- You have a way to restore correct behavior immediately, without building or testing a new version.
- The Environments page shows all published versions and their current deployment status.
- Restoring speed matters more than perfection right now — you can fix the root cause in Draft afterward.
Solution: Roll back to version 21 immediately. Open the Environments page, locate version 21, click Rollback, and confirm. Make one test call to verify the correct refund policy is stated. Then fix the content error in Draft, publish version 23, test in Sandbox, and promote through Pre-release to Live as normal. Rollbacks are safe and instant — always prefer them over deploying a rushed fix under pressure.
Try it yourself
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
- Test pet policy topic – ask “are dogs allowed?” in both Chat and Call; confirm the correct topic triggers.
- Test SMS consent flow – ask “can you text me the late checkout info?” and confirm the agent asks for consent before sending.
- Make a test call – listen for the voice stability change; confirm the agent sounds more consistent and no audio artifacts were introduced.
- Run a regression test – test a simple FAQ, out-of-scope refusal, and a handoff to confirm nothing regressed from your other changes.
- Compare versions – open the diff and confirm the three changes are the only ones present.
Check your understanding
Which environment should receive real user traffic?
- Sandbox – it’s the most stable because it’s been through the most testing
- Pre-release – it’s the last step before Live, so it’s safe for real users
- Live
- Either Pre-release or Live – the difference is just a naming convention
Answer: Live
Only Live should receive real user traffic. Sandbox is for development and initial testing; Pre-release is for QA and UAT with test users only. Exposing real callers to earlier environments risks hitting untested behavior.
Go deeper
The Environments reference covers version diffs, project history, and advanced workflows: