Laravel Agent Detector — AI agent detection package

Introduction

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.

Installation

composer require laravel/agent-detector

Requires PHP 8.2 or later.

Basic usage

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

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:

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.

AI_AGENT=my-custom-agent php your-script.php

$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

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

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

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.

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.

laravel/agent-detector repository

Source code and the latest list of supported agents.

Changelog

Laravel 13

Products

Package Introductions

New Repository Research

Upgrade Guides

Authentication

Frontend

Environment Setup

Laravel Agent Detector — AI agent detection package

Introduction

Installation

Basic usage

AgentResult properties

Supported agents

Configuring custom agents

Practical use cases

Detect AI agents in middleware

Emit verbose logs in AI agent environments

Apply rate limits to requests from AI agents

Switch behavior in console commands

Summary

laravel/agent-detector repository

​Introduction

​Installation

​Basic usage

​AgentResult properties

​Supported agents

​Configuring custom agents

​Practical use cases

​Detect AI agents in middleware

​Emit verbose logs in AI agent environments

​Apply rate limits to requests from AI agents

​Switch behavior in console commands

​Summary

laravel/agent-detector repository

Introduction

Installation

Basic usage

AgentResult properties

Supported agents

Configuring custom agents

Practical use cases

Detect AI agents in middleware

Emit verbose logs in AI agent environments

Apply rate limits to requests from AI agents

Switch behavior in console commands

Summary