Weave Code
Agent Detector Laravel Package
laravel/agent-detector
Lightweight PHP 8.2+ utility for detecting when your app is running inside an AI agent or automated dev environment. Provides AgentDetector::detect() and detectAgent(), plus known-agent matching via env vars like AI_AGENT, CURSOR_AGENT, and GEMINI_CLI.
A lightweight PHP utility to detect if your code is running inside an AI agent or automated development environment.
Frequently asked questions about Agent Detector
- How do I install and use Laravel Agent Detector in a Laravel project?
- Run `composer require laravel/agent-detector` to install. Use `AgentDetector::detect()` or the helper `detectAgent()` to check for agents. For Laravel, bind the service in `AppServiceProvider` for global access. Example: `$result = AgentDetector::detect(); if ($result->isAgent) { ... }`
- Which Laravel and PHP versions does this package support?
- The package requires **PHP 8.2+** and works with Laravel 10+. While it’s framework-agnostic, Laravel-specific helpers (like `detectAgent()`) assume Laravel’s service container. Tested with modern Laravel versions but no hard framework version lock.
- Can I detect custom AI agents not listed in the default set?
- Yes. Set the `AI_AGENT` environment variable to any value (e.g., `AI_AGENT=my-custom-agent`). The detector will recognize it as a custom agent. This is useful for internal tools or emerging agents not yet in the known list.
- How accurate is the detection? Will it cause false positives/negatives?
- Detection relies on environment variables (e.g., `CURSOR_AGENT`, `GEMINI_CLI`), which are reliable for most agents. False negatives may occur if an agent doesn’t set these vars, while false positives could happen in rare CI/CD setups. Test thoroughly in your environment.
- Should I use this in production? What are common use cases?
- Yes, it’s production-ready. Common uses include **rate-limiting API calls from agents**, **skipping tests in CI/CD pipelines**, **auditing agent usage**, or **blocking unauthorized agent access**. Avoid using it for critical security decisions without validation.
- How do I integrate this into Laravel middleware to block agents?
- Create middleware like this: `if (detectAgent()->isAgent) { abort(403, 'AI agents not allowed'); }`. Register it in `app/Http/Kernel.php` under `$routeMiddleware`. For global blocking, bind the detector to the container and use it in middleware.
- Does this work in serverless environments (AWS Lambda, Vercel) or Docker?
- Yes, as long as the relevant environment variables (e.g., `CODEX_SANDBOX`) are passed to your container or serverless function. In Docker, ensure vars are set via `-e AI_AGENT=value` or in your `Dockerfile`. Serverless platforms often support this natively.
- How can I test agent detection in CI/CD or locally?
- Mock agent environments by setting vars in your CI (e.g., `export AI_AGENT=github-actions`). Locally, use `.env` files: `AI_AGENT=local-test`. Test edge cases like unset vars or custom agents. Laravel’s `AppServiceProvider` is a good place to add test-specific logic.
- What’s the performance impact of repeated `AgentDetector::detect()` calls?
- Negligible—it only checks environment variables (O(1) operation). For hot paths (e.g., per-request middleware), cache the result in Laravel’s cache or a static variable. Example: `static $agent = null; return $agent ??= AgentDetector::detect();`
- Are there alternatives to this package for AI agent detection?
- For PHP, alternatives are limited. Similar logic could be built manually with `getenv()` checks, but this package provides **structured results**, **known agent enums**, and **Laravel integration**. For other languages, check Python’s `user-agents` or JavaScript’s `navigator.userAgent` (though less precise).
Weaver
How can I help you explore Laravel packages today?