Agent Detector Laravel Package

Getting Started

Install via Composer:

composer require laravel/agent-detector

First use case: Detect AI agents in your Laravel application's AppServiceProvider boot method or middleware:

use Laravel\AgentDetector\AgentDetector;

public function boot()
{
    $result = AgentDetector::detect();

    if ($result->isAgent) {
        Log::info("Running in AI environment: {$result->name}");
        // Customize behavior for AI agents
    }
}

Key starting points:

1. AgentDetector::detect() - Core detection method
2. detectAgent() - Standalone function alias
3. KnownAgent enum - Predefined agent types
4. AgentResult object - Contains detection results

Implementation Patterns

Core Detection Workflow

// Basic detection
$result = AgentDetector::detect();

// Check for any agent
if ($result->isAgent) {
    // Agent detected
}

// Check specific agent
if ($result->knownAgent() === KnownAgent::Claude) {
    // Claude-specific logic
}

Middleware Integration

public function handle(Request $request, Closure $next)
{
    $result = AgentDetector::detect();

    if ($result->isAgent && $result->knownAgent() === KnownAgent::Copilot) {
        return response()->json(['message' => 'Copilot detected'], 403);
    }

    return $next($request);
}

Service Provider Integration

public function register()
{
    $this->app->singleton('agent-detector', function () {
        return AgentDetector::detect();
    });
}

Custom Agent Handling

// Set environment variable
putenv('AI_AGENT=my-custom-agent');

// Or in .env
// AI_AGENT=my-custom-agent

// Then detect
$result = AgentDetector::detect();
if ($result->name === 'my-custom-agent') {
    // Custom logic
}

Testing Patterns

// In PHPUnit tests
public function testAgentDetection()
{
    putenv('AI_AGENT=github-copilot');

    $result = AgentDetector::detect();
    $this->assertTrue($result->isAgent);
    $this->assertEquals(KnownAgent::Copilot, $result->knownAgent());
}

Gotchas and Tips

Common Pitfalls

1. Environment Variables: Detection relies on environment variables. Ensure they're properly set in your deployment environment.

   # Example for testing
   AI_AGENT=github-copilot php artisan tinker
   

2. Namespace Changes: v2.0.0 changed namespace from AgentDetector to Laravel\AgentDetector. Update imports if migrating.

3. False Positives: Some environments might trigger multiple detection methods. Verify with AgentDetector::AGENT_ENV_VARS:

   print_r(AgentDetector::AGENT_ENV_VARS);
   

4. Performance: Detection is lightweight but not free. Cache results if checking frequently:

   $result = cache()->remember('agent-detection', now()->addHours(1), function() {
       return AgentDetector::detect();
   });
   

Debugging Tips

1. Inspect Detection Logic:

   $result = AgentDetector::detect();
   dd($result->name, $result->isAgent, $result->knownAgent());
   

2. Check All Environment Variables:

   foreach (AgentDetector::AGENT_ENV_VARS as $var) {
       echo "$var = " . getenv($var) . "\n";
   }
   

3. Custom Detection: Extend the detector by creating a custom class:

   class CustomAgentDetector extends AgentDetector
   {
       protected static function detectCustomAgent(): ?string
       {
           return getenv('MY_CUSTOM_VAR') ? 'my-custom-agent' : null;
       }
   }
   

Configuration Quirks

1. KnownAgent Enum: Use label() method for human-readable names:

   echo KnownAgent::Claude->label(); // "Claude"
   

2. AgentResult Properties:

   • isAgent: Boolean indicating if any agent detected
   • name: String name of detected agent
   • knownAgent(): Returns KnownAgent enum if matches known agents

3. Environment Variable Priority: The detector checks variables in a specific order. Newer agents may override older ones.

Extension Points

1. Add New Agent Detection:

   // In a service provider
   AgentDetector::addDetectionMethod(function() {
       return getenv('NEW_AGENT_VAR') ? 'new-agent' : null;
   });
   

2. Custom Agent Detection Class:

   class MyAgentDetector extends AgentDetector
   {
       public static function detect(): AgentResult
       {
           $result = parent::detect();
   
           if ($result->name === 'custom') {
               // Custom logic
           }
   
           return $result;
       }
   }
   

3. Override Detection Logic:

   // Monkeypatch for testing
   AgentDetector::setDetectionMethods([...]);