> ## 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 — AI 智能体检测包

> 介绍 laravel/agent-detector 的使用方法。这是一个用于检测 Claude、Copilot、Cursor 等主流 AI 智能体运行环境的 Laravel 官方包。

## 简介

[laravel/agent-detector](https://github.com/laravel/agent-detector) 是一个轻量级工具包,用于检测 PHP 代码是否运行在 AI 智能体或自动化开发环境中。它于 2026 年 4 月作为 Laravel 官方包正式发布。

随着 AI 智能体深度融入开发现场,了解代码本身运行在什么环境中变得越来越重要。根据请求来自 AI 智能体还是人类,来切换日志详细度、调整限流策略、或返回专门为智能体准备的响应,这些实际开发中的需求正在不断出现。

```mermaid theme={null}
graph TD
    A["AgentDetector::detect()"] --> B{"AI_AGENT<br>环境变量存在?"}
    B -->|Yes| C["作为自定义或已知<br>智能体返回"]
    B -->|No| D{"存在已知的<br>环境变量?"}
    D -->|Yes| E["作为对应的 KnownAgent<br>返回"]
    D -->|No| F{"/opt/.devin<br>文件存在?"}
    F -->|Yes| G["作为 KnownAgent::Devin<br>返回"]
    F -->|No| H["isAgent: false<br>(非智能体)"]
```

## 安装

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

需要 PHP 8.2 或以上版本。

## 基本用法

调用 `AgentDetector::detect()` 会返回一个 `AgentResult` 对象。

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

$result = AgentDetector::detect();

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

// 检查具体的智能体
if ($result->knownAgent() === KnownAgent::Claude) {
    echo "Hello from Claude!";
}
```

也可以使用独立函数的写法。

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

$result = detectAgent();
```

### AgentResult 的属性

| 属性 / 方法                 | 类型            | 说明                                 |
| ----------------------- | ------------- | ---------------------------------- |
| `$result->isAgent`      | `bool`        | 如果运行在 AI 智能体中则为 `true`             |
| `$result->name`         | `?string`     | 智能体名称(例如 `"claude"`)。非智能体时为 `null` |
| `$result->knownAgent()` | `?KnownAgent` | 返回 `KnownAgent` 枚举。未知智能体为 `null`   |

## 支持的智能体一览

| 智能体            | 检测方式(环境变量 / 文件)                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Custom         | `AI_AGENT` 环境变量(任意值)                                                                                                             |
| 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` 或 `CLAUDE_CODE`                                                                                                     |
| Cowork         | `CLAUDE_CODE_IS_COWORK`(与 `CLAUDECODE` 或 `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` 或 `OPENCODE`                                                                                                   |
| Replit         | `REPL_ID`                                                                                                                        |
| Devin          | 存在 `/opt/.devin` 文件                                                                                                              |
| Antigravity    | `ANTIGRAVITY_AGENT`                                                                                                              |
| Pi             | `PI_CODING_AGENT`                                                                                                                |
| Kiro CLI       | `KIRO_AGENT_PATH`                                                                                                                |
| v0             | `AI_AGENT=v0`                                                                                                                    |

检测的优先级依次为:`AI_AGENT` 环境变量 → 已知环境变量 → 文件系统。

## 配置自定义智能体

将任意值设置到 `AI_AGENT` 环境变量,即可作为自定义智能体被检测到。

```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(未知智能体)
```

## 实用案例

### 在中间件中检测 AI 智能体

在 Laravel 中间件中判断运行环境,并对智能体进行分支处理。

```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) {
            // 将智能体名称设置到请求属性上
            $request->attributes->set('ai_agent', $agent->name);
        }

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

### 在 AI 智能体环境下输出详细日志

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

### 对来自 AI 智能体的请求应用限流

通过根据智能体检测结果切换 `ThrottleRequests` 中间件的键,可以为智能体和人类设置不同的限流规则。

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

        // AI 智能体每分钟 10 次请求,人类为 60 次
        $maxAttempts = $agent->isAgent ? 10 : 60;

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

### 在控制台命令中切换行为

以下示例展示当智能体执行 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.");
    }

    // 处理...
}
```

## 总结

`laravel/agent-detector` 是一个把简单的环境变量检查和文件系统探测整合到一起的包。不需要复杂配置,只要调用 `AgentDetector::detect()` 就能使用。

在 AI 智能体正在成为开发流程一部分的当下,了解"代码是被谁(什么)驱动运行的"会越来越重要。日志、限流、响应的定制化等各种场景中,你都可以用到这个包。

<Card title="laravel/agent-detector 仓库" icon="github" href="https://github.com/laravel/agent-detector">
  源代码和最新支持的智能体列表请查看这里。
</Card>


## Related topics

- [laravel/agent-skills — Laravel 官方 AI 智能体技能集](/zh/blog/agent-skills-introduction.md)
- [Laravel PAO — 面向 AI 智能体的输出优化工具](/zh/blog/pao-introduction.md)
- [Laravel AI SDK](/zh/ai-sdk.md)
- [2026 年 5 月 Laravel 更新](/zh/blog/changelog/202605.md)
- [Laravel 新代码分析生态 — surveyor / ranger / roster](/zh/blog/laravel-ecosystem-analysis.md)