Skip to main content

​
API Reference

Complete reference documentation for all SAMMY Three exports and APIs.

​
Core Components

​
SammyAgentProvider

The main provider component that wraps your application. 
import { SammyAgentProvider } from '@sammy-labs/sammy-three';
​
config
SammyAgentConfigProps
required
Configuration object for the agent
​
tools
ToolDefinition[]
Array of custom tool definitions
​
onError
(error: unknown) => void
Global error handler callback
​
onTokenExpired
() => void
Callback when JWT token expires
​
onTurnComplete
(summary: TurnSummary) => void
Callback after each conversation turn
​
onConnectionStateChange
(connected: boolean) => void
WebSocket connection state changes
​
onMemoryUpdate
(result: unknown) => void
Memory service update notifications
​
onToolCall
(tool: LiveServerToolCall) => void
Tool execution notifications
​
onWalkthroughStart
(walkthroughGuideId: string) => void
Guide walkthrough start callback

​
Core Hooks

​
useSammyAgentContext

Access the agent context and control methods. 
import { useSammyAgentContext } from '@sammy-labs/sammy-three';

const {
  // State
  activeSession,
  agentStatus,
  agentVolume,
  userVolume,
  config,
  error,
  muted,
  screenCapture,
  
  // Methods
  startAgent,
  stopAgent,
  sendMessage,
  toggleMuted,
} = useSammyAgentContext();

​
State Properties

PropertyTypeDescription
activeSessionAgentSession | nullCurrent agent session details
agentStatus'connected' | 'connecting' | 'disconnected' | 'disconnecting'Connection status
agentVolumenumberAgent audio volume (0-1)
userVolumenumberUser audio volume (0-1)
configSammyAgentConfigCurrent configuration
errorError | nullCurrent error state
mutedbooleanMicrophone mute status
screenCaptureScreenCaptureScreen capture instance

​
Methods

  • startAgent
  • stopAgent
  • sendMessage
  • toggleMuted
startAgent(options: StartOptions): Promise<boolean>
Start the agent with specified options.
interface StartOptions {
  agentMode: 'user' | 'admin' | 'sammy';
  sammyThreeOrganisationFeatureId?: string;
  guideId?: string;
}
Returns: Promise<boolean> - Success status

​
Capture Hooks

​
useScreenCapture

Generic screen capture hook. 
import { useScreenCapture } from '@sammy-labs/sammy-three';

const screenCapture = useScreenCapture({
  method: 'render', // or 'video'
  quality: 0.8,
  frameRate: 15,
});

​
useRenderCapture

Render-based capture for web applications. 
import { useRenderCapture } from '@sammy-labs/sammy-three';

const capture = useRenderCapture({
  quality: 0.9,
  selector: '#app', // DOM selector
  interval: 1000,   // ms
});

// Methods
capture.start();
capture.stop();
capture.getLatestFrame();

​
useVideoCapture

Video-based full screen capture. 
import { useVideoCapture } from '@sammy-labs/sammy-three';

const capture = useVideoCapture({
  frameRate: 30,
  resolution: {
    width: 1280,
    height: 720,
  },
});

// Methods
capture.start();
capture.stop();
capture.getStream();

​
Audio Hooks

​
useMicrophonePermission

Manage microphone permissions. 
import { useMicrophonePermission } from '@sammy-labs/sammy-three';

const {
  permission,      // 'granted' | 'denied' | 'prompt' | null
  isChecking,      // boolean
  checkPermission, // () => Promise<void>
  requestPermission, // () => Promise<void>
} = useMicrophonePermission();

​
useAudioProcessing

Configure audio processing. 
import { useAudioProcessing } from '@sammy-labs/sammy-three';

const {
  noiseSuppression,
  noiseGate,
  updateConfig,
} = useAudioProcessing({
  noiseSuppression: {
    enabled: true,
    enhancementLevel: 'medium',
  },
  noiseGate: {
    enabled: true,
    threshold: 0.04,
  },
});

​
Context Hooks

​
useContextUpdater

Automatically update agent context. 
import { useContextUpdater } from '@sammy-labs/sammy-three';

useContextUpdater({
  trackPageChanges: true,
  updateInterval: 5000,
  includeMetadata: true,
  customContext: {
    userId: 'user-123',
    sessionId: 'session-456',
  },
});

​
useMemory

Access and manage memory service. 
import { useMemory } from '@sammy-labs/sammy-three';

const {
  memories,
  addMemory,
  searchMemories,
  deleteMemory,
  clearMemories,
} = useMemory();

// Add memory
await addMemory({
  content: 'User prefers dark mode',
  type: 'preference',
});

// Search memories
const results = await searchMemories('dark mode');

​
Guide Hooks

​
useGuidesManager

Manage interactive guides. 
import { useGuidesManager } from '@sammy-labs/sammy-three';

const guides = useGuidesManager({
  enabled: true,
  authConfig: {
    token: 'jwt-token',
    baseUrl: 'https://api.example.com',
  },
  autoStartFromURL: true,
  onStartAgent: startAgent,
  onWalkthroughStart: (guideId) => {
    console.log('Starting guide:', guideId);
  },
});

// Properties
guides.userGuides;        // Available guides
guides.currentGuide;      // Active guide
guides.isLoading;         // Loading state

// Methods
guides.startWalkthrough(guideId);
guides.markGuideAsCompleted(guideId);
guides.refreshUserGuides();
guides.checkForGuideInUrl();
guides.cleanupUrlParams();

​
useGuidesQueryParams

Handle guide URL parameters. 
import { useGuidesQueryParams } from '@sammy-labs/sammy-three';

const {
  guideId,
  hasGuideParam,
  clearGuideParam,
} = useGuidesQueryParams({
  queryParamName: 'walkthrough', // default
});

​
Core Classes

​
SammyAgentCore

Direct agent core implementation. 
import { SammyAgentCore } from '@sammy-labs/sammy-three';

const agentCore = new SammyAgentCore({
  config: {
    auth: { token: 'jwt-token' },
    captureMethod: 'render',
  },
  tools: [/* custom tools */],
  callbacks: {
    onError: (error) => {},
    onTurnComplete: (summary) => {},
  },
  services: {
    memoryService,
    observabilityService,
  },
});

// Methods
await agentCore.start(options);
agentCore.stop();
agentCore.sendMessage(text);
agentCore.getObservabilityTrace();
agentCore.getObservabilityStatistics();

​
SammyApiClient

API client for backend communication. 
import { SammyApiClient } from '@sammy-labs/sammy-three';

const apiClient = new SammyApiClient({
  token: 'jwt-token',
  baseUrl: 'https://api.example.com',
  onTokenExpired: () => refreshToken(),
});

// Methods
await apiClient.get('/endpoint');
await apiClient.post('/endpoint', data);
await apiClient.put('/endpoint', data);
await apiClient.delete('/endpoint');

​
ScreenCaptureManager

Manage screen capture operations. 
import { ScreenCaptureManager } from '@sammy-labs/sammy-three';

const captureManager = new ScreenCaptureManager({
  method: 'render',
  quality: 0.8,
  frameRate: 15,
  enableAudioAdaptation: true,
});

// Methods
captureManager.start();
captureManager.stop();
captureManager.getFrame();
captureManager.setQuality(0.9);
captureManager.enableAudioMode();

​
ObservabilityManager

Track and manage observability events. 
import { ObservabilityManager } from '@sammy-labs/sammy-three';

const observability = new ObservabilityManager({
  enabled: true,
  useWorker: true,
  workerConfig: {
    batchSize: 50,
    batchIntervalMs: 5000,
  },
  callback: async (event) => {
    await sendToAnalytics(event);
  },
});

// Methods
observability.trackEvent(event);
observability.flush();
observability.getStatistics();
observability.clear();

​
ToolManager

Manage custom and MCP tools. 
import { ToolManager } from '@sammy-labs/sammy-three';

const toolManager = new ToolManager();

// Add custom tool
toolManager.addTool({
  declaration: {
    name: 'myTool',
    description: 'Custom tool',
    parameters: {/* schema */},
  },
  handler: async (call, context) => {
    return { result: 'success' };
  },
});

// Get all tools
const tools = toolManager.getTools();

// Execute tool
const result = await toolManager.executeTool(functionCall);

​
Type Definitions

​
Configuration Types

interface SammyAgentConfigProps {
  auth: {
    token: string;
    baseUrl?: string;
    onTokenExpired?: () => void;
  };
  captureMethod?: 'render' | 'video';
  model?: string;
  debugLogs?: boolean;
  defaultVoice?: string;
  captureConfig?: CaptureConfig;
  audioConfig?: AudioConfig;
  observability?: ObservabilityConfig;
  mcp?: MCPConfig;
  guides?: GuidesConfig;
}

​
Tool Types

interface ToolDefinition {
  declaration: {
    name: string;
    description: string;
    parameters: {
      type: 'object';
      properties: Record<string, any>;
      required?: string[];
    };
  };
  category?: ToolCategory;
  handler: (
    functionCall: FunctionCall,
    context: ToolContext
  ) => Promise<any>;
}

interface ToolContext {
  emit: (event: string, data: any) => void;
  getContext: () => any;
  agentCore: SammyAgentCore;
}

​
Event Types

interface TraceEvent {
  timestamp: number;
  type: string;
  data: any;
  metadata?: {
    sessionId?: string;
    userId?: string;
    [key: string]: any;
  };
}

interface TurnSummary {
  agent: string;
  user: string;
  timestamp: number;
  duration: number;
}

​
Utility Functions

​
Audio Utilities

import { 
  audioContext,
  setupAudioFlushOnUnload,
  audioStutterAnalyzer,
} from '@sammy-labs/sammy-three';

// Get audio context
const ctx = audioContext;

// Setup cleanup on page unload
setupAudioFlushOnUnload();

// Debug audio issues
audioStutterAnalyzer.setDebugMode(true);
audioStutterAnalyzer.getAnalysis();

​
File Utilities

import { saveTextToFile } from '@sammy-labs/sammy-three';

// Save text content to file
saveTextToFile(
  'Hello World',
  'hello.txt',
  'text/plain'
);

​
Service Factories

import { 
  createMemoryServices,
  createCoreServices,
} from '@sammy-labs/sammy-three';

// Create memory service
const memoryService = createMemoryServices(apiClient);

// Create all core services
const services = createCoreServices({
  apiClient,
  config,
});

​
Constants

​
Tool Categories

import { ToolCategories } from '@sammy-labs/sammy-three';

ToolCategories.ACTION    // Action tools
ToolCategories.QUERY     // Query tools
ToolCategories.SYSTEM    // System tools

​
Agent Modes

type AgentMode = 'user' | 'admin' | 'sammy';

​
Connection States

type AgentStatus = 
  | 'connected' 
  | 'connecting' 
  | 'disconnected' 
  | 'disconnecting';

​
Migration Types

For migrating from older versions: 
// Legacy imports (deprecated)
import { SammyAgent } from '@sammy-labs/sammy-three-legacy';

// New imports
import { 
  SammyAgentProvider,
  useSammyAgentContext,
} from '@sammy-labs/sammy-three';

​
Browser Compatibility

​
Required APIs

APIChromeFirefoxSafariEdge
MediaDevices53+36+11+12+
WebRTC23+22+11+12+
Web Workers4+3.5+4+12+
Web Audio14+25+6+12+

​
Optional APIs

APIUsed ForFallback
navigator.deviceMemoryPerformance optimizationDefault to 4GB
navigator.connectionNetwork optimizationDefault to 4G
navigator.hardwareConcurrencyWorker optimizationDefault to 4 cores
⌘I