Laravel Agent Detector — package de détection d'agents IA

Introduction

laravel/agent-detector est un utilitaire léger permettant de détecter si du code PHP s’exécute au sein d’un agent IA ou d’un environnement de développement automatisé. Il a été publié en avril 2026 en tant que package officiel Laravel. Alors que les agents IA se sont profondément infiltrés dans le quotidien du développement, il devient important de savoir dans quel environnement le code lui-même s’exécute. Sur le terrain, on rencontre des cas où il faut ajuster la verbosité des logs ou la limitation de débit selon qu’une requête vient d’un agent IA ou d’un humain, ou encore renvoyer des réponses spécifiques aux agents.

Installation

composer require laravel/agent-detector

PHP 8.2 ou supérieur est requis.

Utilisation de base

L’appel de AgentDetector::detect() retourne un objet AgentResult.

use Laravel\AgentDetector\AgentDetector;
use Laravel\AgentDetector\KnownAgent;

$result = AgentDetector::detect();

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

// Vérifier un agent spécifique
if ($result->knownAgent() === KnownAgent::Claude) {
    echo "Hello from Claude!";
}

Il existe également une écriture utilisant une fonction autonome.

use function Laravel\AgentDetector\detectAgent;

$result = detectAgent();

Propriétés de AgentResult

Propriété / Méthode	Type	Description
`$result->isAgent`	`bool`	`true` si l’exécution a lieu dans un agent IA
`$result->name`	`?string`	Nom de l’agent (ex. `"claude"`). `null` s’il ne s’agit pas d’un agent
`$result->knownAgent()`	`?KnownAgent`	Renvoie l’enum `KnownAgent`. `null` pour un agent inconnu

Liste des agents pris en charge

Agent	Méthode de détection (variables d’env / fichiers)
Custom	Variable d’environnement `AI_AGENT` (n’importe quelle valeur)
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` ou `CLAUDE_CODE`
Cowork	`CLAUDE_CODE_IS_COWORK` (défini en même temps que `CLAUDECODE` ou `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` ou `OPENCODE`
Replit	`REPL_ID`
Devin	Présence du fichier `/opt/.devin`
Antigravity	`ANTIGRAVITY_AGENT`
Pi	`PI_CODING_AGENT`
Kiro CLI	`KIRO_AGENT_PATH`
v0	`AI_AGENT=v0`

L’ordre de priorité de détection est : variable d’environnement AI_AGENT → variables d’environnement connues → système de fichiers.

Configurer un agent personnalisé

En attribuant une valeur quelconque à la variable d’environnement AI_AGENT, il est possible de détecter un agent personnalisé.

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

$result = AgentDetector::detect();

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

Cas d’usage concrets

Détecter un agent IA dans un middleware

On détermine l’environnement d’exécution dans un middleware Laravel et on adapte le traitement en fonction de l’agent.

<?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) {
            // Enregistrer le nom de l'agent dans les attributs de la requête
            $request->attributes->set('ai_agent', $agent->name);
        }

        return $next($request);
    }
}

Produire des logs détaillés dans un environnement d’agent IA

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');
}

Appliquer une limitation de débit aux requêtes des agents IA

En faisant varier la clé du middleware ThrottleRequests selon la détection d’agent, on peut appliquer des limites différentes aux agents et aux humains.

<?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();

        // Agents IA : 10 requêtes/min ; humains : 60 requêtes/min
        $maxAttempts = $agent->isAgent ? 10 : 60;

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

Adapter le comportement d’une commande console

Exemple d’affichage d’un rapport de progression détaillé lorsqu’une commande Artisan est exécutée par un agent.

use Laravel\AgentDetector\AgentDetector;

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

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

    // Traitement...
}

Conclusion

laravel/agent-detector est un package qui regroupe une simple vérification de variables d’environnement et une inspection du système de fichiers. Aucune configuration complexe n’est nécessaire : il suffit d’appeler AgentDetector::detect(). Alors que les agents IA s’installent durablement dans le flux de développement, il devient de plus en plus important de savoir « qui (ou quoi) exécute le code ». Ce package se révélera utile dans de nombreux contextes : logs, limitation de débit, personnalisation des réponses, etc.

Dépôt laravel/agent-detector

Le code source et la liste à jour des agents pris en charge se trouvent ici.

​Introduction

​Installation

​Utilisation de base

​Propriétés de AgentResult

​Liste des agents pris en charge

​Configurer un agent personnalisé

​Cas d’usage concrets

​Détecter un agent IA dans un middleware

​Produire des logs détaillés dans un environnement d’agent IA

​Appliquer une limitation de débit aux requêtes des agents IA

​Adapter le comportement d’une commande console

​Conclusion