Laravel Agent Detector — pacchetto per rilevare gli agenti AI

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.

​Introduzione

​Installazione

​Uso di base

​Proprietà di AgentResult

​Elenco degli agenti supportati

​Configurazione di un agente personalizzato

​Casi d’uso pratici

​Rilevare un agente AI in un middleware

​Output di log dettagliati in ambiente agente AI

​Applicare rate limiting alle richieste degli agenti AI

​Modificare il comportamento nei comandi console

​Conclusioni