A TypeScript library that recognizes visits from AI agents and identifies which AI client visited
npm install ai-agent-detectorThe 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.
- 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
``bash`
npm install ai-agent-detector
`typescript
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();
});
`typescript
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
};
}
});
`
The library uses multiple techniques to detect AI agents:
1. User-Agent Analysis: Identifies AI agents by their user-agent strings
1. IP Range Verification: Checks if requests come from known AI provider IP ranges
1. Behavioral Analysis: Detects AI agent behavior patterns (JavaScript execution, header patterns, etc.)
- ChatGPT (OpenAI)
- Perplexity
- Meta AI
- Google AI (including Gemini)
- Claude (Anthropic)
- Common Crawl
`typescript
// 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);
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
1. Use Multiple Detection Techniques: Relying on user-agent alone is not reliable
1. Adjust Confidence Threshold: Set based on your tolerance for false positives/negatives
1. Regular Updates: Keep the library updated as AI agent patterns evolve
1. Custom Techniques: Add your own detection techniques for your specific use case
MIT