> ## 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` enum을 반환. 알려지지 않은 에이전트는 `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 에이전트 스킬 모음](/ko/blog/agent-skills-introduction.md)
- [Laravel PAO — AI 에이전트용 출력 최적화 도구](/ko/blog/pao-introduction.md)
- [Boost의 커스텀 에이전트 만들기](/ko/advanced/boost-custom-agent.md)
- [커스텀 에이전트](/ko/packages/laravel-copilot-sdk/custom-agents.md)
- [에이전트 루프](/ko/packages/laravel-copilot-sdk/agent-loop.md)