> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 커스텀 에이전트

> SessionConfig의 customAgents로 용도별 서브에이전트를 정의하는 방법을 설명합니다.

## 커스텀 에이전트

커스텀 에이전트를 정의하면 용도별로 역할을 나눈 서브에이전트 구성을 만들 수 있습니다.
Laravel 버전에서는 `SessionConfig`의 `customAgents`를 사용해 설정합니다.

여러 서브에이전트를 병렬로 실행하는 오케스트레이션에 대해서는 [Fleet Mode](/ko/packages/laravel-copilot-sdk/fleet-mode)를 참고하세요.

## 기본 사용법

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: '인증 관련 설계를 조사해서 개선안을 제안해줘');

    dump($response->content());
}, config: new SessionConfig(
    customAgents: [
        [
            'name' => 'researcher',
            'displayName' => 'Research Agent',
            'description' => '코드를 조사해서 요점을 정리한다',
            'tools' => ['grep', 'glob', 'view'],
            'prompt' => 'You are a research assistant. Analyze code and summarize findings.',
        ],
        [
            'name' => 'editor',
            'displayName' => 'Editor Agent',
            'description' => '필요 최소한의 코드 변경을 수행한다',
            'tools' => ['view', 'edit', 'bash'],
            'prompt' => 'You are a code editor. Make minimal, surgical changes only.',
        ],
    ],
));
```

배열 형식으로도 동일하게 지정할 수 있습니다.

```php theme={null}
Copilot::run(
    prompt: 'README를 개선해줘',
    config: [
        'customAgents' => [
            [
                'name' => 'docs-writer',
                'description' => '문서 작성을 담당한다',
                'prompt' => 'Write clear technical documentation.',
            ],
        ],
    ],
);
```

## 설정 항목

| 프로퍼티          | 타입       | 필수 | 설명                                |
| ------------- | -------- | -- | --------------------------------- |
| `name`        | `string` | ✅  | 에이전트의 식별자                         |
| `displayName` | `string` |    | 표시명                               |
| `description` | `string` |    | 런타임이 위임처를 선택할 때의 설명               |
| `tools`       | `?array` |    | 사용 가능한 도구. `null` / 생략 시 모두 사용 가능 |
| `prompt`      | `string` | ✅  | 에이전트 전용 시스템 프롬프트                  |
| `mcpServers`  | `array`  |    | 이 에이전트 전용 MCP 서버 설정               |
| `infer`       | `bool`   |    | 자동 선택 대상으로 할지(기본값: `true`)        |
| `skills`      | `array`  |    | 시작 시에 로드할 스킬 이름 리스트               |

> `description`은 구체적으로 쓸수록 자동 선택의 정확도가 올라갑니다.

## 세션 시작 시 특정 에이전트 선택

`agent`를 지정하면 최초 턴부터 특정 커스텀 에이전트를 활성화할 수 있습니다.

```php theme={null}
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'researcher',
            'prompt' => 'You analyze code and answer questions.',
        ],
        [
            'name' => 'editor',
            'prompt' => 'You edit code with minimal changes.',
        ],
    ],
    agent: 'researcher',
);
```

## 자동 선택 비활성화(`infer: false`)

위험도가 높은 조작을 수행하는 에이전트는, 자동 선택을 비활성화하고 명시적으로 사용하는 운영이 안전합니다.

```php theme={null}
$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'dangerous-cleanup',
            'description' => '불필요한 파일을 삭제한다',
            'tools' => ['bash', 'edit', 'view'],
            'prompt' => 'Remove dead code and unused files carefully.',
            'infer' => false,
        ],
    ],
);
```

## 기본 에이전트에서 도구 숨기기

`defaultAgent.excludedTools`를 사용하면 메인 에이전트에서만 특정 도구를 숨길 수 있습니다.
해당 도구를 사용할 수 있는 커스텀 에이전트로 위임하기 쉬워집니다.

```php theme={null}
$config = new SessionConfig(
    tools: [...],
    defaultAgent: [
        'excludedTools' => ['analyze-codebase'],
    ],
    customAgents: [
        [
            'name' => 'researcher',
            'tools' => ['analyze-codebase'],
            'prompt' => 'You perform deep codebase analysis.',
        ],
    ],
);
```

## 서브에이전트 이벤트 모니터링

서브에이전트 실행 중에는 `subagent.*` 이벤트가 흐릅니다.
`onEvent` 또는 `$session->on()`으로 모니터링할 수 있습니다.

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionEvent;

Copilot::start(function (CopilotSession $session) {
    $session->on(function (SessionEvent $event): void {
        if ($event->is(SessionEventType::SUBAGENT_STARTED)) {
            info('Sub-agent started', $event->toArray());
        }

        if ($event->is(SessionEventType::SUBAGENT_COMPLETED)) {
            info('Sub-agent completed', $event->toArray());
        }

        if ($event->is(SessionEventType::SUBAGENT_FAILED)) {
            info('Sub-agent failed', $event->toArray());
        }
    });

    $session->sendAndWait(prompt: '이 저장소의 인증 구현을 조사해줘');
});
```

## 베스트 프랙티스

* `researcher`(읽기 중심)와 `editor`(변경 담당)를 분리한다
* `tools`는 필요 최소한으로 하여 권한을 좁힌다
* `description`을 구체적으로 작성해 자동 위임 정확도를 높인다
* `subagent.failed`를 잡아 재시도나 폴백 전략을 준비한다

## 참고

* [SessionConfig](/ko/packages/laravel-copilot-sdk/session-config)
* [SessionEvent](/ko/packages/laravel-copilot-sdk/session-event)
* [Fleet Mode](/ko/packages/laravel-copilot-sdk/fleet-mode)
* [MCP](/ko/packages/laravel-copilot-sdk/mcp)
* [Tools](/ko/packages/laravel-copilot-sdk/tools)


## Related topics

- [Boost의 커스텀 에이전트 만들기](/ko/advanced/boost-custom-agent.md)
- [Laravel Agent Detector — AI 에이전트 감지 패키지](/ko/blog/agent-detector-introduction.md)
- [AI SDK의 커스텀 프로바이더 만들기](/ko/advanced/ai-sdk-custom-provider.md)
- [Laravel Boost](/ko/boost.md)
- [에이전트 루프](/ko/packages/laravel-copilot-sdk/agent-loop.md)