Laravel Agent Detector – Paket zur Erkennung von KI-Agenten

Nutzung von laravel/agent-detector. Erläuterung des offiziellen Laravel-Pakets, das die Ausführungsumgebungen der wichtigsten KI-Agenten wie Claude, Copilot und Cursor erkennt.

​

Einleitung

laravel/agent-detector ist ein leichtgewichtiges Utility, mit dem sich feststellen lässt, ob PHP-Code innerhalb eines KI-Agenten oder einer automatisierten Entwicklungsumgebung ausgeführt wird. Es wurde im April 2026 als offizielles Laravel-Paket veröffentlicht.

Da KI-Agenten mittlerweile tief in die Entwicklungsarbeit integriert sind, wird es zunehmend wichtig zu wissen, in welcher Umgebung der eigene Code läuft. In der Praxis entstehen Anwendungsfälle wie das Anpassen des Log-Detailgrads oder der Rate Limits je nach dem, ob die Anfrage von einem KI-Agenten oder einem Menschen stammt, sowie die Rückgabe agenten-spezifischer Responses.

​

Installation

composer require laravel/agent-detector

PHP 8.2 oder höher wird vorausgesetzt.

​

Grundlegende Verwendung

Der Aufruf von AgentDetector::detect() gibt ein AgentResult-Objekt zurück.

use Laravel\AgentDetector\AgentDetector;
use Laravel\AgentDetector\KnownAgent;

$result = AgentDetector::detect();

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

// Auf einen bestimmten Agenten prüfen
if ($result->knownAgent() === KnownAgent::Claude) {
    echo "Hello from Claude!";
}

Es existiert auch eine Schreibweise über eine Standalone-Funktion.

use function Laravel\AgentDetector\detectAgent;

$result = detectAgent();

​

Eigenschaften von AgentResult

Eigenschaft / Methode	Typ	Beschreibung
$result->isAgent	bool	true, wenn die Ausführung innerhalb eines KI-Agenten stattfindet
$result->name	?string	Name des Agenten (z. B. "claude"). null, wenn kein Agent aktiv ist
$result->knownAgent()	?KnownAgent	Gibt das KnownAgent-Enum zurück. Bei unbekannten Agenten null

​

Übersicht der unterstützten Agenten

Agent	Erkennungsart (Umgebungsvariable / Datei)
Custom	AI_AGENT-Umgebungsvariable (beliebiger Wert)
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 oder CLAUDE_CODE
Cowork	CLAUDE_CODE_IS_COWORK (gleichzeitig gesetzt mit CLAUDECODE oder 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 oder OPENCODE
Replit	REPL_ID
Devin	Datei /opt/.devin existiert
Antigravity	ANTIGRAVITY_AGENT
Pi	PI_CODING_AGENT
Kiro CLI	KIRO_AGENT_PATH
v0	AI_AGENT=v0

Die Erkennungsreihenfolge lautet: AI_AGENT-Umgebungsvariable → bekannte Umgebungsvariablen → Dateisystem.

​

Konfiguration von Custom-Agenten

Wird der AI_AGENT-Umgebungsvariable ein beliebiger Wert zugewiesen, lässt sich dieser als Custom-Agent erkennen.

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

$result = AgentDetector::detect();

// $result->isAgent === true
// $result->name    === 'my-custom-agent'
// $result->knownAgent() === null (unbekannter Agent)

​

Praxisnahe Anwendungsfälle

​

KI-Agenten in einer Middleware erkennen

Über eine Laravel-Middleware lässt sich die Ausführungsumgebung ermitteln und die Verarbeitung für Agenten abzweigen.

<?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) {
            // Agentenname als Request-Attribut setzen
            $request->attributes->set('ai_agent', $agent->name);
        }

        return $next($request);
    }
}

​

In KI-Agenten-Umgebungen ausführliche Logs ausgeben

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

​

Rate Limits auf Requests von KI-Agenten anwenden

Indem der Key der ThrottleRequests-Middleware auf Basis der Agenten-Erkennung variiert wird, lassen sich unterschiedliche Rate Limits für Agenten und Menschen definieren.

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

        // KI-Agenten: 10 Requests pro Minute, Menschen: 60 Requests
        $maxAttempts = $agent->isAgent ? 10 : 60;

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

​

Verhalten in Konsolenkommandos umschalten

Ein Beispiel dafür, wie ein Artisan-Kommando bei Ausführung durch einen Agenten detaillierten Fortschritt ausgibt.

use Laravel\AgentDetector\AgentDetector;

public function handle(): void
{
    $agent = AgentDetector::detect();

    if ($agent->isAgent) {
        $this->info("Running in {$agent->name} environment — verbose mode enabled.");
    }

    // Verarbeitung ...
}

​

Fazit

laravel/agent-detector ist ein Paket, das einfache Prüfungen von Umgebungsvariablen und Dateisystem in einer Lösung bündelt. Ohne aufwendige Konfiguration reicht ein Aufruf von AgentDetector::detect().

Da KI-Agenten zunehmend zu einem festen Bestandteil des Entwicklungsworkflows werden, gewinnt das Wissen darüber, „durch wen (bzw. was) Code ausgeführt wird” weiter an Bedeutung. Ob beim Logging, bei Rate Limits oder beim Anpassen von Responses – dieses Paket lässt sich in vielen Szenarien nutzbringend einsetzen.

Repository von laravel/agent-detector

Quellcode und aktuelle Liste unterstützter Agenten finden Sie hier.