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

```mermaid theme={null}
graph TD
    A["AgentDetector::detect()"] --> B{"AI_AGENT<br>Umgebungsvariable gesetzt?"}
    B -->|Yes| C["Als Custom- oder bekannter Agent<br>zurückgeben"]
    B -->|No| D{"Bekannte Umgebungs-<br>variable vorhanden?"}
    D -->|Yes| E["Als passender KnownAgent<br>zurückgeben"]
    D -->|No| F{"/opt/.devin<br>Datei vorhanden?"}
    F -->|Yes| G["Als KnownAgent::Devin<br>zurückgeben"]
    F -->|No| H["isAgent: false<br>(kein Agent)"]
```

## Installation

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

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

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

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

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

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

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

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

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

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

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

<Card title="Repository von laravel/agent-detector" icon="github" href="https://github.com/laravel/agent-detector">
  Quellcode und aktuelle Liste unterstützter Agenten finden Sie hier.
</Card>


## Related topics

- [Einen eigenen Agenten für Boost erstellen](/de/advanced/boost-custom-agent.md)
- [Laravel PAO – Output-Optimierungstool für KI-Agenten](/de/blog/pao-introduction.md)
- [laravel/agent-skills – Offizielle KI-Agent-Skills-Sammlung von Laravel](/de/blog/agent-skills-introduction.md)
- [Laravel und KI-Entwicklung](/de/ai.md)
- [Laravel AI SDK](/de/ai-sdk.md)