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

# Supervisor 기초

> 이 문서는 **[Agent Bricks](/blog/guides/agent-bricks/overview)** 섹션의 일부입니다.

***

## 개요

Supervisor Agent는 여러 전문 에이전트를 **조율(Orchestrate)하여 복합 업무를 처리** 하는 멀티 에이전트 시스템입니다.

**핵심 기능:**

* 에이전트 간 상호작용 관리
* 태스크 위임(Delegation)
* 결과 종합(Synthesis)
* 사용자 권한 기반 라우팅

**적합한 유스케이스:**

* 시장 분석 (데이터 + 문서 결합)
* 사내 프로세스 자동화
* 고객 서비스 (여러 지식 소스 통합)

***

## 지원하는 서브 에이전트 유형

최대 **20개** 의 서브 에이전트를 등록할 수 있습니다.

| 서브 에이전트 유형                  | 설명                               | 필요 권한                            |
| --------------------------- | -------------------------------- | -------------------------------- |
| **Genie Spaces**            | 데이터 탐색 인터페이스                     | Space 접근 + UC 객체 권한              |
| **Agent Endpoints**         | Knowledge Assistant 엔드포인트만 지원    | `CAN QUERY`                      |
| **Unity Catalog Functions** | 커스텀 도구 (UC 함수)                   | `EXECUTE`                        |
| **External MCP Servers**    | MCP 프로토콜 서버 (Bearer Token/OAuth) | `USE CONNECTION` (UC Connection) |

> **참고**
> **중요**: Agent Endpoints는 Knowledge Assistant로 만든 엔드포인트만 지원합니다. 일반 Agent Framework 엔드포인트는 사용할 수 없습니다.

***

## 추가 요구사항

공통 요구사항 외에 다음이 필요합니다.

* **On-Behalf-Of-User Authorization** 활성화
* 최소 1개의 서브 에이전트 또는 도구
* Enhanced Security and Compliance 워크스페이스는 미지원

***

## 생성 단계 (Step by Step)

### Step 1: 서브 에이전트 생성 및 권한 부여

Supervisor를 만들기 전에 먼저 서브 에이전트를 준비합니다.

**예시: KA + Genie 조합**

```
1. Knowledge Assistant 생성 → 엔드포인트 확인
   - 엔드 유저에게 CAN QUERY 권한 부여

2. Genie Space 생성 → Space ID 확인
   - 엔드 유저에게 Space 접근 + UC 테이블 SELECT 권한 부여

3. (선택) UC Function 생성
   - 엔드 유저에게 EXECUTE 권한 부여

4. (선택) MCP Server 연결
   - UC Connection 생성 후 USE CONNECTION 권한 부여
```

### Step 2: Supervisor 설정

1. **Agents**> **Supervisor Agent**> **Build** 클릭
2. 기본 정보 입력:
   * **Name**: Supervisor 고유 이름
   * **Description**: 전체 시스템 목적 설명
3. **서브 에이전트 추가**(최대 20개):
   * 각 서브 에이전트의 **이름** 과 **Content Description** 입력
   * Description이 태스크 위임 로직에 직접 영향을 줌
4. **Instructions**(선택): Supervisor의 전체 동작 가이드라인

> **주의**
> **Description이 라우팅의 핵심입니다.** Supervisor는 각 서브 에이전트의 Description을 기반으로 어떤 에이전트에 태스크를 위임할지 결정합니다. 가능한 한 상세하게 작성하세요.

### Step 3: 테스트

1. **Test Your Agent** 패널에서 대화형 테스트
2. 올바른 서브 에이전트로 태스크가 위임되는지 확인
3. **AI Playground** 에서 고급 평가 기능 활용:
   * **AI Judge**: 자동 품질 평가
   * **Synthetic Task Generation**: 합성 태스크로 테스트

### Step 4: 품질 개선

* **Examples** 탭에서 라벨링된 질문/태스크 시나리오 추가
* SME에게 공유 링크 전달하여 피드백 수집
* 자연어 가이드라인 추가 (저장 즉시 적용)
* 재테스트로 개선 효과 검증

### Step 5: 권한 관리

| 권한 수준          | 할 수 있는 일                             |
| -------------- | ------------------------------------ |
| **Can Manage** | 설정 편집, 서브 에이전트 관리, 권한 관리             |
| **Can Query**  | API/Playground를 통한 쿼리만 가능 (설정 확인 불가) |

### Step 6: 엔드포인트 쿼리

배포된 Supervisor에 다음 방법으로 접근할 수 있습니다:

* **AI Playground** 인터랙티브 인터페이스
* **REST API**(curl)
* **Python SDK**

***

## 라우팅 로직과 접근 제어

Supervisor Agent는 **사용자 인식(User-Aware) 라우팅** 을 구현합니다.

```
사용자 질문 입력
    ↓
사용자의 서브 에이전트 접근 권한 확인
    ↓
┌─ 모든 서브 에이전트 접근 불가 → 대화 종료
├─ 일부 서브 에이전트 접근 가능 → 접근 불가한 에이전트 자동 회피
└─ 모든 서브 에이전트 접근 가능 → Description 기반 최적 에이전트 선택
    ↓
선택된 서브 에이전트에 태스크 위임
    ↓
결과 종합 후 응답
```

이 방식은 사용자가 권한 없는 데이터나 에이전트에 접근하는 것을 원천적으로 차단합니다.

***

## Long-Running Task Mode

복잡한 태스크의 경우, Supervisor Agent는 **Long-Running Task Mode** 를 지원합니다. 이 모드는 복잡한 태스크를 여러 요청/응답 사이클로 자동 분할하여 **타임아웃을 방지** 합니다.

***