> ## 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 — Paquete de detección de agentes de IA

> Cómo usar laravel/agent-detector. Explicación del paquete oficial de Laravel que detecta el entorno de ejecución de los principales agentes de IA como Claude, Copilot y Cursor.

## Introducción

[laravel/agent-detector](https://github.com/laravel/agent-detector) es una utilidad ligera para detectar si el código PHP se está ejecutando dentro de un agente de IA o de un entorno de desarrollo automatizado. Se publicó como paquete oficial de Laravel en abril de 2026.

Ahora que los agentes de IA están profundamente integrados en el trabajo de desarrollo, resulta importante conocer en qué entorno se está ejecutando el propio código. En el desarrollo real surgen casos como cambiar el nivel de detalle de los logs o los límites de tasa según si la petición proviene de un agente de IA o de un humano, o devolver respuestas específicas para agentes.

```mermaid theme={null}
graph TD
    A["AgentDetector::detect()"] --> B{"¿Variable de entorno<br>AI_AGENT presente?"}
    B -->|Sí| C["Devolver como agente<br>personalizado o conocido"]
    B -->|No| D{"¿Variables de entorno<br>conocidas presentes?"}
    D -->|Sí| E["Devolver como<br>KnownAgent correspondiente"]
    D -->|No| F{"¿Existe el archivo<br>/opt/.devin?"}
    F -->|Sí| G["Devolver como<br>KnownAgent::Devin"]
    F -->|No| H["isAgent: false<br>(ningún agente)"]
```

## Instalación

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

Se requiere PHP 8.2 o superior.

## Uso básico

Al llamar a `AgentDetector::detect()` se devuelve un objeto `AgentResult`.

```php theme={null}
use Laravel\AgentDetector\AgentDetector;
use Laravel\AgentDetector\KnownAgent;

$result = AgentDetector::detect();

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

// Comprobar un agente específico
if ($result->knownAgent() === KnownAgent::Claude) {
    echo "Hello from Claude!";
}
```

También existe una versión con función independiente.

```php theme={null}
use function Laravel\AgentDetector\detectAgent;

$result = detectAgent();
```

### Propiedades de AgentResult

| Propiedad / Método      | Tipo          | Descripción                                                      |
| ----------------------- | ------------- | ---------------------------------------------------------------- |
| `$result->isAgent`      | `bool`        | `true` cuando se ejecuta dentro de un agente de IA               |
| `$result->name`         | `?string`     | Nombre del agente (p. ej. `"claude"`). `null` si no es un agente |
| `$result->knownAgent()` | `?KnownAgent` | Devuelve el enum `KnownAgent`. `null` para agentes desconocidos  |

## Lista de agentes compatibles

| Agente         | Método de detección (variable de entorno / archivo)                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Custom         | Variable de entorno `AI_AGENT` (cualquier valor)                                                                                      |
| 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` (junto con `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          | Existe el archivo `/opt/.devin`                                                                                                       |
| Antigravity    | `ANTIGRAVITY_AGENT`                                                                                                                   |
| Pi             | `PI_CODING_AGENT`                                                                                                                     |
| Kiro CLI       | `KIRO_AGENT_PATH`                                                                                                                     |
| v0             | `AI_AGENT=v0`                                                                                                                         |

El orden de prioridad de detección es: variable de entorno `AI_AGENT` → variables de entorno conocidas → sistema de archivos.

## Configuración de un agente personalizado

Si asignas cualquier valor a la variable de entorno `AI_AGENT`, se detectará como un agente personalizado.

```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 desconocido)
```

## Casos de uso prácticos

### Detectar un agente de IA en un middleware

Determina el entorno de ejecución en un middleware de Laravel y bifurca el procesamiento hacia lógica orientada a agentes.

```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) {
            // Establecer el nombre del agente como atributo de la petición
            $request->attributes->set('ai_agent', $agent->name);
        }

        return $next($request);
    }
}
```

### Emitir logs detallados en entornos de agente de 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');
}
```

### Aplicar límite de tasa a las peticiones de agentes de IA

Al cambiar la clave del middleware `ThrottleRequests` según la detección de agentes, puedes establecer límites de tasa distintos para agentes y humanos.

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

        // Agentes de IA: 10 peticiones por minuto; humanos: 60
        $maxAttempts = $agent->isAgent ? 10 : 60;

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

### Cambiar el comportamiento en comandos de consola

Ejemplo que emite un progreso detallado cuando un agente ejecuta un comando de 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.");
    }

    // Procesamiento...
}
```

## Conclusión

`laravel/agent-detector` es un paquete que reúne comprobaciones sencillas de variables de entorno e inspecciones del sistema de archivos. Basta con llamar a `AgentDetector::detect()` sin ninguna configuración compleja.

Ahora que los agentes de IA se están consolidando como parte del flujo de desarrollo, saber "quién (o qué) está ejecutando el código" será cada vez más importante. Este paquete puede resultar útil en múltiples escenarios como logs, límites de tasa o personalización de respuestas.

<Card title="Repositorio de laravel/agent-detector" icon="github" href="https://github.com/laravel/agent-detector">
  Aquí puedes consultar el código fuente y la lista actualizada de agentes compatibles.
</Card>


## Related topics

- [Laravel PAO — Herramienta de optimización de salida para agentes de IA](/es/blog/pao-introduction.md)
- [laravel/agent-skills — Colección oficial de skills para agentes de IA de Laravel](/es/blog/agent-skills-introduction.md)
- [Crear un agente personalizado de Boost](/es/advanced/boost-custom-agent.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/es/packages/laravel-boost-phpstorm-copilot.md)
- [Laravel y el desarrollo con IA](/es/ai.md)