> ## 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)** 섹션의 일부입니다.

오케스트레이션 메커니즘 심층 분석, 라우팅 전략(Description 작성법), 서브 에이전트 간 컨텍스트 전달, 디버깅 방법, 아키텍처 패턴을 다룹니다.

***

## 오케스트레이션 메커니즘 심층 분석

```
[Phase 1: 권한 필터링] → [Phase 2: 의도 분석 & 라우팅]
→ [Phase 3: 태스크 위임] → [Phase 4: 응답 수신 & 종합]
→ [Phase 5: 추가 작업 판단] → [최종 응답 반환]
```

### 단일 질문 vs 복합 질문 처리

| 질문 유형      | 처리 방식                 |
| ---------- | --------------------- |
| **단일 도메인** | 하나의 에이전트에 직접 라우팅      |
| **복합 질문**  | 순차적으로 여러 에이전트 호출 후 종합 |
| **모호한 질문** | 가장 관련성 높은 에이전트를 추론    |

***

## 라우팅 전략: Description이 라우팅에 미치는 영향

| 수준     | Description 예시                                                      | 라우팅 정확도 |
| ------ | ------------------------------------------------------------------- | ------- |
| **나쁨** | "HR 관련 처리"                                                          | 50% 이하  |
| **보통** | "사내 HR 정책 문서에 대한 Q\&A"                                              | 70%     |
| **좋음** | "사내 HR 정책(연차, 복리후생, 채용, 평가) 관련 문서 기반 질문에 답변. 수치 데이터 조회는 처리하지 않습니다." | 90%+    |

### 겹치는 도메인 처리 전략

| 문제 상황                 | 해결 전략                     |
| --------------------- | ------------------------- |
| **KA와 Genie가 동일 도메인** | "문서 기반" vs "데이터 기반" 명확 구분 |
| **두 KA의 문서 범위가 겹침**   | 담당 문서 유형을 구체적으로 나열        |
| **모호한 질문이 빈번**        | Instructions에 라우팅 규칙 명시   |

***

## 하위 Agent 간 컨텍스트 전달 방식

```
[Supervisor] → [1차 호출: Genie] → [중간 처리: 응답 컨텍스트 추가]
→ [2차 호출: KA] → [최종 종합]
```

### 주의사항

| 항목         | 대응 방법                       |
| ---------- | --------------------------- |
| **토큰 제한**  | Instructions에 "간결하게 응답" 지시  |
| **정보 손실**  | 구조화된 출력 요청 (테이블, JSON)      |
| **순서 의존성** | Long-Running Task Mode 활용   |
| **에러 전파**  | Instructions에 에러 시 대체 동작 정의 |

***

## 디버깅 방법

### MLflow Trace를 활용한 디버깅

Trace에서 각 Phase의 소요 시간, 라우팅 판단 근거, 서브 에이전트 응답을 확인합니다.

### 일반적인 문제와 진단 방법

| 문제 증상               | 해결 방법                          |
| ------------------- | ------------------------------ |
| **잘못된 에이전트로 라우팅**   | Description을 더 구체적으로 수정        |
| **서브 에이전트 응답이 빈 값** | 서브 에이전트를 단독으로 테스트              |
| **"권한 없음" 에러**      | 사용자에게 접근 권한 부여                 |
| **타임아웃**            | Long-Running Task Mode 또는 최적화  |
| **응답 언어 불일관**       | Instructions에 "반드시 한국어로 응답" 명시 |

***

## Supervisor Agent 아키텍처 패턴

### 패턴 1: 문서 + 데이터 통합

```
[Supervisor]
├── [KA: 정책/매뉴얼]
└── [Genie: 운영 데이터]
```

### 패턴 2: 도메인별 전문 에이전트

```
[Supervisor]
├── [KA: 제품 A 문서]
├── [KA: 제품 B 문서]
└── [Genie: 제품별 성과 데이터]
```

### 패턴 3: 외부 시스템 연동

```
[Supervisor]
├── [KA: 내부 문서]
├── [MCP: Slack 알림]
└── [UC Function: 이메일 전송]
```

### 패턴 4: 계층적 Supervisor (Nested)

> **주의**
> 현재 Supervisor를 다른 Supervisor의 서브 에이전트로 직접 등록할 수 없습니다. Agent Framework(코드 기반)으로 구축 후 간접 연결이 필요합니다.