Laravel Agent Detector – Paket zur Erkennung von KI-Agenten

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.

​Einleitung

​Installation

​Grundlegende Verwendung

​Eigenschaften von AgentResult

​Übersicht der unterstützten Agenten

​Konfiguration von Custom-Agenten

​Praxisnahe Anwendungsfälle

​KI-Agenten in einer Middleware erkennen

​In KI-Agenten-Umgebungen ausführliche Logs ausgeben

​Rate Limits auf Requests von KI-Agenten anwenden

​Verhalten in Konsolenkommandos umschalten

​Fazit