🤗 14. 본편 07: ManagedAgent 위임 패턴과 팀 오케스트레이션

이번 편은 한 명의 에이전트가 모든 일을 다 처리하지 않고, 역할별 하위 에이전트에게 일을 **위임(delegate)**하는 구조를 다룬다.
핵심은 ManagedAgent 패턴으로 계획(Planner) - 실행(Worker) - 검토(Reviewer) 흐름을 분리해, 결과 품질과 운영 안정성을 동시에 높이는 것이다.

• 이전 편: 🤗 12. 본편 06
• 최근 실습편: 🤗 13. 실습편 03

한 줄 결론

작업을 역할별로 쪼개고(Planner/Worker/Reviewer), 최종 출력 계약을 고정하면 초보자도 재현 가능한 멀티에이전트 운영이 가능해진다.

flowchart TD
  U[사용자 요청] --> P[Planner Agent\n요구사항 분해]
  P --> W[Worker Agent\n도구 실행/초안 생성]
  W --> R[Reviewer Agent\n품질/리스크 점검]
  R --> C{통과?}
  C -- Yes --> F[FINAL: deliverable + checklist + verdict]
  C -- No --> W2[Worker 재작업]
  W2 --> R

---

왜 ManagedAgent가 실무에서 중요한가?

초보자가 처음 만드는 에이전트는 보통 “질문 하나 → 답변 하나” 구조다.
하지만 실제 업무에서는 아래 문제가 자주 생긴다.

1. 요청이 길어질수록 누락이 늘어남
2. 도구 호출 실패 시 복구가 어려움
3. 결과물 품질 기준이 매번 흔들림

ManagedAgent 패턴은 이 문제를 역할 분리로 푼다.

• Planner: 해야 할 일을 체크리스트로 분해
• Worker: 도구를 써서 실제 실행
• Reviewer: 출력 형식/정확도/누락을 검사

즉, “잘 생각하는 모델”보다 먼저 “흔들리지 않는 작업 구조”를 만드는 접근이다.

---

실습 목표

• smolagents 기반으로 역할 분리 에이전트 구조를 이해한다.
• 출력 계약을 FINAL: 블록으로 고정해 파싱 가능하게 만든다.
• single과 eval 실행으로 재현성을 점검한다.

실습 준비물

• 도구: Python 3.10+, 터미널, 가상환경(venv)
• 입력:
  • (온라인) OPENAI_API_KEY 등 모델 키
  • (오프라인) 키 없이 실행 가능
• 작업 폴더 예시: ~/hf-managed-agent-lab

---

1) 환경 준비

• 도구: 터미널, Python venv
• 입력: smolagents, litellm
• 실행명령:

mkdir -p ~/hf-managed-agent-lab
cd ~/hf-managed-agent-lab
python3 -m venv .venv
source .venv/bin/activate
pip install -U smolagents litellm

• 성공판정:
  • (.venv) 프롬프트가 보임
  • pip 에러 없이 설치 완료

2) 최소 멀티에이전트 코드 작성

• 도구: 에디터
• 입력: 아래 예제 코드
• 실행명령:

cat > managed_agent_demo.py <<'PY'
from __future__ import annotations
import argparse
import json
import re
from dataclasses import dataclass
 
 
def planner(query: str) -> list[str]:
    return [
        f"요구사항 핵심 정리: {query}",
        "필수 산출물 3개 정의(요약/체크리스트/판정)",
        "리스크 2개 식별",
    ]
 
 
def worker(plan: list[str]) -> str:
    summary = "요청 목적을 달성하기 위한 단계형 실행안을 작성했다."
    checklist = [
        "요구사항 누락 없음",
        "실행 순서가 재현 가능",
        "리스크/대응 포함",
    ]
    verdict = "READY"
    return f"FINAL: summary={summary} | checklist={';'.join(checklist)} | verdict={verdict}"
 
 
def reviewer(final_text: str) -> dict:
    m = re.search(r"FINAL:\s*summary=(.*?)\s*\|\s*checklist=(.*?)\s*\|\s*verdict=(\w+)", final_text)
    if not m:
        return {"ok": False, "reason": "FINAL format mismatch"}
 
    summary, checklist, verdict = m.groups()
    ok = bool(summary.strip()) and bool(checklist.strip()) and verdict in {"READY", "NEEDS_REVIEW"}
    return {
        "ok": ok,
        "summary": summary.strip(),
        "checklist": [x.strip() for x in checklist.split(";") if x.strip()],
        "verdict": verdict,
    }
 
 
def run_single(query: str) -> dict:
    plan = planner(query)
    draft = worker(plan)
    review = reviewer(draft)
    return {"query": query, "plan": plan, "draft": draft, "review": review}
 
 
def run_eval(path: str) -> dict:
    with open(path, "r", encoding="utf-8") as f:
        items = json.load(f)
 
    if not isinstance(items, list):
        raise ValueError("input JSON root must be list")
 
    results = [run_single(item["query"]) for item in items]
    pass_count = sum(1 for r in results if r["review"].get("ok"))
    score = pass_count / len(results) if results else 0.0
    return {"count": len(results), "pass_count": pass_count, "score": round(score, 2), "pass": score >= 0.67}
 
 
def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--mode", choices=["single", "eval"], required=True)
    ap.add_argument("--query", default="ManagedAgent로 릴리즈 노트 작성 파이프라인 구성")
    ap.add_argument("--input", default="sample_tasks_day14.json")
    args = ap.parse_args()
 
    if args.mode == "single":
        print(json.dumps(run_single(args.query), ensure_ascii=False, indent=2))
    else:
        print(json.dumps(run_eval(args.input), ensure_ascii=False, indent=2))
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • managed_agent_demo.py 파일 생성 완료

3) 샘플 입력 만들기

• 도구: 터미널
• 입력: 평가용 태스크 3개
• 실행명령:

cat > sample_tasks_day14.json <<'JSON'
[
  {"query": "고객 인터뷰 요약 초안을 3단계로 정리"},
  {"query": "주간 배포 체크리스트를 팀 공용 포맷으로 작성"},
  {"query": "장애 보고서 초안에 원인/영향/복구 항목 추가"}
]
JSON

• 성공판정:
  • JSON 루트가 [] 배열

4) 단일 실행

• 도구: managed_agent_demo.py
• 입력: 질의 1개
• 실행명령:

python3 managed_agent_demo.py --mode single --query "주간 운영 리포트 자동화 플로우 설계"

• 성공판정:
  • 출력 JSON에 plan, draft, review 존재
  • review.ok = true

5) 배치 평가 실행

• 도구: sample_tasks_day14.json
• 입력: 태스크 3개
• 실행명령:

python3 managed_agent_demo.py --mode eval --input sample_tasks_day14.json

• 성공판정:
  • score가 계산됨
  • pass = true면 재현 가능한 최소 품질 충족

---

실무 적용 포인트 (바로 써먹기)

1. 출력 계약 고정 (FINAL:)
   • 나중에 n8n/스크립트에서 파싱하기 쉽다.
2. 역할별 실패 로그 분리
   • Planner 실패 vs Worker 실패를 구분하면 복구 시간이 줄어든다.
3. Reviewer를 품질 게이트로 사용
   • 배포 전 자동 점검 단계로 붙이기 좋다.
4. 오프라인 fallback 유지
   • API 장애/요금 이슈 시에도 기본 파이프라인을 테스트할 수 있다.

---

자주 막히는 문제와 해결

1. input JSON root must be list

   • 원인: JSON 루트를 {}로 작성
   • 해결: [] 배열로 수정

2. FINAL format mismatch

   • 원인: Worker 출력 형식이 계약과 다름
   • 해결: FINAL: summary=... | checklist=... | verdict=... 형식 강제

3. 한글 경로 실행 실패

   • 원인: 경로 인용 누락
   • 해결: 경로 전체를 큰따옴표로 감싼다

---

체크리스트

• single 실행에서 review.ok=true 확인
• eval 실행에서 score 기록
• 팀 기준으로 verdict 조건(READY/NEEDS_REVIEW) 합의
• 운영 파이프라인(n8n/cron)에 FINAL 파서 연결

참고 링크 (우선순위)

1. https://github.com/huggingface/agents-course
2. https://huggingface.co/learn/agents-course
3. https://huggingface.co/docs/smolagents

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 작성, 실습 절차 구조화, 예제 코드 정리를 수행했으며, 최종 발행 전 사람이 명령 재현성과 링크 유효성을 점검했다.