🤗 25. 실습편 07: smolagents 멀티에이전트 리서치 팩 미니프로젝트 핸즈온 1

이번 편은 **“하나의 요청을 역할별 서브 에이전트로 분해해, 근거 포함 리서치 팩(JSON)을 만드는 실습”**이다.
핵심은 아래 4가지를 재현하는 것이다.

• Orchestrator + Specialist(시장/기술) 2개 역할 구성

• 웹 검색 기반 근거 수집

• 구조화 결과(JSON) 저장

• 품질 게이트 + 트러블슈팅으로 재실행 가능 상태 확보

• 이전 편: 🤗 24. 본편 14

• 다음 편 예고: 실습편 07-2 (평가 에이전트 추가, 자동 재시도 루프)

flowchart TD
  A[사용자 주제 입력] --> B[Orchestrator CodeAgent]
  B --> C[시장 분석 Specialist]
  B --> D[기술 분석 Specialist]
  C --> E[근거 2개 이상 반환]
  D --> F[근거 2개 이상 반환]
  E --> G[Orchestrator가 리서치 팩 JSON 병합]
  F --> G
  G --> H[research_pack.json 저장]
  H --> I{품질 게이트 통과?}
  I -- Yes --> J[완료]
  I -- No --> K[프롬프트/환경 수정 후 재실행]
  K --> B

0) 실습 목표

입력 주제 1개를 넣으면, 멀티에이전트가 시장/기술 관점 요약과 출처를 모아 research_pack.json으로 저장한다.

---

1) 환경 준비

• 도구: 터미널
• 입력: Python 3.10+
• 실행명령:

mkdir -p ~/hf-agents-lab25
cd ~/hf-agents-lab25
python3 -m venv .venv
source .venv/bin/activate
pip install -U smolagents litellm duckduckgo-search

• 성공판정:

python -V
pip show smolagents | head -n 5
pip show duckduckgo-search | head -n 5

• Python 버전이 출력되고
• smolagents, duckduckgo-search 정보가 보이면 성공

2) 모델/API 설정

• 도구: 터미널
• 입력: API 키, 모델 ID
• 실행명령:

export OPENAI_API_KEY="YOUR_API_KEY"
export MODEL_ID="openai/gpt-4o-mini"

• 성공판정:

python - <<'PY'
import os
print('MODEL_ID =', os.getenv('MODEL_ID'))
print('OPENAI_API_KEY set =', bool(os.getenv('OPENAI_API_KEY')))
PY

• OPENAI_API_KEY set = True 확인

3) 미니 프로젝트 코드 작성

• 도구: 에디터/터미널
• 입력: 아래 코드
• 실행명령:

cat > lab25_multiagent_research_pack.py <<'PY'
from __future__ import annotations
 
import json
import os
from datetime import datetime
from pathlib import Path
 
from smolagents import CodeAgent, DuckDuckGoSearchTool, LiteLLMModel
 
TOPIC = "2026년 한국 B2B 조직이 도입 가능한 AI 에이전트 운영 패턴 3가지"
OUT = Path("research_pack.json")
 
 
def strip_code_fence(text: str) -> str:
    t = text.strip()
    if t.startswith("```"):
        lines = t.splitlines()
        if lines and lines[0].startswith("```"):
            lines = lines[1:]
        if lines and lines[-1].startswith("```"):
            lines = lines[:-1]
        t = "\n".join(lines).strip()
    return t
 
 
def run_specialist(agent: CodeAgent, role: str, topic: str) -> dict:
    prompt = f"""
너는 {role} Specialist다.
주제: {topic}
 
웹 검색 기반으로 아래 JSON만 반환하라:
{{
  "role": "{role}",
  "insights": ["...", "...", "..."],
  "sources": [
    {{"title": "...", "url": "..."}},
    {{"title": "...", "url": "..."}}
  ]
}}
 
규칙:
- insights는 정확히 3개
- sources는 최소 2개
- URL은 실제 http/https 주소
- 찾지 못하면 모른다고 명시
"""
    raw = agent.run(prompt)
    return json.loads(strip_code_fence(str(raw)))
 
 
def main() -> None:
    model = LiteLLMModel(model_id=os.getenv("MODEL_ID", "openai/gpt-4o-mini"))
    tool = DuckDuckGoSearchTool()
 
    market_agent = CodeAgent(
        model=model,
        tools=[tool],
        max_steps=6,
        additional_authorized_imports=["json"],
    )
    tech_agent = CodeAgent(
        model=model,
        tools=[tool],
        max_steps=6,
        additional_authorized_imports=["json"],
    )
 
    market = run_specialist(market_agent, "시장 분석", TOPIC)
    tech = run_specialist(tech_agent, "기술 분석", TOPIC)
 
    orchestrator_prompt = f"""
다음 두 결과를 병합해 최종 리서치 팩 JSON만 반환하라.
 
[시장 분석]
{json.dumps(market, ensure_ascii=False)}
 
[기술 분석]
{json.dumps(tech, ensure_ascii=False)}
 
형식:
{{
  "topic": "...",
  "executive_summary": ["...", "...", "...", "...", "..."],
  "specialists": [...],
  "source_count": 0
}}
 
규칙:
- executive_summary는 정확히 5줄
- specialists에는 위 2개 결과를 그대로 넣기
- source_count는 전체 source 개수 합
"""
 
    orchestrator = CodeAgent(
        model=model,
        tools=[],
        max_steps=4,
        additional_authorized_imports=["json"],
    )
 
    final_obj = json.loads(strip_code_fence(str(orchestrator.run(orchestrator_prompt))))
    final_obj["generated_at"] = datetime.now().isoformat(timespec="seconds")
 
    OUT.write_text(json.dumps(final_obj, ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"saved: {OUT}")
    print(json.dumps({
        "topic": final_obj.get("topic"),
        "summary_count": len(final_obj.get("executive_summary", [])),
        "source_count": final_obj.get("source_count"),
    }, ensure_ascii=False))
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • lab25_multiagent_research_pack.py 파일 생성
  • 코드에 CodeAgent 3개(시장/기술/오케스트레이터) 확인

4) 실행 및 결과 저장

• 도구: Python
• 입력: TOPIC 문자열(코드 상단)
• 실행명령:

python lab25_multiagent_research_pack.py
cat research_pack.json

• 성공판정:
  • saved: research_pack.json 출력
  • JSON에 executive_summary 5개 라인
  • specialists 2개 블록 + source_count 값 존재

5) 품질 게이트(재현 체크)

• 도구: Python
• 입력: research_pack.json
• 실행명령:

python - <<'PY'
import json
from urllib.parse import urlparse
 
obj = json.load(open('research_pack.json', encoding='utf-8'))
 
assert isinstance(obj.get('executive_summary'), list), 'executive_summary must be list'
assert len(obj['executive_summary']) == 5, 'executive_summary must be 5 lines'
assert isinstance(obj.get('specialists'), list) and len(obj['specialists']) == 2, 'specialists must be 2'
 
total = 0
for sp in obj['specialists']:
    assert len(sp.get('insights', [])) == 3, f"{sp.get('role')} insights must be 3"
    assert len(sp.get('sources', [])) >= 2, f"{sp.get('role')} sources must be >=2"
    for s in sp['sources']:
        u = s.get('url', '')
        p = urlparse(u)
        assert p.scheme in ('http', 'https') and p.netloc, f'invalid url: {u}'
    total += len(sp['sources'])
 
assert obj.get('source_count') == total, 'source_count mismatch'
print('PASS: 품질 게이트 통과')
PY

• 성공판정:
  • PASS: 품질 게이트 통과 출력

---

트러블슈팅 (3개 이상)

1. AuthenticationError 또는 모델 호출 실패

• 원인: API 키 미설정/오타
• 점검:

python - <<'PY'
import os
print('OPENAI_API_KEY set =', bool(os.getenv('OPENAI_API_KEY')))
print('MODEL_ID =', os.getenv('MODEL_ID'))
PY

• 조치: 환경변수 재설정 후 재실행

2. DuckDuckGoSearchTool ImportError

• 원인: 패키지 버전 불일치
• 조치:

pip install -U smolagents duckduckgo-search
python - <<'PY'
from smolagents import DuckDuckGoSearchTool
print('ok')
PY

3. JSON 파싱 실패 (json.loads)

• 원인: 모델 출력에 설명 문장/코드블록이 섞임
• 조치:
  • 프롬프트에 JSON만 반환 유지
  • strip_code_fence()로 코드블록 제거 후 파싱

4. source_count mismatch 품질 게이트 실패

• 원인: 병합 시 source_count 계산 누락/오류
• 조치:
  • 오케스트레이터 프롬프트에 전체 source 합 규칙 고정
  • 검증 스크립트 실패 시 재실행 전 specialists[].sources 개수 먼저 점검

5. 검색 품질 낮음(중복/약한 출처)

• 원인: TOPIC이 너무 넓거나 모호함
• 조치:
  • TOPIC을 산업/지역/기간으로 좁혀 재실행
  • 예: 2026년 한국 SaaS 기업의 AI 에이전트 운영 사례 3가지

---

체크리스트

• 3개 에이전트(시장/기술/오케스트레이터) 실행 성공
• research_pack.json 저장 완료
• 5줄 요약 + 역할별 인사이트/출처 형식 충족
• 품질 게이트 스크립트 PASS
• 트러블슈팅 3개 이상 재현/정리

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI로 초안을 작성하고, 사람이 실습 재현성(도구/입력/실행명령/성공판정), 링크 유효성, 문서 형식, 내부 링크를 검토해 최종 확정했다.