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

```mermaid theme={null}
graph TD
    A["AgentDetector::detect()"] --> B{"Variable d'env<br>AI_AGENT présente ?"}
    B -->|Yes| C["Renvoie comme agent<br>personnalisé ou connu"]
    B -->|No| D{"Variable d'env<br>connue présente ?"}
    D -->|Yes| E["Renvoie le KnownAgent<br>correspondant"]
    D -->|No| F{"Fichier /opt/.devin<br>présent ?"}
    F -->|Yes| G["Renvoie KnownAgent::Devin"]
    F -->|No| H["isAgent: false<br>(aucun agent)"]
```

## Installation

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

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

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

```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 (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 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) {
            // 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

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

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

        // 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.

```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.");
    }

    // 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.

<Card title="Dépôt laravel/agent-detector" icon="github" href="https://github.com/laravel/agent-detector">
  Le code source et la liste à jour des agents pris en charge se trouvent ici.
</Card>


## Related topics

- [laravel/agent-skills — la collection officielle de skills d'agents IA Laravel](/fr/blog/agent-skills-introduction.md)
- [Créer un agent personnalisé pour Boost](/fr/advanced/boost-custom-agent.md)
- [Laravel PAO — outil d'optimisation des sorties pour les agents IA](/fr/blog/pao-introduction.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/fr/packages/laravel-boost-phpstorm-copilot.md)
- [Laravel et le développement IA](/fr/ai.md)