Agent Detector Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/agent-detector
   

2. First Use Case: Detect if code is running in an AI environment (e.g., GitHub Copilot, Claude, or Replit) in a single line:

   use Laravel\AgentDetector\AgentDetector;
   
   $result = AgentDetector::detect();
   if ($result->isAgent) {
       // Handle AI-generated execution (e.g., log, skip tests, or adjust behavior)
   }
   

3. Where to Look First:

   • KnownAgent Enum: Reference for supported agents (e.g., KnownAgent::Claude, KnownAgent::Copilot).
   • AgentDetector::AGENT_ENV_VARS: Public constant listing all environment variables used for detection (useful for debugging or custom extensions).

Implementation Patterns

Core Workflows

1. Runtime Detection in Middleware/Service Providers:

   // app/Http/Middleware/DetectAgentMiddleware.php
   public function handle(Request $request, Closure $next) {
       $result = AgentDetector::detect();
       if ($result->knownAgent() === KnownAgent::Copilot) {
           $request->attributes->add(['is_copilot' => true]);
       }
       return $next($request);
   }
   

2. Conditional Logic in Commands/Jobs:

   // app/Console/Commands/GenerateReport.php
   protected function handle() {
       $result = AgentDetector::detect();
       if (!$result->isAgent) {
           $this->generateReport(); // Only run manually
       } else {
           $this->warn("Skipping report generation in AI environment.");
       }
   }
   

3. Testing Integration:

   // tests/Feature/AgentDetectionTest.php
   public function test_agent_detection() {
       putenv('AI_AGENT=github-copilot');
       $result = AgentDetector::detect();
       $this->assertTrue($result->isAgent);
       $this->assertEquals(KnownAgent::Copilot, $result->knownAgent());
   }
   

Integration Tips

• Environment-Specific Config: Use the detection result to load environment-specific configurations (e.g., .env.copilot):

  $result = AgentDetector::detect();
  if ($result->knownAgent() === KnownAgent::Copilot) {
      $this->loadEnvironmentFrom('.env.copilot');
  }
  

• Custom Agents: Extend detection for proprietary tools by setting AI_AGENT:

  AI_AGENT=my-company-ai php artisan my:command
  

• Laravel Service Container: Bind the detector for dependency injection:

  // app/Providers/AppServiceProvider.php
  public function register() {
      $this->app->singleton(AgentDetector::class, fn() => AgentDetector::detect());
  }
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • Some CI/CD environments (e.g., GitHub Actions) may trigger isAgent if they set AI_AGENT. Verify with:

     if ($result->isAgent && !$this->isCiEnvironment()) { ... }
     

2. Namespace Changes (v2.0+):

   • Pre-v2.0 used AgentDetector; v2.0+ uses Laravel\AgentDetector. Update imports if migrating.

3. File-Based Detection (e.g., Devin):

   • Checks like /opt/.devin may fail in Docker/containerized environments. Test locally first.

Debugging

• Inspect Environment Variables:

  dd(AgentDetector::AGENT_ENV_VARS); // List all checked env vars
  

• Custom Detection Logic: Extend AgentDetector by overriding detect() or adding new checks to AGENT_ENV_VARS.

Tips

1. Performance: Cache the detection result if called repeatedly (e.g., in middleware):

   $result = app()->bound('agent_detector') ?? AgentDetector::detect();
   app()->singleton('agent_detector', $result);
   

2. User-Agent Headers: For HTTP-based detection (e.g., browser extensions), combine with Request->userAgent():

   if (str_contains($request->userAgent(), 'AI-Agent')) { ... }
   

3. Testing: Use putenv() to simulate AI environments in tests:

   putenv('CLAUDE_CODE=1');
   $this->assertTrue(AgentDetector::detect()->isAgent);
   

4. Extending Detection: Add new agents by extending the KnownAgent enum and updating AgentDetector::detect():

   // app/Enums/CustomAgent.php
   namespace App\Enums;
   use Laravel\AgentDetector\KnownAgent;
   
   class CustomAgent {
       public static function detect(): ?KnownAgent {
           return env('MY_CUSTOM_AGENT') ? KnownAgent::Custom : null;
       }
   }