메인 콘텐츠로 건너뛰기

​
시작하며

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->isAgentboolAI 에이전트 안에서 실행 중이면 true
$result->name?string에이전트 이름 (예: "claude"). 에이전트가 아니면 null
$result->knownAgent()?KnownAgentKnownAgent enum을 반환. 알려지지 않은 에이전트는 null

​
지원 에이전트 목록

에이전트감지 방법 (환경 변수 / 파일)
CustomAI_AGENT 환경 변수 (임의 값)
GitHub CopilotAI_AGENT=github-copilot, AI_AGENT=github-copilot-cli, COPILOT_MODEL, COPILOT_ALLOW_ALL, COPILOT_GITHUB_TOKEN, COPILOT_CLI
CursorCURSOR_AGENT
ClaudeCLAUDECODE 또는 CLAUDE_CODE
CoworkCLAUDE_CODE_IS_COWORK (CLAUDECODE 또는 CLAUDE_CODE와 함께 설정)
GeminiGEMINI_CLI
CodexCODEX_SANDBOX, CODEX_CI, CODEX_THREAD_ID
Augment CLIAUGMENT_AGENT
AMPAMP_CURRENT_THREAD_ID
OpencodeOPENCODE_CLIENT 또는 OPENCODE
ReplitREPL_ID
Devin/opt/.devin 파일 존재
AntigravityANTIGRAVITY_AGENT
PiPI_CODING_AGENT
Kiro CLIKIRO_AGENT_PATH
v0AI_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 리포지토리

소스 코드와 최신 지원 에이전트 목록은 이곳에서 확인하실 수 있습니다.
마지막 수정일 2026년 7월 13일

관련 항목

laravel/agent-skills — Laravel 공식 AI 에이전트 스킬 모음Laravel PAO — AI 에이전트용 출력 최적화 도구Boost의 커스텀 에이전트 만들기커스텀 에이전트에이전트 루프