Migration Guide
Smoothly upgrade from legacy versions of SAMMY Three to take advantage of new features and improvements.
Overview
The latest version of SAMMY Three includes significant improvements and new features. This guide will help you migrate your existing implementation.
Breaking Changes Important API changes that require updates
New Features Exciting capabilities to adopt
Deprecations Features being phased out
Version Comparison
What’s New
Audio Processing
Advanced noise suppression with AI-powered filtering and environment presets
Interactive Guides
Built-in walkthrough system with URL activation and progress tracking
MCP Integration
Model Context Protocol support for dynamic tool discovery
Worker Architecture
Improved performance with background workers and CSP compliance
Critical DOM Renders
Automatic capture at conversation boundaries for better context
Migration Steps
Step 1: Update Package
npm uninstall @sammy-labs/sammy-three-legacy
npm install @sammy-labs/sammy-three
Step 2: Update Imports
// ❌ Old
import { SammyAgent } from '@sammy-labs/sammy-three-legacy' ;
// ✅ New
import {
SammyAgentProvider ,
useSammyAgentContext
} from '@sammy-labs/sammy-three' ;
Step 3: Update Configuration
The configuration structure has been updated for better organization.
Old Configuration
New Configuration
const agent = new SammyAgent ({
apiKey: 'your-api-key' ,
apiUrl: 'https://api.example.com' ,
model: 'gemini-1.5' ,
voice: 'default' ,
quality: 'high' ,
debug: true ,
});
Step 4: Update Component Structure
class App extends Component {
constructor () {
this . agent = new SammyAgent ( config );
}
componentDidMount () {
this . agent . connect ();
}
componentWillUnmount () {
this . agent . disconnect ();
}
render () {
return < ChatInterface agent = { this . agent } /> ;
}
}
Step 5: Update Method Calls
Connection
Messaging
Audio
// ❌ Old
agent . connect ();
agent . disconnect ();
// ✅ New
await startAgent ({ agentMode: 'user' });
stopAgent ();
Breaking Changes
Authentication
API keys are no longer supported. You must use JWT tokens for authentication.
// ❌ Old: API Key
const agent = new SammyAgent ({
apiKey: 'sk_live_abc123' ,
});
// ✅ New: JWT Token
const config = {
auth: {
token: 'eyJhbGciOiJIUzI1NiIs...' ,
onTokenExpired : async () => {
const newToken = await refreshToken ();
// Update configuration
},
},
};
Event Handling
Events are now handled through provider callbacks instead of event emitters.
// ❌ Old: Event Emitters
agent . on ( 'error' , handleError );
agent . on ( 'connected' , handleConnected );
agent . on ( 'message' , handleMessage );
// ✅ New: Provider Callbacks
< SammyAgentProvider
onError = { handleError }
onConnectionStateChange = { handleConnectionChange }
onTurnComplete = { handleTurnComplete }
>
Screen Capture
Capture configuration has been restructured.
// ❌ Old
const agent = new SammyAgent ({
capture: true ,
captureQuality: 'high' ,
captureRate: 30 ,
});
// ✅ New
const config = {
captureMethod: 'render' , // or 'video'
captureConfig: {
quality: 0.9 ,
frameRate: 30 ,
enableAudioAdaptation: true ,
},
};
New Features to Adopt
Audio Processing
Take advantage of the new audio processing capabilities:
const config = {
audioConfig: {
noiseSuppression: {
enabled: true ,
enhancementLevel: 'medium' ,
},
noiseGate: {
enabled: true ,
threshold: 0.04 ,
},
environmentPreset: 'office' ,
},
};
Interactive Guides
Implement the new guides system:
import { useGuidesManager } from '@sammy-labs/sammy-three' ;
const guides = useGuidesManager ({
enabled: true ,
authConfig: auth ,
autoStartFromURL: true ,
onStartAgent: startAgent ,
});
// Start a guide
await guides . startWalkthrough ( 'onboarding-v1' );
Enable dynamic tool discovery:
const config = {
mcp: {
enabled: true ,
servers: [{
name: 'hubspot' ,
type: 'sse' ,
sse: {
url: 'https://mcp.example.com/sse' ,
apiKey: process . env . MCP_API_KEY ,
},
}],
},
};
Worker Mode
Enable for better performance:
const config = {
observability: {
enabled: true ,
useWorker: true ,
workerConfig: {
batchSize: 50 ,
batchIntervalMs: 5000 ,
},
},
};
Deprecated Features
Features Being Removed
Direct API Access
Synchronous Methods
Global State
Deprecated: Direct API client access// ❌ Deprecated
agent . api . get ( '/endpoint' );
// ✅ Use API client separately
import { SammyApiClient } from '@sammy-labs/sammy-three' ;
const apiClient = new SammyApiClient ( config );
Common Migration Issues
Issue: Token Expiration
The new version requires proper token refresh handling.
// Solution: Implement token refresh
const config = {
auth: {
token: currentToken ,
onTokenExpired : async () => {
const newToken = await fetch ( '/refresh-token' );
updateConfig ({ auth: { token: newToken } });
},
},
};
Issue: Missing Microphone Permission
Permission handling is now more explicit.
// Solution: Use permission hook
import { useMicrophonePermission } from '@sammy-labs/sammy-three' ;
const { permission , requestPermission } = useMicrophonePermission ();
if ( permission !== 'granted' ) {
await requestPermission ();
}
Issue: Worker Initialization Failed
Some environments may not support workers.
// Solution: Disable workers if needed
const config = {
observability: {
useWorker: false , // Fallback to main thread
},
};
Testing Your Migration
Migration Checklist
Update all package imports
Replace class components with hooks
Update authentication to use JWT tokens
Convert event handlers to callbacks
Test audio in target environments
Verify screen capture works correctly
Test error handling flows
Validate performance improvements
Testing Script
// Test your migration with this script
async function testMigration () {
const tests = {
authentication: false ,
connection: false ,
audio: false ,
capture: false ,
tools: false ,
};
try {
// Test authentication
const auth = await getAuthToken ();
tests . authentication = !! auth ;
// Test connection
const success = await startAgent ({ agentMode: 'user' });
tests . connection = success ;
// Test audio
const { permission } = await checkMicrophonePermission ();
tests . audio = permission === 'granted' ;
// Add more tests...
} catch ( error ) {
console . error ( 'Migration test failed:' , error );
}
console . table ( tests );
}
Support Resources
Version History
Version Release Date Key Changes 3.0.0 2024-01 Complete rewrite with React hooks 2.5.0 2023-12 Added MCP support 2.4.0 2023-11 Audio processing improvements 2.3.0 2023-10 Worker architecture 2.2.0 2023-09 Interactive guides 2.1.0 2023-08 Critical DOM renders 2.0.0 2023-07 JWT authentication