For a hands-on intro, see Environments tutorial. For technical reference, see Environments and versions.
Quick reference
| I need to… | Action | Time estimate |
|---|---|---|
| Publish a new version | Click Publish → Add description | 2 min |
| Promote to Pre-release | Select version → Promote → Pre-release | 2 min |
| Promote to Live | Select version → Promote → Live | 2 min |
| Rollback to previous version | Find old version → Promote to Live | 3 min |
| Compare two versions | Select versions → Compare | 5 min |
| View version history | Deployments > Environments | 2 min |
| Test a version | Agent Chat → Select environment | 5 min |
Understanding environments and versions
The three environments
PolyAI uses a three-tier deployment model:-
Sandbox - Development and testing environment
- Make changes freely
- Test without affecting users
- No real customer traffic
-
Pre-release - User Acceptance Testing (UAT) environment
- Validate changes before production
- Test with select users or internal team
- Mirrors Live configuration
-
Live - Production environment
- Serves real customer traffic
- Requires careful change management
- Should always be stable
How versions work
- Versions are immutable - Once published, they can’t be changed
- Each environment has one active version - Sandbox, Pre-release, and Live each run a specific version
- Versions flow upward - Sandbox → Pre-release → Live
- You can skip environments - Promote directly from Sandbox to Live (not recommended)
- Rollback is just promotion - Promote an older version to go back
Publishing a new version
When to publish
Publish a new version when you’ve made changes in Sandbox and want to:- Test in a clean environment
- Prepare for promotion to Pre-release or Live
- Create a checkpoint before major changes
- Document a set of related updates
How to publish
- Make your changes in Sandbox
- Test thoroughly in Agent Chat
- Click Publish in the top right
- Add a version description:
- Summarize what changed
- Note any breaking changes
- Reference ticket numbers if applicable
- Click Publish
- “Added Spanish language support with new voice”
- “Fixed booking function timeout issue”
- “Updated business hours for holiday season”
- “Added 50 new FAQ topics from customer feedback”
What gets included in a version
A published version includes:- All Managed Topics
- Connected knowledge source configurations (not the content itself)
- Functions and their code
- Agent settings (about, model, rules)
- Response Controls
- Routing and handoff rules
- API integrations
- Test Cases and Test Sets
Connected knowledge content is synced separately. Sync sources before publishing to ensure the latest content is available.
Promoting versions
Promoting to Pre-release
Use Pre-release for UAT before going live:- Go to Deployments > Environments in the sidebar
- Click the Options Menu next to the desired version
- Select Promote to Pre-release
- Confirm
- Testing with internal team
- Validating with select customers
- Final checks before production
- Compliance or security review
Promoting to Live
Promote to Live when you’re confident the version is ready:- Go to the Pre-release tab in Deployments > Environments
- Click the options menu next to the version
- Select Promote to Live
- Confirm your selection by checking the box and clicking Promote
Skipping environments
You can promote directly from Sandbox to Live, but this is not recommended:- Risk: Untested changes go straight to production
- Use only for: Emergency hotfixes or trivial changes
- Best practice: Always test in Pre-release first
Comparing versions
Why compare versions
Comparing versions helps you:- Understand what changed between versions
- Identify the cause of issues
- Decide whether to promote or rollback
- Document changes for stakeholders
How to compare
- Go to Deployments > Environments
- Select two versions to compare
- Click Compare
- Review the diff:
- Green - Additions (new entries)
- Red - Deletions (removed entries)
- Blue - Edits (modified entries)
What you can compare
- Managed Topics (questions and answers)
- Function code
- Agent settings
- Response Controls
- Routing rules
- Connected knowledge configurations
The comparison shows configuration changes, not Connected knowledge content changes.
Rolling back
When to rollback
Rollback to a previous version when:- New version has critical bugs
- Performance degrades significantly
- Customer complaints spike
- Functions fail unexpectedly
- You need to buy time to fix an issue
How to rollback
- Go to Deployments > Environments
- Find the last known good version
- Click the options menu and select Promote to Live (or Pre-release)
- Confirm
Rollback best practices
- Act quickly - Don’t let bad versions run longer than necessary
- Communicate - Notify your team and stakeholders
- Investigate - Understand what went wrong
- Fix forward - After rolling back, fix the issue and re-promote
- Document - Record what happened and how you fixed it
Emergency rollback procedure
For critical production issues:- Identify the issue - Confirm it’s version-related
- Find last good version - Check Environments & Versions
- Promote immediately - Don’t wait for scheduled time
- Notify team - Alert stakeholders
- Monitor - Verify the rollback fixed the issue
- Post-mortem - Analyze what went wrong
Version management workflows
Standard deployment workflow
-
Develop in Sandbox
- Make changes
- Test in Agent Chat
- Run Test Sets
- Iterate until satisfied
-
Publish version
- Add descriptive version description
- Document changes
-
Promote to Pre-release
- Test with internal team
- Run full Test Sets
- Validate with select customers
- Monitor for issues
-
Promote to Live
- Schedule for off-peak hours
- Monitor closely after promotion
- Be ready to rollback if needed
Hotfix workflow
For urgent fixes:- Identify the issue in Live
- Reproduce in Sandbox
- Fix the issue
- Test quickly but thoroughly
- Publish version
- Promote to Pre-release (brief testing)
- Promote to Live immediately
- Monitor closely
Feature release workflow
For major new features:- Develop in Sandbox over multiple sessions
- Publish checkpoint versions as you go
- Test extensively with Test Sets
- Promote to Pre-release
- UAT with stakeholders (1-2 weeks)
- Gather feedback and iterate
- Promote to Live when approved
- Monitor and optimize
Seasonal update workflow
For recurring seasonal changes (e.g., holiday hours):- Find last year’s version in history
- Review what changed
- Apply similar changes in Sandbox
- Update dates and details
- Test and publish
- Promote to Pre-release (brief testing)
- Schedule promotion to Live for the right date
- Revert after season ends
Best practices
Version descriptions
- Be specific - “Fixed booking timeout” not “Bug fix”
- Include context - Reference ticket numbers or customer reports
- Note breaking changes - Warn about incompatibilities
- Use consistent format - Establish a team standard
- “TICKET-123: Added Spanish support with ElevenLabs voice”
- “Hotfix: Fixed payment API authentication error”
- “Feature: New loyalty program integration with 20 FAQs”
- “Seasonal: Updated holiday hours for Dec 2025”
Testing before promotion
- Run Test Sets - Automated regression testing
- Manual testing - Try realistic scenarios
- Edge cases - Test unusual inputs
- Performance - Check latency and quality
- Integrations - Verify external APIs work
Monitoring after promotion
- First 30 minutes - Watch closely for immediate issues
- First 24 hours - Monitor key metrics
- First week - Track trends and patterns
- Be ready to rollback - Have the process ready
Version hygiene
- Publish regularly - Don’t accumulate too many changes
- Clean up old versions - Archive or delete very old versions
- Document major versions - Keep notes on significant releases
- Use semantic versioning - Consider v1.0, v1.1, v2.0 naming
Troubleshooting version issues
Version won’t promote
Possible causes:- Validation errors
- Missing required fields
- Conflicting configurations
- Check error messages
- Review version configuration
- Fix issues in Sandbox
- Publish new version
- Try promoting again
Changes not appearing after promotion
Possible causes:- Wrong environment selected
- Caching issues
- Version didn’t fully deploy
- Verify correct environment in Agent Chat
- Refresh the page
- Check Environments & Versions for active version
- Wait a few minutes for propagation
- Contact support if persists
Can’t find a specific version
Possible causes:- Version was deleted
- Looking in wrong project
- Version was never published
- Check version history
- Verify project selection
- Search by description or date
- Check with team members
Rollback didn’t fix the issue
Possible causes:- Issue is not version-related
- External dependency problem
- Data issue (not configuration)
- Compare current and previous versions
- Check external APIs and integrations
- Review Connected knowledge content
- Check for infrastructure issues
- Investigate non-version factors
Advanced version management
Using variants with versions
Variants allow different configurations within the same version:- Location-specific - Different menus per restaurant
- A/B testing - Test different approaches
- Customer segments - Different experiences per user type
Version tagging
While not a built-in feature, you can use version descriptions for tagging:[HOTFIX]- Emergency fixes[FEATURE]- New capabilities[BUGFIX]- Non-urgent fixes[SEASONAL]- Temporary changes[EXPERIMENT]- A/B tests
Version branching strategies
For complex projects, consider:- Main branch - Stable, production-ready versions
- Development branch - Active development
- Hotfix branch - Emergency fixes
Related pages
- Environments and versions overview - Understanding the deployment model
- Testing your agent - Creating Test Sets for validation
- Performance monitoring - Tracking version performance
- Health checks - Proactive version monitoring