Skip to main content

​
Versioning

Versioning is your safety net for AI deployments. Every change you make to your AI’s knowledge or guidance creates a new, immutable version that you can test, deploy, and roll back with confidence. This ensures your customers always interact with stable, predictable AI behavior while you continue to innovate behind the scenes.

​
Why Versioning Matters

AI agents are fundamentally different from traditional software. They don’t follow deterministic code paths - they generate responses dynamically based on instructions, knowledge, and context. Versioning provides the control and safety you need to manage this complexity.

​
The Challenge Without Versioning

Imagine making a small tweak to your AI’s guidance and pushing it live immediately. Within minutes:
  • Customer conversations might get unexpected responses
  • Critical functionality could break without warning
  • You’d have no way to quickly revert the change
  • Different channels might show inconsistent behavior
  • You’d lose the ability to test before production

​
The Power of Versioning

With proper versioning, you gain: Predictable Deployments - Every version is an exact snapshot of your AI’s complete configuration. When you deploy version #15, you know precisely what behavior customers will experience. Safe Testing - Test new versions thoroughly in staging environments before exposing them to customers. Catch issues early when they’re easy to fix. Instant Rollback - If a deployment causes problems, revert to the previous version in seconds. Your customers experience minimal disruption. Audit Trail - Track exactly what changed and when. See your AI’s evolution over time and understand the impact of each modification. Consistency Across Channels - All channels (Website, Zendesk, Salesforce, Slack) use the same version simultaneously. No confusion about which configuration is live where. Confidence to Innovate - Experiment freely knowing you can always roll back. Version control removes the fear of making improvements.
Think of versions like save points in a video game. You can try new strategies, and if something goes wrong, you reload the last working save. Versioning gives you that same freedom to experiment with your AI.

​
How Versioning Works

botBrains uses a three-tier architecture to manage versions and deployments:

​
1. Profiles (Your Work in Progress)

A profile represents your AI’s current configuration:
  • Guidance instructions and rules
  • Tool and integration settings
  • LLM model selection and parameters
  • Audience targeting rules
  • General settings and preferences
Profiles are editable. You can:
  • Add or modify guidance instructions
  • Enable or disable tools
  • Adjust LLM settings
  • Test changes in preview mode
Changes to profiles are not immediately visible to customers - they exist in your development environment until you build a version.

​
2. Versions (Immutable Snapshots)

A version is an immutable snapshot created when you build your profile:
  • Sequential number identifier (#1, #2, #3…)
  • Complete profile configuration at build time
  • Knowledge snapshot with all data provider content
  • Creation timestamp
  • Never changes after creation
Building a version:
  1. Freezes your current profile configuration
  2. Captures the complete state of all knowledge sources
  3. Indexes content for fast retrieval
  4. Creates a deployable package
  5. Makes it available for production use
Versions are immutable by design. Once built, they never change. This ensures consistency - version #12 behaves identically every time, whether you deploy it today or next month.

​
3. Aliases (Production Pointers)

An alias is a named pointer to a specific version:
  • “Production” alias points to your live version
  • Can be updated to point to different versions
  • All channels connect to aliases, not directly to versions
  • Allows instant version switching without reconfiguring channels
When you update an alias from version #12 to version #13:
  • All channels using that alias switch immediately
  • No downtime or configuration changes needed
  • Previous version remains available for rollback

​
The Complete Architecture

┌─────────────────────────────────────────────────────────────┐
│  YOUR WORK IN PROGRESS                                      │
│                                                              │
│  Profile Configuration                                      │
│  ├─ Guidance Instructions (editable)                        │
│  ├─ Tool Configuration (editable)                           │
│  ├─ LLM Settings (editable)                                 │
│  └─ Audience Rules (editable)                               │
│                                                              │
│  Knowledge Sources (editable)                               │
│  ├─ Data Providers syncing content                          │
│  ├─ Snippets being created                                  │
│  └─ Tables being updated                                    │
│                                                              │
│  [Build Version] ──────────────────────────────────────┐    │
│                                                         │    │
└─────────────────────────────────────────────────────────┼────┘
                                                          │
                                                          ▼
┌─────────────────────────────────────────────────────────────┐
│  IMMUTABLE VERSIONS                                         │
│                                                              │
│  Version #15 (Latest Build)                                 │
│  ├─ Profile Configuration Snapshot                          │
│  ├─ Knowledge Snapshot (all sources)                        │
│  ├─ Created: 2025-03-15 14:30 UTC                          │
│  └─ Status: Available                                       │
│                                                              │
│  Version #14 (Previous)                   ◄─── Production   │
│  ├─ Profile Configuration Snapshot             Alias        │
│  ├─ Knowledge Snapshot (all sources)                        │
│  ├─ Created: 2025-03-14 10:15 UTC                          │
│  └─ Status: Production ✓                                    │
│                                                              │
│  Version #13, #12, #11... (History)                         │
│  └─ All available for rollback                              │
│                                                              │
└─────────────────────────────────────────────┬───────────────┘
                                              │
                                              │ Channels connect
                                              │ to alias
                                              ▼
┌─────────────────────────────────────────────────────────────┐
│  CUSTOMER-FACING CHANNELS                                   │
│                                                              │
│  Website Widget ────┐                                       │
│  Zendesk Integration─┼─→ Production Alias ─→ Version #14    │
│  Salesforce ─────────┤                                      │
│  Slack Bot ──────────┘                                      │
│                                                              │
└─────────────────────────────────────────────────────────────┘

​
The Deployment Flow

Understanding the complete lifecycle from making changes to deploying them helps you use versioning effectively.

​
Step 1: Make Changes

Edit your AI configuration in the platform: Modify Guidance
  • Add new guidance rules for emerging use cases
  • Refine existing instructions for better responses
  • Update tone or style guidelines
  • Adjust tool permissions
Update Knowledge
  • Sync data providers to get latest content
  • Create or edit snippets
  • Upload new documents
  • Update search tables
Configure Tools
  • Enable new integrations
  • Adjust tool parameters
  • Add or remove available actions
All changes are saved to your profile but not yet live. Your production AI continues using the current version.
Work freely in your profile without worrying about affecting live customers. Changes only go live when you explicitly build and deploy a version.

​
Step 2: Test in Preview

Before building a version, test your changes: Use Preview Mode
  1. Navigate to Behavior → Guidance
  2. Click the preview/test interface
  3. Ask sample questions
  4. Verify responses match expectations
  5. Check that tools work correctly
What Preview Shows
  • Current profile configuration (not deployed version)
  • Latest knowledge from data providers
  • All active guidance rules
  • Enabled tools and integrations
Limitations
  • Preview doesn’t capture production traffic patterns
  • May not reflect all edge cases
  • Should be supplemented with test suites

​
Step 3: Build a Version

When you’re ready to make changes available: Navigate to Behavior and click Build Version, Set Active. What Happens During Build Immediate Actions (1-5 seconds):
  • System locks current profile configuration
  • Assigns sequential version number
  • Creates build job
Processing (30-60 seconds):
  • Captures complete knowledge snapshot
  • Indexes all data provider content
  • Processes all chunks and embeddings
  • Compiles profile configuration
  • Creates deployable package
  • Validates completeness
Completion:
  • Version becomes available
  • Production alias updates to new version (if “Set Active” chosen)
  • All channels switch to new version
  • Build notification appears
Build Options “Build Version, Set Active” (Recommended for most updates)
  • Creates version and deploys to production
  • All channels switch immediately
  • Use when: Changes are tested and ready for customers
“Build Version” (For staged deployments)
  • Creates version without deploying
  • Allows additional testing before going live
  • Manually set as active later
  • Use when: Major changes need final validation
“Build Version, Set Active, Get Email” (For large deployments)
  • Runs build asynchronously in background
  • Sends email notification when complete
  • Use when: Many channels or large knowledge bases (10+ minutes build time)
Building with “Set Active” deploys changes to all connected channels immediately. Ensure you’ve tested thoroughly before using this option for significant changes.

​
Step 4: Verify Deployment

After building and deploying: Immediate Checks (First 5 minutes)
  1. Test sample questions in each channel
  2. Verify responses match expectations
  3. Check that new knowledge is accessible
  4. Confirm tools work correctly
Short-term Monitoring (First Hour)
  1. Review incoming conversations
  2. Watch for error rates or unusual patterns
  3. Check customer satisfaction scores
  4. Monitor escalation rates
Ongoing Evaluation (First 24 Hours)
  1. Compare metrics to previous version
  2. Review conversation topics and outcomes
  3. Gather team feedback
  4. Identify any issues requiring rollback or fixes

​
Step 5: Iterate or Roll Back

Based on monitoring results: If Deployment Succeeds
  • Document what changed and why
  • Note improvements in metrics
  • Continue refining for next version
  • Archive learnings for team knowledge
If Issues Arise
  • Assess severity and impact
  • Roll back immediately if critical (see Rolling Back)
  • Investigate root cause
  • Fix in development environment
  • Test more thoroughly
  • Build and deploy corrected version

​
Testing New Versions

Proper testing prevents production issues and builds confidence in deployments.

​
Testing Strategies

Preview Testing (Basic) Test individual changes as you make them:
  1. Make a change to guidance or knowledge
  2. Open preview interface
  3. Ask relevant questions
  4. Verify responses
  5. Iterate until satisfied
Best for: Small, incremental changes Test Suites (Recommended) Create comprehensive test suites covering critical functionality:
  1. Navigate to Test Suites
  2. Create suite for each major feature area
  3. Add test cases covering common scenarios
  4. Run suite against preview version
  5. Review results and fix failures
  6. Re-run until all tests pass
Best for: Ensuring regressions don’t occur Learn more in Testing AI Agents. Staging Environment (Advanced) Use a separate project as staging:
  1. Create separate botBrains project for testing
  2. Copy configuration from production
  3. Build and deploy test versions in staging
  4. Test with real channels (test Slack workspace, etc.)
  5. Validate with team before production deployment
Best for: Teams with multiple stakeholders or high-risk deployments A/B Testing (Enterprise) Compare versions side-by-side:
  1. Deploy version A to some channels
  2. Deploy version B to other channels
  3. Monitor comparative metrics
  4. Identify winning version
  5. Deploy winner to all channels
Best for: Optimizing performance or testing major changes

​
What to Test

Functional Testing
  • Knowledge retrieval works correctly
  • Tools and integrations execute properly
  • Guidance rules apply as expected
  • Audience targeting functions correctly
Quality Testing
  • Response accuracy meets standards
  • Tone and style match brand guidelines
  • Escalations trigger appropriately
  • Citations and sources appear correctly
Edge Case Testing
  • Ambiguous or unclear questions
  • Multi-step conversations with context
  • Error conditions and fallback behavior
  • Unusual user inputs or requests
Performance Testing
  • Response times are acceptable
  • No timeout errors occur
  • Concurrent conversations handle correctly

​
Test Coverage Guidelines

Minimum Viable Testing
  • 5-10 test cases covering most common user questions
  • Manual preview testing before each build
  • Spot-check after deployment
Recommended Testing
  • 20-50 test cases organized into suites
  • Automated test suite runs before deployment
  • Structured monitoring after deployment
  • Team review for major changes
Comprehensive Testing
  • 100+ test cases covering all features
  • Multiple test suites by feature area
  • Staging environment validation
  • Automated regression testing
  • A/B testing for optimizations

​
Upgrading to Production

Promoting a version to production requires understanding the mechanisms and implications.

​
Deployment Methods

Automatic Deployment (During Build) When building with “Set Active”:
  1. Build process creates version
  2. Production alias updates automatically
  3. Channels switch immediately upon completion
  4. Zero manual steps after clicking “Build”
Manual Deployment (After Build) When building without “Set Active”:
  1. Build process creates version (not deployed)
  2. Version appears in versions list
  3. Test version as needed
  4. Manually set as active when ready
  5. Production alias updates upon manual action
  6. Channels switch immediately
Setting a Version as Active Manually
  1. Navigate to Behavior → General
  2. Scroll to Versions section
  3. Find the version you want to deploy
  4. Click the ⋮ menu (three vertical dots)
  5. Select Set as Active
  6. Confirm the action
Within seconds, all channels switch to the selected version.

​
Deployment Characteristics

Zero Downtime All deployments are zero-downtime:
  • Channels remain available during version switch
  • New conversations use new version immediately
  • Ongoing conversations complete with current version
  • No service interruption occurs
Instant Propagation Version changes propagate instantly:
  • All channels update within 1-2 seconds
  • No gradual rollout or propagation delay
  • Consistent behavior across all integration points
Atomic Updates Version switches are atomic:
  • All channels switch simultaneously
  • No partial deployment state exists
  • Either old version or new version, never mixed

​
Channel-Specific Considerations

Each integration channel handles version updates seamlessly, but understanding the specifics helps you plan deployments. Website Widget
  • Updates apply to new chat sessions immediately
  • Existing open chat windows may use previous version until refresh
  • Users who reload page get new version
  • Consider deployment timing around peak traffic
Zendesk
  • Agent assist suggestions use new version immediately
  • Automated responses switch instantly
  • No impact on ticket workflow or history
  • Existing tickets continue normally
Salesforce
  • Case deflection uses new version for new cases
  • Agent assist updates immediately
  • Historical case data unaffected
  • Salesforce knowledge sync continues
Slack
  • Bot responses use new version immediately
  • Direct messages and channel mentions update instantly
  • Message history shows previous version’s responses
  • Users see no interruption
WhatsApp
  • New messages use new version immediately
  • Conversation history preserved
  • No impact on message delivery
  • Users experience seamless transition
While version switches are instant at the platform level, browser caching may cause brief delays (1-2 minutes) for website widgets. Users who refresh get the new version immediately.

​
Deployment Best Practices

Timing Deployments Deploy during periods that minimize impact:
  • Low traffic hours - Fewer customers affected if issues arise
  • Team availability - Ensure team can monitor and respond
  • Avoid critical periods - Don’t deploy during major events or holidays
  • Consider time zones - If global, choose time when most regions have low activity
Staged Rollouts For major changes, consider rolling out gradually:
  1. Deploy to internal channels first (test Slack workspace)
  2. Monitor for issues
  3. Deploy to one customer-facing channel
  4. Monitor metrics and feedback
  5. Deploy to remaining channels if successful
This requires creating separate aliases for different channels, which is an advanced pattern. Communication Inform relevant stakeholders:
  • Before deployment: Notify team of upcoming changes
  • During deployment: Communicate deployment in progress
  • After deployment: Share results and next steps
Documentation Track deployments systematically:
  • Document what changed in each version
  • Note why changes were made
  • Record deployment time and conditions
  • Log any issues encountered
  • Summarize outcomes and learnings

​
Why Knowledge is Versioned

Knowledge versioning is crucial for maintaining AI reliability and ensuring consistent behavior.

​
The Need for Knowledge Snapshots

Your knowledge sources are constantly evolving:
  • Data providers sync new content regularly
  • Snippets get created and edited
  • Documents are updated or removed
  • Tables receive new data
Without versioning, your AI’s behavior would change unpredictably as knowledge updates. This creates problems: Inconsistent Responses - The same question might get different answers depending on when it’s asked. Untested Changes - New knowledge affects responses without validation or review. No Rollback Path - If updated knowledge causes issues, you can’t revert to previous working state. Debugging Nightmares - Impossible to know which knowledge version caused a specific response.

​
How Knowledge Snapshots Work

When you build a version, botBrains captures a complete knowledge snapshot: Data Provider Content
  • All synced pages, documents, and articles
  • Current state of all sources
  • Processed chunks and embeddings
  • Metadata and structure
Snippet Collections
  • All active snippets
  • Content and formatting
  • Audience targeting rules
  • Priority ordering
Search Tables
  • Table schemas and columns
  • Row data (by reference)
  • Query configurations
Processing State
  • Embeddings for semantic search
  • Indexes for fast retrieval
  • Chunk boundaries and metadata
The snapshot is immutable. Even if you update data providers or snippets afterward, the deployed version continues using its snapshot.

​
Keeping Knowledge Current

As knowledge sources update, you need to rebuild to incorporate changes. Staleness Indicator The platform shows when deployed knowledge is outdated:
  • Green: “Knowledge Up-to-date” - Deployed version has latest content
  • Orange: “Knowledge Stale” - Data providers synced new content after last build
When you see the orange indicator:
  1. Review what changed in data providers
  2. Test updated content in preview
  3. Build new version when ready
  4. Deploy to incorporate latest knowledge
Regular Rebuild Cadence Establish a rebuild schedule based on update frequency: Daily Updates (e.g., support documentation changes daily)
  • Build new versions daily or multiple times per day
  • Automate builds using API if needed
  • Monitor staleness indicators
Weekly Updates (e.g., product docs update weekly)
  • Build new versions weekly
  • Batch multiple knowledge updates into one version
  • Schedule builds during low-traffic periods
Monthly Updates (e.g., policies update occasionally)
  • Build monthly or as needed
  • Focus builds on significant knowledge additions
  • Combine with guidance improvements
Set calendar reminders to check for stale knowledge. Even if you haven’t changed guidance, rebuilding to incorporate updated knowledge keeps your AI current.

​
Guidance vs. Knowledge Versioning

Both guidance and knowledge are versioned, but they’re managed differently: Guidance Changes Require Rebuild
  • Edit guidance in profile
  • Changes don’t affect production until build
  • Preview shows edited guidance
  • Build creates new version with updated guidance
Knowledge Changes Require Rebuild
  • Data providers sync new content
  • Synced content doesn’t affect production until build
  • Preview may show updated knowledge
  • Build creates new version with knowledge snapshot
Both Together
  • Most versions include both guidance and knowledge changes
  • Build captures current state of both
  • Version contains complete, consistent snapshot

​
Version Management

Effectively managing versions over time ensures clean history and easy navigation.

​
Viewing Version History

Navigate to Behavior → General → Versions to see all versions. Version List Displays:
  • Version Number: Sequential identifier (#1, #2, #3…)
  • Profile Name: Profile version at build time (v0.0, v0.1, v0.2…)
  • Status Badge: “Production” if currently active
  • Created Date: When version was built
  • Actions Menu: Options to set as active or view details
Versions are sorted newest to oldest by default.

​
Comparing Versions

Understanding what changed between versions helps troubleshoot issues and track improvements. Manual Comparison
  1. Note version numbers to compare (e.g., #14 vs. #15)
  2. Check your documentation or notes for changes made
  3. Review guidance edits between profile versions
  4. Identify knowledge syncs that occurred between builds
Conversation Analysis
  1. Navigate to Analyze → Conversations
  2. Filter by version number
  3. Review responses from each version
  4. Identify behavioral differences
  5. Determine which version performed better
Metrics Comparison
  1. Navigate to Analyze → Metrics
  2. Compare time periods for each version
  3. Look at CSAT, resolution rate, escalation rate
  4. Identify performance improvements or regressions
The platform doesn’t currently provide automatic diff views between versions. Use your own documentation and metrics analysis to track changes.

​
Rolling Back to Previous Versions

When a deployment causes issues, rolling back quickly minimizes customer impact. Quick Rollback Process
  1. Identify the Problem
    • Monitor conversations showing incorrect responses
    • Review metrics showing degraded performance
    • Receive customer or team feedback about issues
  2. Determine Target Version
    • Usually the version immediately before problematic one
    • Verify that version was working correctly
    • Check version number (e.g., rollback from #15 to #14)
  3. Execute Rollback
    • Navigate to Behavior → General → Versions
    • Find the target version in list
    • Click ⋮ menu next to version
    • Select Set as Active
    • Confirm the action
  4. Verify Rollback
    • Test sample questions immediately
    • Monitor incoming conversations
    • Confirm expected behavior restored
    • Watch metrics for improvement
Rollback Timing From problem identification to restored service: 2-5 minutes
  • 1 minute to identify issue and decide on rollback
  • 1 minute to navigate and execute rollback
  • 1-2 minutes for verification
  • Channels update within seconds of rollback

​
When to Roll Back

Immediate Rollback (Critical Issues) Roll back immediately if you observe:
  • High error rates: Tools failing, knowledge not accessible
  • Incorrect information: AI providing wrong answers systematically
  • Broken functionality: Key features not working
  • CSAT drop: Customer satisfaction drops significantly (>0.5 points)
  • Escalation spike: Dramatic increase in human handoffs
  • Customer complaints: Multiple reports of poor experience
Monitor First (Minor Issues) Wait and monitor if you see:
  • Slight metric fluctuations: Small changes within normal variance
  • Isolated incidents: Single conversation with unexpected behavior
  • Cosmetic issues: Minor wording or style differences
  • Easily fixable: Can be corrected quickly with snippet update
After Rolling Back
  1. Investigate Root Cause
    • Review what changed between versions
    • Identify specific guidance, knowledge, or configuration that caused issue
    • Understand why the problem wasn’t caught in testing
  2. Fix in Development
    • Update profile with correction
    • Test thoroughly in preview
    • Run test suites to prevent regression
    • Add new test cases covering the issue
  3. Rebuild and Redeploy
    • Build new version with fix
    • Deploy during appropriate time
    • Monitor closely for success
    • Document the incident and resolution

​
Version Naming and Tagging

While versions have sequential numbers, profile names help track changes. Profile Naming Convention The platform uses semantic versioning for profiles:
  • v0.0, v0.1, v0.2 - Initial development versions
  • v1.0 - First production-ready version
  • v1.1, v1.2 - Minor improvements and refinements
  • v2.0 - Major changes or new features
When to Increment Minor Version (v1.1 → v1.2)
  • Small guidance refinements
  • Knowledge updates from syncs
  • Bug fixes and corrections
  • Tone adjustments
  • Single feature additions
Major Version (v1.9 → v2.0)
  • Complete guidance overhaul
  • New integration channels
  • Major feature additions
  • Significant knowledge restructuring
  • Fundamental behavior changes
Tracking Changes Keep external documentation of version changes: 
Version #15 (Profile v1.3) - 2025-03-15
- Added 12 new snippets for API documentation
- Updated refund policy guidance for Q2 2025
- Enabled search_web tool for technical questions
- Fixed escalation criteria for billing issues

Version #14 (Profile v1.2) - 2025-03-10
- Synced latest product documentation (25 new pages)
- Refined tone to be more conversational
- Disabled create_ticket tool (testing phase complete)

Version #13 (Profile v1.1) - 2025-03-05
- Initial production release
- Complete guidance for support, sales, technical
- 150 snippets across all product areas
- All channels connected and tested

​
Cleaning Up Old Versions

Versions are stored indefinitely by default, which provides complete history. Version Retention All versions remain available unless explicitly deleted:
  • No automatic cleanup or archiving
  • Oldest versions remain accessible
  • Storage costs are minimal
  • History provides valuable audit trail
When to Keep Versions
  • Recent versions (last 10-20 builds)
  • Major milestone versions (v1.0, v2.0)
  • Versions used in production for significant periods
  • Versions representing major changes
Version Limits The platform doesn’t impose strict version limits, but practical considerations:
  • 100+ versions may slow UI performance
  • Most projects have 20-50 versions over time
  • Consider your rollback needs when deciding retention

​
Best Practices

Effective version management comes from disciplined processes and clear conventions.

​
Build Frequency

During Active Development Build frequently to test and iterate quickly:
  • After each significant change
  • Daily or multiple times per day
  • Test each version before setting as production
  • Iterate based on test results
During Stable Operation Build less frequently, focusing on meaningful updates:
  • Weekly or monthly to incorporate knowledge updates
  • When substantial guidance improvements are ready
  • Batch multiple small changes into single version
  • Avoid building for trivial changes

​
Testing Before Deployment

Minimum Testing (Small Changes)
  • Preview test with 5-10 sample questions
  • Verify specific change works as intended
  • Quick smoke test across main features
Standard Testing (Normal Updates)
  • Run full test suite (20-50 test cases)
  • Preview test across multiple scenarios
  • Team review if multiple people involved
  • Check for regressions in core functionality
Comprehensive Testing (Major Changes)
  • Multiple test suites covering all features
  • Staging environment validation
  • Team review and sign-off
  • Phased rollout plan prepared
  • Rollback plan documented

​
Monitoring After Deployment

First 30 Minutes
  • Spot-check conversations manually
  • Test in each channel
  • Verify no immediate errors
  • Confirm expected behavior
First 24 Hours
  • Monitor key metrics (CSAT, escalation rate)
  • Review conversation topics
  • Check error logs
  • Gather team feedback
First Week
  • Compare metrics to previous version
  • Identify unexpected patterns
  • Review customer feedback
  • Document learnings

​
Documentation Standards

Version Notes Template For each version, document: 
## Version #[number] (Profile v[version]) - [Date]

### Summary
Brief description of what changed and why.

### Changes
- Guidance: [List guidance changes]
- Knowledge: [List knowledge updates]
- Tools: [List tool configuration changes]
- Other: [Any other changes]

### Testing
- Test suite results: [Pass/fail counts]
- Manual testing: [Key scenarios tested]
- Issues found: [Problems discovered and fixed]

### Deployment
- Deployed: [Date and time]
- Channels affected: [List]
- Monitoring plan: [How you'll verify success]

### Results
- Metrics impact: [CSAT, escalation rate, etc.]
- Issues encountered: [Problems post-deployment]
- Rollback: [If needed, when and why]
- Learnings: [What you learned]
Commit to Documentation Maintain discipline around documentation:
  • Write version notes immediately after building
  • Update with deployment results within 24 hours
  • Keep notes in shared location (wiki, docs, Git)
  • Make documentation part of deployment process

​
Team Workflows

Single Person Team
  1. Make changes to profile
  2. Test in preview
  3. Build version and set active
  4. Monitor for issues
  5. Document results
Small Team (2-5 People)
  1. Person A makes changes
  2. Person B reviews in preview
  3. Team lead approves build
  4. Person A builds and deploys
  5. Team monitors together
  6. Person A documents
Larger Team (5+ People)
  1. Developer makes changes in profile
  2. QA team runs test suites
  3. Product manager reviews and approves
  4. DevOps builds and deploys
  5. Support team monitors conversations
  6. Developer documents and shares learnings

​
Troubleshooting

Common versioning issues and their solutions.

​
Build Fails

Symptoms
  • “Build failed” error message
  • Build process stops after starting
  • Version doesn’t appear in list
Common Causes
  1. TODO items in configuration
    • Solution: Search for “TODO” in guidance and remove placeholders
  2. No guidance defined
    • Solution: Add at least one active guidance rule with instructions
  3. Invalid tool configuration
    • Solution: Verify JSON syntax in tool configurations
  4. Missing required fields
    • Solution: Check that all required profile fields are filled
  5. Knowledge indexing error
    • Solution: Verify data providers synced successfully before building
Resolution Steps
  1. Review error message for specific cause
  2. Navigate to indicated configuration area
  3. Fix the identified issue
  4. Try building again
  5. Contact support if error persists

​
Knowledge Not Updating

Symptoms
  • New knowledge doesn’t appear in AI responses
  • Staleness indicator shows green but content is outdated
  • Data provider synced but AI doesn’t know new information
Cause Haven’t rebuilt version to incorporate knowledge changes. Resolution
  1. Navigate to Data Providers
  2. Verify sync completed successfully
  3. Check staleness indicator in Behavior → General
  4. If orange, build new version
  5. Set new version as active
  6. Verify AI can access new knowledge
Prevention
  • Build new version after knowledge syncs
  • Check staleness indicator regularly
  • Set up regular rebuild schedule

​
Channels Not Using New Version

Symptoms
  • Some channels show old responses after deployment
  • Version updated but behavior unchanged
  • Inconsistent responses across channels
Checks
  1. Verify production alias updated
    • Navigate to Behavior → General → Versions
    • Check which version has “Production” badge
  2. Confirm channels connected to production alias
    • Navigate to Behavior → General → Channels
    • Verify channels point to correct alias
  3. Clear browser cache (for website widgets)
    • Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
    • Clear site data in browser settings
  4. Check channel configuration
    • Navigate to specific channel settings
    • Verify alias assignment hasn’t changed
Resolution
  • Usually resolves automatically within 1-2 minutes
  • Browser cache clearing often fixes widget issues
  • If persisting beyond 5 minutes, rebuild and redeploy
  • Contact support if issue continues beyond 10 minutes

​
Deployment Stuck

Symptoms
  • Build shows “Building…” for longer than expected
  • No completion notification after 5+ minutes
  • Build progress indicator doesn’t update
Normal Build Times
  • Small projects (minimal knowledge): 30-60 seconds
  • Medium projects (typical knowledge): 1-3 minutes
  • Large projects (extensive knowledge): 3-10 minutes
Resolution Steps Wait appropriate time:
  1. Wait 10 minutes minimum for large projects
  2. Don’t start another build during this time
Check completion:
  1. Refresh page to see if build completed
  2. Check versions list for newly created version
  3. Look for completion notification
If still stuck after 15 minutes:
  1. Try building again (may have timed out)
  2. Check data provider sync status (failed syncs can block builds)
  3. Review browser console for errors
  4. Contact support with project ID and approximate build start time

​
Version Rollback Not Working

Symptoms
  • Set previous version as active but behavior unchanged
  • Rollback appears successful but issues persist
  • Channels still using problematic version
Resolution
  1. Verify version switch completed
    • Check which version has “Production” badge
    • Ensure correct version marked as active
  2. Test in fresh session
    • Start new conversation (don’t use existing chat)
    • Clear browser cache if using web widget
    • Test in different channel to rule out caching
  3. Confirm correct rollback target
    • Verify version you rolled back to was actually working
    • Check version created date matches expected timeframe
    • Review version’s profile name to confirm it’s correct one
  4. Force propagation
    • Set to different version, wait 1 minute
    • Set back to intended version
    • Verify channels update
Prevention
  • Document which versions work well
  • Test rollback target before deploying to all channels
  • Keep notes on version history for quick reference

​
Advanced Patterns

​
Multiple Environment Setup

For teams requiring staging and production separation: Approach: Separate Projects Create two botBrains projects: Staging Project
  • Development and testing environment
  • Copy of production configuration
  • Connected to test channels (test Slack, staging website)
  • Frequent builds and experimentation
  • No real customer traffic
Production Project
  • Live customer environment
  • Only tested changes deployed
  • Connected to customer-facing channels
  • Careful build and deployment process
  • Monitored continuously
Workflow
  1. Make changes in staging project
  2. Build and test in staging
  3. Validate with team
  4. Manually replicate changes to production project
  5. Build and deploy in production
Considerations
  • Requires manual synchronization between projects
  • Doubles configuration effort
  • Provides maximum safety for high-stakes deployments

​
Automated Deployment

For engineering-driven teams: Using the API Automate version building via API: 
# Build a new version
curl -X POST \
  https://api.botbrains.io/v1/projects/{project_id}/deployments \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json"
Integration Patterns Trigger builds on knowledge sync:
  • Data provider completes sync
  • Webhook triggers build API call
  • New version automatically created
  • Notification sent to team
CI/CD pipeline integration:
  • Guidance changes committed to Git
  • CI pipeline runs tests
  • Automated build triggered
  • Deploy only if tests pass
Considerations
  • Requires API access and automation infrastructure
  • Need robust testing to prevent bad automated deployments
  • Benefits teams with frequent updates and technical capability

​
Next Steps

You now understand how versioning protects your AI deployments while enabling continuous improvement. Continue learning:

Deployments Overview

Learn about the complete deployment system including aliases and channels

Testing AI Agents

Build test suites to validate versions before deployment

Integration Channels

Connect your AI to Website, Zendesk, Salesforce, Slack, and more

Monitoring Performance

Track metrics to measure the impact of your deployments
 Versioning transforms AI development from risky to reliable. Use it to build with confidence, test thoroughly, and deliver exceptional customer experiences consistently.