Skip to main content

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

  • Components
  • Styles
  • Types
// ❌ 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.
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');

MCP Tools

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

VersionRelease DateKey Changes
3.0.02024-01Complete rewrite with React hooks
2.5.02023-12Added MCP support
2.4.02023-11Audio processing improvements
2.3.02023-10Worker architecture
2.2.02023-09Interactive guides
2.1.02023-08Critical DOM renders
2.0.02023-07JWT authentication
I