Laravel Agent Detector — AI 智能体检测包

简介

laravel/agent-detector 是一个轻量级工具包,用于检测 PHP 代码是否运行在 AI 智能体或自动化开发环境中。它于 2026 年 4 月作为 Laravel 官方包正式发布。随着 AI 智能体深度融入开发现场,了解代码本身运行在什么环境中变得越来越重要。根据请求来自 AI 智能体还是人类,来切换日志详细度、调整限流策略、或返回专门为智能体准备的响应,这些实际开发中的需求正在不断出现。

安装

composer require laravel/agent-detector

需要 PHP 8.2 或以上版本。

基本用法

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

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!";
}

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

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 环境变量,即可作为自定义智能体被检测到。

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

$result = AgentDetector::detect();

// $result->isAgent === true
// $result->name    === 'my-custom-agent'
// $result->knownAgent() === null(未知智能体)

实用案例

在中间件中检测 AI 智能体

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

<?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 智能体环境下输出详细日志

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

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 命令时,输出更详细的进度信息。

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

laravel/agent-detector 仓库

源代码和最新支持的智能体列表请查看这里。

​简介

​安装

​基本用法

​AgentResult 的属性

​支持的智能体一览

​配置自定义智能体

​实用案例

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

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

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

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

​总结