Supervisor Agent (Multi-Agent)

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

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

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

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

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

Step 1: Knowledge Assistant 생성
  ├── 이름: "product-support-ka"
  ├── Knowledge Source: UC Volume (product_docs/)
  │   ├── product_manual.pdf
  │   ├── faq.md
  │   └── troubleshooting_guide.docx
  └── Instructions: "고객 질문에 친절하게 응답. 반드시 출처 인용."

Step 2: Genie Space 생성
  ├── 이름: "order-analytics-genie"
  ├── 테이블: sales.orders, sales.customers, sales.products
  ├── Knowledge Store:
  │   ├── 컬럼 설명: "order_date = 주문일, revenue = 매출액"
  │   └── JOIN 정의: orders.customer_id = customers.id
  └── Sample Questions: "이번 달 매출은?", "Top 10 고객 리스트"

Step 3: Supervisor Agent 생성
  ├── 이름: "customer-support-supervisor"
  ├── 서브 에이전트 1: product-support-ka
  │   └── Description: "제품 사용법, FAQ, 문제 해결 가이드 관련 질문 처리"
  ├── 서브 에이전트 2: order-analytics-genie
  │   └── Description: "주문, 매출, 고객 데이터 조회 및 분석"
  └── Instructions:
      "고객 지원팀을 위한 통합 어시스턴트.
       제품 관련 질문은 product-support-ka로,
       데이터 조회 질문은 order-analytics-genie로 라우팅."

Step 4: 테스트
  ├── "이 제품 설정 방법이 뭐야?" → KA 라우팅 확인
  ├── "지난달 매출 합계 알려줘" → Genie 라우팅 확인
  └── "VIP 고객의 제품 이용 가이드를 정리해줘" → 복합 라우팅 확인

Step 5: 권한 부여 및 배포
  ├── 고객지원팀에 CAN QUERY 권한 부여
  └── AI Playground 또는 API로 서비스

[사용자 질문 수신]
    ↓
[Phase 1: 권한 필터링]
    - 질문한 사용자의 ID 확인
    - 각 서브 에이전트에 대한 사용자의 접근 권한 확인
    - 접근 불가한 서브 에이전트를 후보 목록에서 제외
    - 모든 서브 에이전트가 접근 불가 → "권한이 없습니다" 응답 후 종료
    ↓
[Phase 2: 의도 분석 & 라우팅]
    - Supervisor LLM이 질문의 의도를 분석
    - 접근 가능한 서브 에이전트들의 Description을 컨텍스트로 제공
    - Instructions(있는 경우)를 참고하여 라우팅 규칙 적용
    - 최적의 서브 에이전트 1개 선택 (또는 복합 질문 시 순차적으로 여러 개)
    ↓
[Phase 3: 태스크 위임]
    - 선택된 서브 에이전트에 질문(또는 변환된 서브 태스크) 전달
    - 서브 에이전트 유형에 따른 호출 방식:
      · KA Endpoint → REST API 호출
      · Genie Space → Genie API 호출 (사용자 권한으로)
      · UC Function → 함수 실행
      · MCP Server → MCP 프로토콜 호출
    ↓
[Phase 4: 응답 수신 & 종합]
    - 서브 에이전트의 응답 수신
    - 복합 질문인 경우 여러 서브 에이전트의 응답을 종합(Synthesis)
    - 최종 응답 포맷팅
    ↓
[Phase 5: 추가 작업 판단]
    - LLM이 "추가 서브 에이전트 호출이 필요한가?"를 판단
    - 필요하면 Phase 2로 돌아감 (반복)
    - 불필요하면 최종 응답 반환
    ↓
[최종 응답 반환]

당신은 고객지원 통합 AI 어시스턴트입니다.

라우팅 규칙:
1. 제품 사용법, FAQ, 문제 해결 관련 질문 → product-support-ka
2. 주문, 매출, 고객 데이터 조회 관련 질문 → order-analytics-genie
3. 외부 시스템(JIRA, Slack) 관련 작업 → external-tools-mcp
4. 위 어디에도 해당하지 않는 질문 → "죄송합니다, 해당 질문은 처리할 수 없습니다"

주의사항:
- 하나의 질문이 여러 에이전트에 해당할 수 있음. 이 경우 순차적으로 호출.
- 데이터 관련 질문은 반드시 Genie로 라우팅 (KA로 보내지 말 것)
- 응답은 항상 한국어로

[Supervisor]
    │
    ├── 질문: "VIP 고객 리스트를 뽑고 이들의 구매 패턴을 분석해줘"
    │
    ├── [1차 호출: Genie Space]
    │   ├── 전달: "VIP 고객 리스트를 조회해줘"
    │   └── 응답: 고객 ID, 이름, 등급, 총 구매액 테이블
    │
    ├── [Supervisor 중간 처리]
    │   ├── Genie 응답을 컨텍스트에 추가
    │   └── 다음 서브 에이전트 호출 판단
    │
    ├── [2차 호출: KA]
    │   ├── 전달: "다음 VIP 고객들의 구매 패턴을 분석해줘: [Genie 결과 요약]"
    │   └── 응답: 구매 패턴 분석 (문서 기반)
    │
    └── [최종 종합]
        └── 두 응답을 결합한 최종 답변

Trace 구조 예시:

[Supervisor] ─── 총 소요: 8.2초
├── [Phase 1: 권한 확인] ─── 0.1초
│   └── 접근 가능 에이전트: KA, Genie (MCP 제외)
├── [Phase 2: 라우팅 판단] ─── 1.2초
│   ├── LLM 호출: "이 질문은 데이터 조회 → Genie 선택"
│   └── 선택된 에이전트: order-analytics-genie
├── [Phase 3: Genie 호출] ─── 6.5초
│   ├── SQL 생성: SELECT ... FROM ...
│   ├── SQL 실행: 5.1초
│   └── 결과: 15행 반환
└── [Phase 4: 응답 종합] ─── 0.4초
    └── 최종 응답 생성

1. 서브 에이전트 단독 테스트
   □ 각 서브 에이전트(KA, Genie)를 AI Playground에서 개별 테스트
   □ 단독으로 잘 작동하는지 확인 → 문제가 있으면 서브 에이전트 자체를 수정

2. 라우팅 테스트
   □ 각 서브 에이전트 전용 질문으로 Supervisor 테스트
   □ 올바른 에이전트로 라우팅되는지 Trace에서 확인
   □ 잘못 라우팅되면 Description 수정

3. 복합 질문 테스트
   □ 여러 에이전트가 필요한 질문으로 테스트
   □ 순차 호출이 올바르게 이루어지는지 확인
   □ 컨텍스트 전달이 제대로 되는지 확인

4. 에지 케이스 테스트
   □ 어떤 에이전트에도 해당하지 않는 질문
   □ 권한 없는 사용자의 질문
   □ 매우 긴 질문 또는 다국어 질문

[Supervisor]
├── [KA: 정책/매뉴얼] — 텍스트 기반 Q&A
└── [Genie: 운영 데이터] — 데이터 기반 분석

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

[Supervisor]
├── [KA: 내부 문서]
├── [Genie: 내부 데이터]
├── [MCP: Slack 알림 전송]
├── [MCP: JIRA 티켓 생성]
└── [UC Function: 이메일 전송]

[최상위 Supervisor]
├── [하위 Supervisor: 영업팀]
│   ├── [KA: 영업 매뉴얼]
│   └── [Genie: 영업 데이터]
├── [하위 Supervisor: 마케팅팀]
│   ├── [KA: 마케팅 가이드]
│   └── [Genie: 마케팅 성과]
└── [KA: 공통 HR 정책]