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

Utilisation de laravel/agent-detector. Présentation du package officiel Laravel qui détecte l’environnement d’exécution des principaux agents IA comme Claude, Copilot ou Cursor.

​

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.