Laravel Agent Detector — pacchetto per rilevare gli agenti AI

Come usare laravel/agent-detector. Descrizione del pacchetto ufficiale Laravel che rileva gli ambienti di esecuzione dei principali agenti AI come Claude, Copilot e Cursor.

​

Introduzione

laravel/agent-detector è una utility leggera per rilevare se il codice PHP viene eseguito all’interno di un agente AI o di un ambiente di sviluppo automatizzato. È stato pubblicato come pacchetto ufficiale Laravel ad aprile 2026.

Ora che gli agenti AI sono entrati profondamente nel processo di sviluppo, è diventato importante sapere in quale ambiente sta girando il codice stesso. Nello sviluppo reale sorgono casi in cui è utile modificare il livello di dettaglio dei log o i rate limit a seconda che la richiesta provenga da un agente AI o da un essere umano, oppure restituire risposte specifiche per gli agenti.

​

Installazione

composer require laravel/agent-detector

È richiesto PHP 8.2 o superiore.

​

Uso di base

Chiamando AgentDetector::detect() viene restituito un oggetto AgentResult.

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

$result = AgentDetector::detect();

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

// Verifica un agente specifico
if ($result->knownAgent() === KnownAgent::Claude) {
    echo "Hello from Claude!";
}

È disponibile anche una scrittura con funzione standalone.

use function Laravel\AgentDetector\detectAgent;

$result = detectAgent();

​

Proprietà di AgentResult

Proprietà / Metodo	Tipo	Descrizione
$result->isAgent	bool	true se in esecuzione all’interno di un agente AI
$result->name	?string	Nome dell’agente (es. "claude"). null se non è un agente
$result->knownAgent()	?KnownAgent	Restituisce l’enum KnownAgent. null per agenti sconosciuti

​

Elenco degli agenti supportati

Agente	Metodo di rilevamento (variabile d’ambiente / file)
Custom	Variabile d’ambiente AI_AGENT (qualsiasi valore)
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 o CLAUDE_CODE
Cowork	CLAUDE_CODE_IS_COWORK (impostata insieme a CLAUDECODE o 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 o OPENCODE
Replit	REPL_ID
Devin	Esistenza del file /opt/.devin
Antigravity	ANTIGRAVITY_AGENT
Pi	PI_CODING_AGENT
Kiro CLI	KIRO_AGENT_PATH
v0	AI_AGENT=v0

L’ordine di priorità del rilevamento è: variabile d’ambiente AI_AGENT → variabili d’ambiente note → filesystem.

​

Configurazione di un agente personalizzato

Impostando un valore qualsiasi nella variabile d’ambiente AI_AGENT, può essere rilevato come agente personalizzato.

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

$result = AgentDetector::detect();

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

​

Casi d’uso pratici

​

Rilevare un agente AI in un middleware

Determina l’ambiente di esecuzione in un middleware Laravel e biforca l’elaborazione per gli agenti.

<?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) {
            // Imposta il nome dell'agente come attributo della richiesta
            $request->attributes->set('ai_agent', $agent->name);
        }

        return $next($request);
    }
}

​

Output di log dettagliati in ambiente agente AI

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

​

Applicare rate limiting alle richieste degli agenti AI

Modificando la chiave del middleware ThrottleRequests in base al rilevamento dell’agente, puoi definire rate limit diversi per agenti ed esseri umani.

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

        // Gli agenti AI: 10 richieste al minuto; gli umani: 60
        $maxAttempts = $agent->isAgent ? 10 : 60;

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

​

Modificare il comportamento nei comandi console

Esempio di output di un avanzamento dettagliato quando un agente esegue un comando Artisan.

use Laravel\AgentDetector\AgentDetector;

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

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

    // Elaborazione...
}

​

Conclusioni

laravel/agent-detector è un pacchetto che raggruppa semplici controlli di variabili d’ambiente e ispezioni del filesystem. Si usa semplicemente chiamando AgentDetector::detect() senza configurazioni complesse.

Ora che gli agenti AI si stanno consolidando come parte del flusso di sviluppo, sapere “da chi (o cosa) viene eseguito il codice” diventerà sempre più importante. Questo pacchetto potrà essere sfruttato in molte situazioni, come log, rate limiting e personalizzazione delle risposte.

Repository laravel/agent-detector

Trovi qui il codice sorgente e l’elenco aggiornato degli agenti supportati.