Weave Code
Agent Detector Laravel Package
laravel/agent-detector
Lightweight PHP/Laravel utility to detect when your code runs inside an AI agent or automated dev environment. Detect via AgentDetector::detect() or detectAgent(), identify known agents like Cursor, Gemini, Codex, Claude, or custom via env vars.
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 Laravel Agent Detector in my Laravel project?
- Run `composer require laravel/agent-detector` to install the package. It requires PHP 8.2+ and works with Laravel 10+. No additional configuration is needed for basic usage, though you may register it as a service provider for Laravel-specific integrations.
- Can I use this package outside of Laravel (e.g., in a standalone PHP script)?
- Yes, the package is framework-agnostic. You can use the standalone `detectAgent()` function anywhere PHP 8.2+ runs. Laravel-specific features like service providers or middleware are optional.
- What AI agents does this package detect by default?
- The package detects known agents like Cursor (via `CURSOR_AGENT`), Gemini (`GEMINI_CLI`), Codex (`CODEX_SANDBOX`, `CODEX_CI`), and Claude. You can also detect custom agents by setting the `AI_AGENT` environment variable.
- How do I integrate this into Laravel middleware to detect agents on every request?
- Create a middleware class extending `Closure` or `Handle` and call `AgentDetector::detect()` or `detectAgent()`. Store the result in the request or session, or use it to conditionally modify behavior (e.g., disable caching for AI agents).
- Will this package work in a serverless or containerized PHP environment?
- Yes, the package is lightweight and designed for containerized or serverless deployments. Detection relies on environment variables (e.g., `AI_AGENT`), which are easily set in Docker, Kubernetes, or serverless configurations like AWS Lambda.
- How can I extend this to detect custom or internal AI agents not listed by default?
- Set the `AI_AGENT` environment variable to a custom value (e.g., `AI_AGENT=my-internal-agent`). The package will recognize it as a custom agent. For more complex logic, subclass `AgentDetector` or use middleware to add custom detection rules.
- Are there performance concerns with running `AgentDetector::detect()` on every request?
- The package is optimized for low overhead, but frequent checks in high-throughput systems may add minor latency. For production, consider caching the result (e.g., in the session or Redis) if detection doesn’t change per request.
- How do I test this package in CI/CD to ensure it works in non-agent environments?
- Mock environment variables in your tests (e.g., unset `AI_AGENT`, `CURSOR_AGENT`, etc.) and verify the detector returns `false` for `isAgent`. Use PHPUnit’s `putenv()` or Laravel’s `actingAs()` with environment overrides for testing.
- What happens if I upgrade to Laravel 11 or a newer PHP version? Will this package break?
- The package is maintained by the Laravel team and supports Laravel 10+. For PHP 8.3+, no breaking changes are expected, but always check the [release notes](https://github.com/laravel/agent-detector/releases) for updates. Test thoroughly after upgrades.
- Are there alternatives to this package for detecting AI agents in PHP/Laravel?
- For basic detection, you could manually check environment variables or use regex on `$_SERVER['HTTP_USER_AGENT']`. However, this package offers a maintained, Laravel-native solution with built-in support for known agents and extensibility for custom cases.
Weaver
How can I help you explore Laravel packages today?