Configuration Options

Superline Agent Detection provides various configuration options to customize its behavior according to your needs. This page details all available configuration options passed to the AgentDetector.init() method. For constructor options (metadataProvider, eventsProvider, eventStorage, throttleConfig), see the AgentDetector constructor documentation.

AgentDetectorInitOptions

The configuration object passed to the AgentDetector.init() method.

debug

boolean

default:"false"

Enables debug mode, which:

Logs detailed information about the detection process to the console
Includes raw extracted features in the detection result
Provides more verbose error messages

Useful during development and troubleshooting, but should be disabled in production.

AgentDetector.init({ debug: true });

autoStart

boolean

default:"true"

Determines whether the detection process should start automatically after initialization.

When true, event listeners are attached and data collection begins immediately
When false, you need to call AgentDetector.startDetection() manually to begin collection

// Initialize without starting
AgentDetector.init({ autoStart: false });

// Later, start manually
AgentDetector.startDetection();

extractorClasses

ExtractorClass[]

Array of custom feature extractor classes to use instead of the default ones. Defaults to DEFAULT_EXTRACTORS.Each extractor class must extend the FeatureExtractor base class (or similar) and be provided as a constructor.

import AgentDetector from '@superline-ai/agent-detection';
import CustomExtractor from './my-custom-extractor';

AgentDetector.init({
  extractorClasses: [CustomExtractor]
});

Show Custom Extractor Structure (Conceptual)

import { FeatureExtractor } from '@superline-ai/agent-detection'; // Assuming path

export class CustomExtractor extends FeatureExtractor {
  constructor(metadataProvider, eventsProvider) {
    super(metadataProvider, eventsProvider, 'custom');
  }
  
  initialize() {
    // Setup event listeners or initialize data
    return true;
  }
  
  cleanup() {
    // Remove event listeners or cleanup
  }
  
  extractFeatures() {
    // Return extracted features
    return {
      hasData: true,
      error: false,
      features: {
         myFeature1: 0.75,
         myFeature2: 'value'
      }
    };
  }
}

onDetection

(result: DetectionResult) => void

Callback function invoked when detection results are available, typically after calling finalizeDetection() or getCurrentDetectionResult().

function handleDetection(result) {
   console.log(`Detected agent: ${result.isAgent}, Confidence: ${result.confidence}`);
}

AgentDetector.init({
  onDetection: handleDetection
});

throttleConfig

ThrottleConfig

Overrides the throttle configuration provided in the constructor for this instance. Used to control the rate at which high-frequency events (like mouse movements) are processed.

Show ThrottleConfig properties

mouseMoveThrottleMs

number

default:"50"

Minimum time in milliseconds between processing mouse move events.

scrollThrottleMs

number

default:"100"

Minimum time in milliseconds between processing scroll events.

keyboardThrottleMs

number

default:"20"

Minimum time in milliseconds between processing keyboard events.

clickThrottleMs

number

default:"10"

Minimum time in milliseconds between processing click events.

AgentDetector.init({
  throttleConfig: {
    mouseMoveThrottleMs: 100, // Sample mouse moves less frequently
    scrollThrottleMs: 150
  }
});

threshold

number

default:"0.5"

The probability threshold (0-1) for classifying a session as an AI agent.

If the calculated probability confidence is >= threshold, isAgent will be true
If the confidence is < threshold, isAgent will be false

Adjusting this threshold lets you control the balance between false positives and false negatives based on the confidence value.

// More strict classification (fewer false positives, more false negatives)
AgentDetector.init({ threshold: 0.7 });

// More lenient classification (more false positives, fewer false negatives)
AgentDetector.init({ threshold: 0.3 });

Configuration Examples

// Initialize with default options
AgentDetector.init();

Best Practices

Production vs. Development

Use debug: true during development to diagnose issues and inspect features.
Ensure debug: false in production for optimal performance and cleaner logs.

Performance Considerations

Using default extractors and throttle settings provides a good balance.
If performance issues arise on low-end devices, consider increasing throttleConfig values (e.g., mouseMoveThrottleMs) to reduce processing load.
Providing only necessary custom extractors via extractorClasses can also improve performance if default ones are not needed.

Threshold Adjustment

The default threshold (0.5) used to set isAgent works well for many applications.
You can adjust this threshold using the threshold option in init().
Increase threshold (e.g., 0.7) if false positives (humans marked as agents) are problematic.
Decrease threshold (e.g., 0.3) if false negatives (agents marked as humans) are problematic.
Consider your application’s specific needs and tolerance for misclassification when adjusting.
Always analyze the raw confidence in your analytics for the most nuanced understanding.

Extractor Management

By default, the library uses a set of core extractors (DEFAULT_EXTRACTORS).

Providing extractorClasses replaces the default set entirely. If you want to add to the defaults, you need to explicitly include the defaults in your array:

import { DEFAULT_EXTRACTORS } from '@superline-ai/agent-detection';
import MyCustomExtractor from './my-custom-extractor';

AgentDetector.init({
  extractorClasses: [...DEFAULT_EXTRACTORS, MyCustomExtractor]
});

Get Started

Core Concepts

API Reference

Configuration

Configuration Options

AgentDetectorInitOptions

Configuration Examples

Best Practices

Next Steps

Agent Detector

Detection Result

Get Started

Core Concepts

API Reference

​Configuration Options

​AgentDetectorInitOptions

​Configuration Examples

​Best Practices

​Next Steps

Agent Detector

Detection Result

Configuration Options

AgentDetectorInitOptions

Configuration Examples

Best Practices

Next Steps