> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/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.

```mermaid theme={null}
graph TD
    A["AgentDetector::detect()"] --> B{"AI_AGENT<br>variabile d'ambiente presente?"}
    B -->|Yes| C["restituisce come agente<br>custom o noto"]
    B -->|No| D{"variabile d'ambiente<br>nota presente?"}
    D -->|Yes| E["restituisce il KnownAgent<br>corrispondente"]
    D -->|No| F{"file /opt/.devin<br>presente?"}
    F -->|Yes| G["restituisce come<br>KnownAgent::Devin"]
    F -->|No| H["isAgent: false<br>(nessun agente)"]
```

## Installazione

```bash theme={null}
composer require laravel/agent-detector
```

È richiesto PHP 8.2 o superiore.

## Uso di base

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

```php theme={null}
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.

```php theme={null}
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.

```bash theme={null}
AI_AGENT=my-custom-agent php your-script.php
```

```php theme={null}
$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 theme={null}
<?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

```php theme={null}
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 theme={null}
<?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.

```php theme={null}
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.

<Card title="Repository laravel/agent-detector" icon="github" href="https://github.com/laravel/agent-detector">
  Trovi qui il codice sorgente e l'elenco aggiornato degli agenti supportati.
</Card>


## Related topics

- [laravel/agent-skills — la raccolta ufficiale di skill per agenti AI di Laravel](/it/blog/agent-skills-introduction.md)
- [Laravel PAO — strumento di ottimizzazione dell'output per agenti AI](/it/blog/pao-introduction.md)
- [Agenti personalizzati](/it/packages/laravel-copilot-sdk/custom-agents.md)
- [Laravel Package Skeleton — template starter per pacchetti ufficiali](/it/blog/package-skeleton-introduction.md)
- [Creare un agente personalizzato per Boost](/it/advanced/boost-custom-agent.md)