Laravel Agent Detector — Paquete de detección de agentes de IA

Introducción

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.

Instalación

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.

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.

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.

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

$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

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

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

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.

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.

Repositorio de laravel/agent-detector

Aquí puedes consultar el código fuente y la lista actualizada de agentes compatibles.

​Introducción

​Instalación

​Uso básico

​Propiedades de AgentResult

​Lista de agentes compatibles

​Configuración de un agente personalizado

​Casos de uso prácticos

​Detectar un agente de IA en un middleware

​Emitir logs detallados en entornos de agente de IA

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

​Cambiar el comportamiento en comandos de consola

​Conclusión