4단계 오케스트레이션: 5가지 범용 에이전트 기술이 어떻게 YAML 기반 규칙 + 컴포저블 컴포넌트 + 우아한 성능 저하(Graceful Degradation)를 달성하는가

세 번째 스코어링(scoring) if-else 문을 하드코딩하고 있다면, 이제는 질문을 던져야 할 때입니다: 규칙을 YAML로 옮기고 비즈니스 로직이 코드 대신 설정(config)을 변경하게 할 수는 없을까?

문제점: 왜 에이전트 기술은 계속해서 바퀴를 재발명하는가?

모든 에이전트 개발자는 동일한 딜레마에 직면합니다 — 모든 비즈니스 시나리오가 유사한 파이프라인을 다시 작성합니다:

• 스코어링 (Scoring): 특징 추출 (Extract features) → 규칙 매칭 (Match rules) → 점수 계산 (Calculate score) → 보고서 생성 (Generate report)
• 민원 처리 (Complaints): 티켓 추출 (Extract ticket) → 교차 검증 (Cross-validate) → 근본 원인 파악 (Pinpoint root cause) → 아카이브 (Archive)
• 쿼리 (Querying): 의도 파악 (Understand intent) → SQL 구축 (Build SQL) → 쿼리 실행 (Execute query) → 차트 렌더링 (Render chart)

골격(skeleton)은 동일합니다. 각 단계에서 변하는 것은 오직 "내용"뿐입니다. 하지만 모든 팀은 파이프라인을 처음부터 다시 구축합니다.

teleagent-skills는 해답을 제시합니다: 4단계 오케스트레이션(4-Phase orchestration)을 갖춘 5가지 범용 기술(Skills)로 골격을 고정하고, 비즈니스 변경 사항은 YAML 설정에만 반영되도록 하는 것입니다.

아키텍처 개요: 4단계 파이프라인 + 5가지 범용 기술

2.1 4단계 오케스트레이션 다이어그램

┌─────────────────────────────────────────────────────────────┐
│                    상위 비즈니스 기술 (Upper Business Skill)                      │
│  (스코어링 엔진 / 증거 체인 / 데이터 어그리게이터 / ...)  │
│... 

핵심 아이디어: 각 단계(Phase)는 독립적인 컴포넌트이며, 단계 간에는 JSON 계약(JSON contracts)을 통해서만 데이터를 전달합니다.

• 어떤 단계든 교체 가능합니다 (더 강력한 분석기(Analyzer)를 원하시나요? 교체하면 됩니다)
• 어떤 단계든 건너뛸 수 있습니다 (성능 저하 모드/degradation mode)
• 어떤 단계든 재사용 가능합니다 (5가지 기술이 동일한 추출(Extract) 컴포넌트를 공유합니다)

2.2 JSON 계약 예시

{
  "phase": "extract",
  "skill": "scoring-engine",
...

세 가지 설계 원칙, 심층 분석

원칙 1: YAML 기반의 매개변수화된 규칙

전통적인 방식은 스코어링 규칙을 하드코딩합니다:

하드코딩됨 — 비즈니스 로직이 변경될 때마다 코드 변경이 필요함

if customer.revenue > 10000000:
score += 30
...

teleagent-skills는 다르게 처리합니다 — 모든 규칙은 YAML로 외부화됩니다:

# scoring_rules.yaml
scoring_engine:
  name: "政企客户商机评分"
...

비즈니스가 변경되었나요? YAML을 편집하세요. 새로운 차원이 필요한가요? YAML을 추가하세요. 코드 변경은 전혀 필요 없습니다.

원칙 2: 컴포저블 컴포넌트 (Composable Components) — 4단계 오케스트레이션 + JSON 계약 (JSON Contracts)

5가지 기술(Skills) 모두 동일한 4단계 골격을 공유하지만, 각 기술의 단계별 동작은 다릅니다:

기술 (Skill)	1단계 추출 (Extract)	2단계 분석 (Analyze)	3단계 생성 (Generate)	4단계 아카이브 (Archive)
Scoring Engine	스코어링 객체 속성 추출	YAML 규칙 로드 및 점수 매칭	스코어링 보고서 + 권장 사항 생성	스코어링 기록 아카이브
...

컴포저빌리티(Composability)의 힘: 상위 수준의 기술은 필요에 따라 하위 수준의 기술을 체인(chain) 형태로 연결할 수 있습니다. 예를 들어, 데이터 쿼리 게이트웨이 파이프라인은 다음과 같습니다:

NL2Query(1-2단계) → Data Aggregator(1-2단계) → Visualization Renderer(1-3단계)

하나의 자연어 쿼리가 "이해 → 쿼리 → 집계 → 시각화" 과정을 통해 엔드 투 엔드(end to end)로 자동 흐릅니다.

원칙 3: 우아한 성능 저하 (Graceful Degradation) — 하위 컴포넌트 실패 시

4단계 아키텍처에는 내장된 3단계 성능 저하(degradation) 메커니즘이 있습니다:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   1단계     │────▶│   2단계     │────▶│   3단계     │────▶│   4단계     │
│   추출 (Extract) │     │   분석 (Analyze) │     │   생성 (Generate) │     │   아카이브 (Archive) │
...

성능 저하의 핵심 원칙: 에러와 함께 시스템이 충돌(crash)하는 것보다, 차라리 신뢰도가 낮은(low-confidence) 결과를 사용자에게 제공하는 편을 택합니다.

5가지 기술 (The 5 Skills), 하나씩 살펴보기

4.1 Scoring Engine

정의: YAML 규칙 설정에 의해 구동되는 다차원 가중치 스코어링 컴포넌트입니다.

전형적인 시나리오: 기업 기회 스코어링 (enterprise opportunity scoring), 벤더 평가, 고객 이탈 예측, 파트너 등급 분류.

입력(Input) → 규칙 매칭(Rule matching) → 스코어링 출력(Scoring output) 흐름:

{
  "customer": "고객A",
  "total_score": 78,
...
}

4.2 증거 체인 (Evidence Chain)

정의: 충돌을 감지하고, 신뢰도(Confidence)를 평가하며, 근본 원인(Root cause)을 정확히 찾아내는 다중 소스 증거 교차 검증 컴포넌트입니다.

데이터 소스 1: 고객 불만 사항    ──┐
                                         │     ┌──────────────────┐
데이터 소스 2: 시스템 경고 로그    ──┼────▶│  증거 체인 (Evidence Chain)  │
...

4.3 데이터 어그리게이터 (Data Aggregator)

정의: 검증/정제, 집계(Aggregation), 전년 대비(YoY)/전월 대비(MoM), TOP 순위 산출을 지원하는 원시 데이터 재처리 컴포넌트입니다.

원시 쿼리 결과 (Raw query results)           어그리게이터 출력 (Aggregator output)
┌──────────────┐         ┌──────────────────────────────┐
│ 300개 행     │───────▶ │ 월간 요약 + YoY/MoM           │
...

4.4 시각화 렌더러 (Visualization Renderer)

정의: 구조화된 데이터를 ECharts 차트와 대시보드(Dashboards)로 변환하는 자동 렌더링 컴포넌트입니다.

차트 유형 선택은 자동으로 이루어집니다: 시계열(Time-series) → 선 그래프(Line chart), 범주형(Categorical) → 막대/파이 차트(Bar/pie), 다차원(Multi-dimensional) → 레이더 차트(Radar).

4.5 NL2Query

정의: 자연어를 구조화된 쿼리로 변환하는 스마트 자연어-쿼리 변환(Natural-language-to-structured-query) 컴포넌트입니다.

사용자 입력: "화동 지역 지난달 5G 전용망 신규 고객 수"

1단계 추출 (Phase1 Extract):  의도(intent)="query", 엔티티(entities)=[지역(region)="화동", 시간(time)="지난달", 지표(metric)="5G 전용망"]
...

신뢰도 스코어링 (Confidence scoring): 신뢰도가 임계값(Threshold) 미만으로 떨어지면, 출력물에 "낮은 신뢰도(low confidence)" 경고가 표시되며 사람이 검토할 수 있도록 SQL을 보여줍니다.

산업별 활용 사례 매트릭스 (Industry Use-Case Matrix)

산업 분야	스코어링 엔진 (Scoring Engine)	증거 체인 (Evidence Chain)	데이터 어그리게이터 (Data Aggregator)	시각화 렌더러 (Viz Renderer)	NL2Query
금융 (Finance)	고객 신용 등급	자금 세탁 방지(Anti-money-laundering) 다중 소스 검증	거래량 YoY/MoM	리스크 관리 대시보드	"고객의 지난 3개월간 거래 내역 확인해줘"
...

핵심 통찰 (Key insight): 5가지 기술 모두 YAML 규칙 설정만으로 다양한 산업에 적응할 수 있습니다. 스코어링 엔진의 코드 로직은 동일하며, 오직 YAML 파일만 달라집니다.

이것이 기존 프레임워크와 근본적으로 다른 점

차원 (Dimension)	LangChain/LlamaIndex	AutoGen/CrewAI	teleagent-skills
오케스트레이션 (Orchestration)	코드 레벨 체인 (Code-level Chain)	멀티 에이전트 대화 (Multi-Agent dialogue)	4단계 선언적 오케스트레이션 (4-Phase declarative orchestration)
...

빠른 시작 (Quick Start)

git clone https://github.com/yuzhaopeng-up/teleagent-skills.git
cd teleagent-skills

...

라이선스 (License): Apache 2.0

에이전트 스킬 오픈소스 생태계 (Agent Skills Open-Source Ecosystem)

리포지토리 (Repo)	기능 (What It Does)	GitHub
financial-ai-skills	금융 AI 스킬 라이브러리: 104개 시나리오, 순수 Python (pure Python)	https://github.com/yuzhaopeng-up/financial-ai-skills
...

파이프라인을 처음부터 직접 구축하는 것을 멈추세요. 4단계 스켈레톤 (4-Phase skeleton)이 준비되어 있습니다 — 당신은 그저 YAML만 작성하면 됩니다.

teleagent-skills를 스타(Star)하고, 함께 에이전트 스킬 (Agent Skills)을 표준화해 나갑시다.