# 서브에이전트 (/ko/docs/verdent-manager/configuration/subagents)

> 메인 에이전트가 필요할 때 호출할 수 있는 전문 에이전트



서브에이전트는 메인 에이전트(Worker)가 작업 실행 중 언제든지 호출할 수 있는 전문 "전문가"입니다. 각 서브에이전트는 고유한 전문 분야와 전용 프롬프트를 가지며, 다른 모델에서 실행될 수도 있습니다. 채팅에서 `@SubagentName`만 입력하면 도움을 위해 참여합니다. 그룹 채팅에서 동료를 태그하는 것과 같습니다.

***

## 내장 서브에이전트 [#내장-서브에이전트]

Verdent에는 소프트웨어 개발에서 가장 흔히 필요한 영역을 다루는 6개의 서브에이전트가 기본 제공됩니다.

| 이름                      | 기본 모델                             | 잘하는 일                                                        |
| ----------------------- | --------------------------------- | ------------------------------------------------------------ |
| **General**             | 메인 에이전트를 따름                       | 복잡한 문제, 코드 검색, 다단계 작업을 위한 범용 리서치 에이전트입니다. 거의 모든 일을 도울 수 있습니다 |
| **Fast Context**        | Gemini 3 Flash                    | 코드를 빠르게 찾고 컨텍스트 근거를 수집합니다. 코드베이스 인덱싱에 특화되어 있으며 매우 빠릅니다       |
| **Verifier**            | Sonnet 4.6                        | 빠른 코드 리뷰입니다. 변경한 뒤 태그하면 눈에 띄는 문제를 잡아줍니다                      |
| **Verdent Helper**      | Haiku 4.5                         | Verdent 사용 도우미입니다. Verdent의 동작 방식에 대해 무엇이든 물어볼 수 있습니다        |
| **Multi-Model Planner** | Gemini 3.1 Pro; Opus 4.6; GPT-5.4 | 여러 모델(Claude, GPT, Gemini)을 사용해 플랜을 생성하고 결과를 병합합니다           |
| **Reviewer**            | Gemini 3.1 Pro; Opus 4.6; GPT-5.4 | 전체 코드 리뷰를 수행합니다. 논리 오류, 엣지 케이스, 숨은 위험을 확인합니다                 |

<Note>
  두 서브에이전트는 특별합니다. **Multi-Model Planner**와 **Reviewer**는 2\~3개의 모델을 병렬로 실행합니다. 각 모델은 독립적으로 생각하고 자체 결과를 만든 다음, 그 결과를 결합합니다. 그 외 모든 서브에이전트는 단일 모델입니다.
</Note>

***

## 서브에이전트 사용 방법 [#서브에이전트-사용-방법]

어떤 대화에서든 `@`를 입력하면 서브에이전트 선택 메뉴가 열립니다(퍼지 검색 지원). 원하는 서브에이전트를 선택하면 현재 컨텍스트를 이어받아 작업합니다.

**예시:**

* 복잡한 인증 로직을 작성한 뒤: `@Reviewer please review this` → Reviewer가 보안, 로직, 엣지 케이스 관점에서 확인합니다.
* 까다로운 아키텍처 결정을 내려야 할 때: `@Multi-Model Planner` → 여러 모델이 해결책을 제안하고, 가장 좋은 안을 선택합니다.
* 코딩 후 빠르게 `@Verifier` 실행 → 기본 검증에는 전체 테스트 스위트를 실행하는 것보다 빠릅니다.

***

## 커스텀 서브에이전트 [#커스텀-서브에이전트]

내장 서브에이전트는 대부분의 필요를 충족하지만, 프로젝트에 맞춘 전문가가 필요할 때도 있습니다. 직접 만들 수 있습니다.

### 저장 위치 [#저장-위치]

커스텀 서브에이전트는 다음 위치에 Markdown 파일로 저장됩니다.

```
~/.verdent/subagents/
```

정리를 위해 최대 5단계의 하위 디렉터리를 지원합니다.

### 파일 형식 [#파일-형식]

각 서브에이전트는 YAML frontmatter가 있는 Markdown 파일입니다.

```markdown
---
name: SQL-Expert
description: Specializes in SQL optimization and database design, good at analyzing slow queries and indexing strategies
color: blue
model: claude-sonnet-4-6
---

You are a senior database expert focused on PostgreSQL performance optimization.
When users provide SQL queries, you should:
1. Analyze the query execution plan
2. Identify performance bottlenecks (full table scans, missing indexes, etc.)
3. Provide concrete optimization suggestions and rewritten SQL
...
```

### 주요 세부 사항 [#주요-세부-사항]

* **이름:** 문자, 숫자, 하이픈만 포함해야 합니다(예: `SQL-Expert`, `MyAgent123`). 공백이나 ASCII가 아닌 문자는 사용할 수 없습니다.
* **색상:** `dark-green`, `light-green`, `red-orange`, `amber`, `cyan`, `blue`, `pink`, `purple`, `verdent` 중 하나입니다. 시각적으로 더 쉽게 구분하기 위한 값입니다.
* **핫 리로드:** `.md` 파일을 저장하면 즉시 적용됩니다. Verdent를 다시 시작할 필요가 없습니다.

***

## Settings에서 서브에이전트 관리 [#settings에서-서브에이전트-관리]

모든 서브에이전트 관리는 **Settings → Subagents**에서 이루어집니다.

| 작업             | 설명                                                                            |
| -------------- | ----------------------------------------------------------------------------- |
| **목록 보기**      | 모든 서브에이전트가 카드로 표시됩니다. 내장 항목에는 "Built-in" 라벨이 붙고, 플러그인 기반 항목에는 플러그인 이름이 표시됩니다. |
| **활성화 / 비활성화** | 다른 서브에이전트에 영향을 주지 않고 각 서브에이전트를 켜거나 끕니다.                                       |
| **새로 만들기**     | **Add Subagent**를 선택하고 Identifier(고유 이름), Model, Description, Prompt를 입력합니다.  |
| **편집**         | 카드를 호버해 편집합니다. 내장 서브에이전트는 Model과 Description만 변경할 수 있습니다.                     |
| **복제**         | 커스텀 서브에이전트를 복사합니다(복제본은 활성화하기 전까지 기본적으로 비활성화됩니다).                              |
| **삭제**         | 커스텀 서브에이전트는 제거할 수 있습니다(확인 필요). 내장 서브에이전트는 삭제할 수 없습니다.                         |

### 모델 선택 차이 [#모델-선택-차이]

* **Multi-Model Planner**와 **Reviewer**는 다중 모델 선택을 지원합니다(한 번에 2\~3개 모델).
* 다른 서브에이전트는 단일 모델 선택을 사용합니다.
* **General**에는 특별한 옵션이 있습니다. 메인 에이전트의 모델을 자동으로 따를 수 있어 별도 설정을 유지하지 않아도 됩니다.

***

## 사용 사례 [#사용-사례]

### 코드 리뷰 [#코드-리뷰]

복잡한 로직을 구현한 뒤 `@Reviewer`를 태그합니다. 정확성, 엣지 케이스, 잠재적 버그를 확인해 수동으로 한 줄씩 검사하는 수고를 줄여줍니다.

### 다양한 관점의 아키텍처 설계 [#다양한-관점의-아키텍처-설계]

중요한 결정(예: 마이크로서비스 도입, 데이터베이스 선택)에는 `@Multi-Model Planner`를 사용해 여러 최상위 모델의 독립적인 제안을 받고 결정 위험을 줄입니다.

### 빠른 검증 [#빠른-검증]

코드 변경 후 `@Verifier`가 문법, 타입, 기본 문제를 빠르게 확인합니다. 전체 테스트 스위트보다 빠르고, 아무 검사도 하지 않는 것보다 안정적입니다.

### 커스텀 도메인 전문가 [#커스텀-도메인-전문가]

프로젝트에 맞춘 서브에이전트를 만듭니다.

* 스키마와 쿼리 패턴을 이해하는 SQL 최적화 전문가
* ESLint와 디자인 시스템 규칙을 강제하는 프런트엔드 코드 표준 관리자
* 기술 콘텐츠를 명확하고 읽기 쉬운 글로 다듬는 문서화 도우미

***

## 참고 사항 [#참고-사항]

* 커스텀 서브에이전트를 활성화하려면 유효한 모델로 설정해야 합니다. BYOK를 사용 중이고 키가 만료되거나 모델이 폐기되면, 해당 서브에이전트는 자동으로 비활성화됩니다.
* 내장 서브에이전트의 모델은 변경할 수 있지만, 기본값은 튜닝되어 있습니다. 변경하면 성능이 낮아질 수 있습니다.
* **Description은 중요합니다:** 메인 에이전트의 컨텍스트에 주입되며, 서브에이전트가 호출되는 시점에 영향을 줍니다. 더 나은 설명은 더 똑똑한 라우팅으로 이어집니다.
* 서브에이전트는 서로를 호출할 수 없습니다. 메인 에이전트(Worker)만 호출할 수 있으며, 더 깊은 중첩은 허용되지 않습니다.