AI Agent Detector Library - Documentation

Overview

The AI Agent Detector is a TypeScript library that recognizes visits from AI agents and identifies which AI client visited your website. It's designed to be a Google Analytics-like tool specifically for tracking AI agent traffic.

Features

• AI Agent Detection: Identifies when a website visitor is an AI agent

• Client Identification: Determines which specific AI client is visiting (ChatGPT, Perplexity, Meta AI, etc.)

• Multi-factor Detection: Uses multiple techniques for more accurate detection

• Confidence Scoring: Provides confidence levels for detection results

• Analytics: Tracks AI agent visits, pages visited, and more

• Extensible: Easy to add new detection techniques and AI agent types

Installation

npm install ai-agent-detector

Basic Usage

import { AIAgentDetector } from 'ai-agent-detector';

// Create detector instance
const detector = new AIAgentDetector();

// Express middleware example
app.use((req, res, next) => {
  const result = detector.detect(req);
  
  if (result.isAIAgent) {
    // Add AI agent info to request
    req.aiAgent = result;
    
    // Log AI agent visit
    console.log(`AI agent detected: ${result.client?.name || 'Unknown'}`);
  }
  
  next();
});

Advanced Configuration

import { 
  AIAgentDetector, 
  DetectionTechniqueType, 
  AIClientType 
} from 'ai-agent-detector';

// Create detector with custom configuration
const detector = new AIAgentDetector({
  confidenceThreshold: 75,
  enabledTechniques: [
    DetectionTechniqueType.USER_AGENT,
    DetectionTechniqueType.IP_RANGE,
    DetectionTechniqueType.BEHAVIORAL
  ],
  enabledAgents: [
    AIClientType.CHATGPT,
    AIClientType.PERPLEXITY,
    AIClientType.GOOGLE_AI
  ],
  collectAnalytics: true
});

// Register custom detection technique
detector.registerTechnique({
  id: 'custom-header-check',
  type: DetectionTechniqueType.CUSTOM,
  weight: 40,
  execute: (request) => {
    const hasSpecificHeader = !!request.headers['x-specific-header'];
    return {
      techniqueId: 'custom-header-check',
      techniqueType: DetectionTechniqueType.CUSTOM,
      detected: hasSpecificHeader,
      confidence: hasSpecificHeader ? 40 : 0
    };
  }
});

Detection Techniques

The library uses multiple techniques to detect AI agents:

1. User-Agent Analysis: Identifies AI agents by their user-agent strings

2. IP Range Verification: Checks if requests come from known AI provider IP ranges

3. Behavioral Analysis: Detects AI agent behavior patterns (JavaScript execution, header patterns, etc.)

Supported AI Clients

• ChatGPT (OpenAI)

• Perplexity

• Meta AI

• Google AI (including Gemini)

• Claude (Anthropic)

• Common Crawl

Analytics

// Get analytics data
const analytics = detector.getAnalytics();

console.log(`Total AI Agent Visits: ${analytics.totalVisits}`);
console.log('Visits by Client:', analytics.visitsByClient);
console.log('Visits by Page:', analytics.visitsByPage);

API Reference

AIAgentDetector

The main class for detecting AI agents.

Methods

• detect(request): Analyzes a request to determine if it's from an AI agent

• configure(options): Updates detector configuration

• registerTechnique(technique): Adds a custom detection technique

• registerAgent(agent): Adds a custom AI agent definition

• startTracking(): Begins collecting analytics data

• stopTracking(): Stops collecting analytics data

• getAnalytics(): Returns collected analytics data

Configuration Options

• confidenceThreshold: Minimum confidence level to consider as an AI agent (0-100)

• enabledTechniques: Array of detection techniques to use

• enabledAgents: Array of AI client types to detect

• collectAnalytics: Whether to collect analytics data

• analyticsStorage: Storage options for analytics data

• customRules: Custom detection rules

Best Practices

1. Use Multiple Detection Techniques: Relying on user-agent alone is not reliable

2. Adjust Confidence Threshold: Set based on your tolerance for false positives/negatives

3. Regular Updates: Keep the library updated as AI agent patterns evolve

4. Custom Techniques: Add your own detection techniques for your specific use case

License

MIT