> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Agent Detector — AI agent detection package

> How to use laravel/agent-detector. An overview of the official Laravel package that detects execution environments for major AI agents such as Claude, Copilot, and Cursor.

## Introduction

[laravel/agent-detector](https://github.com/laravel/agent-detector) is a lightweight utility for detecting whether PHP code is running inside an AI agent or automated development environment. It was published as an official Laravel package in April 2026.

Now that AI agents are deeply embedded in the development workflow, it has become important to know what environment your code is running in. Real-world cases include adjusting log verbosity or rate limits depending on whether a request comes from an AI agent or a human, or returning agent-specific responses.

```mermaid theme={null}
graph TD
    A["AgentDetector::detect()"] --> B{"AI_AGENT<br>env var set?"}
    B -->|Yes| C["Return as custom or<br>known agent"]
    B -->|No| D{"Known env var<br>set?"}
    D -->|Yes| E["Return as the matching<br>KnownAgent"]
    D -->|No| F{"/opt/.devin<br>file exists?"}
    F -->|Yes| G["Return as<br>KnownAgent::Devin"]
    F -->|No| H["isAgent: false<br>(no agent)"]
```

## Installation

```bash theme={null}
composer require laravel/agent-detector
```

Requires PHP 8.2 or later.

## Basic usage

Calling `AgentDetector::detect()` returns an `AgentResult` object.

```php theme={null}
use Laravel\AgentDetector\AgentDetector;
use Laravel\AgentDetector\KnownAgent;

$result = AgentDetector::detect();

if ($result->isAgent) {
    echo "Running inside: {$result->name}";
}

// Check for a specific agent
if ($result->knownAgent() === KnownAgent::Claude) {
    echo "Hello from Claude!";
}
```

You can also use the standalone function:

```php theme={null}
use function Laravel\AgentDetector\detectAgent;

$result = detectAgent();
```

### AgentResult properties

| Property / method       | Type          | Description                                            |
| ----------------------- | ------------- | ------------------------------------------------------ |
| `$result->isAgent`      | `bool`        | `true` if running inside an AI agent                   |
| `$result->name`         | `?string`     | Agent name (e.g. `"claude"`). `null` if not an agent   |
| `$result->knownAgent()` | `?KnownAgent` | Returns a `KnownAgent` enum. `null` for unknown agents |

## Supported agents

| Agent          | Detection method (env var / file)                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Custom         | `AI_AGENT` env var (any value)                                                                                                        |
| GitHub Copilot | `AI_AGENT=github-copilot`, `AI_AGENT=github-copilot-cli`, `COPILOT_MODEL`, `COPILOT_ALLOW_ALL`, `COPILOT_GITHUB_TOKEN`, `COPILOT_CLI` |
| Cursor         | `CURSOR_AGENT`                                                                                                                        |
| Claude         | `CLAUDECODE` or `CLAUDE_CODE`                                                                                                         |
| Cowork         | `CLAUDE_CODE_IS_COWORK` (set alongside `CLAUDECODE` or `CLAUDE_CODE`)                                                                 |
| Gemini         | `GEMINI_CLI`                                                                                                                          |
| Codex          | `CODEX_SANDBOX`, `CODEX_CI`, `CODEX_THREAD_ID`                                                                                        |
| Augment CLI    | `AUGMENT_AGENT`                                                                                                                       |
| AMP            | `AMP_CURRENT_THREAD_ID`                                                                                                               |
| Opencode       | `OPENCODE_CLIENT` or `OPENCODE`                                                                                                       |
| Replit         | `REPL_ID`                                                                                                                             |
| Devin          | The `/opt/.devin` file exists                                                                                                         |
| Antigravity    | `ANTIGRAVITY_AGENT`                                                                                                                   |
| Pi             | `PI_CODING_AGENT`                                                                                                                     |
| Kiro CLI       | `KIRO_AGENT_PATH`                                                                                                                     |
| v0             | `AI_AGENT=v0`                                                                                                                         |

Detection priority is: `AI_AGENT` env var → known env vars → filesystem.

## Configuring custom agents

Set any value in the `AI_AGENT` environment variable to have it detected as a custom agent.

```bash theme={null}
AI_AGENT=my-custom-agent php your-script.php
```

```php theme={null}
$result = AgentDetector::detect();

// $result->isAgent === true
// $result->name    === 'my-custom-agent'
// $result->knownAgent() === null (unknown agent)
```

## Practical use cases

### Detect AI agents in middleware

Use Laravel middleware to determine the execution environment and branch to agent-specific behavior.

```php theme={null}
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Laravel\AgentDetector\AgentDetector;

class DetectAiAgent
{
    public function handle(Request $request, Closure $next): mixed
    {
        $agent = AgentDetector::detect();

        if ($agent->isAgent) {
            // Set the agent name on the request attributes
            $request->attributes->set('ai_agent', $agent->name);
        }

        return $next($request);
    }
}
```

### Emit verbose logs in AI agent environments

```php theme={null}
use Laravel\AgentDetector\AgentDetector;
use Illuminate\Support\Facades\Log;

$agent = AgentDetector::detect();

if ($agent->isAgent) {
    Log::withContext(['ai_agent' => $agent->name])
        ->debug('Agent request received', $request->all());
} else {
    Log::info('User request received');
}
```

### Apply rate limits to requests from AI agents

By varying the `ThrottleRequests` middleware key based on agent detection, you can set different rate limits for agents and humans.

```php theme={null}
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Routing\Middleware\ThrottleRequests;
use Laravel\AgentDetector\AgentDetector;

class ThrottleByAiAgent
{
    public function handle(Request $request, Closure $next): mixed
    {
        $agent = AgentDetector::detect();

        // 10 requests per minute for AI agents, 60 for humans
        $maxAttempts = $agent->isAgent ? 10 : 60;

        return app(ThrottleRequests::class)->handle(
            $request,
            $next,
            $maxAttempts,
        );
    }
}
```

### Switch behavior in console commands

An example of emitting detailed progress when an agent runs an Artisan command.

```php theme={null}
use Laravel\AgentDetector\AgentDetector;

public function handle(): void
{
    $agent = AgentDetector::detect();

    if ($agent->isAgent) {
        $this->info("Running in {$agent->name} environment — verbose mode enabled.");
    }

    // Processing...
}
```

## Summary

`laravel/agent-detector` bundles simple environment variable checks and filesystem inspection into a single package. Just call `AgentDetector::detect()`—no complex configuration required.

As AI agents become an established part of the development flow, understanding "who (or what) is running your code" only grows in importance. This package can be useful in many scenarios such as logging, rate limiting, and customizing responses.

<Card title="laravel/agent-detector repository" icon="github" href="https://github.com/laravel/agent-detector">
  Source code and the latest list of supported agents.
</Card>


## Related topics

- [Laravel PAO — output optimization for AI agents](/en/blog/pao-introduction.md)
- [laravel/agent-skills — Laravel's official AI agent skills](/en/blog/agent-skills-introduction.md)
- [Creating a Custom Agent for Boost](/en/advanced/boost-custom-agent.md)
- [Custom agents](/en/packages/laravel-copilot-sdk/custom-agents.md)
- [Laravel AI SDK](/en/ai-sdk.md)