🤗 22. 실습편 06: smolagents 웹리서치 브리핑 미니프로젝트 핸즈온 1

이번 편은 **“웹에서 근거를 찾고, 5줄 브리핑으로 정리하는 리서치 에이전트”**를 직접 만드는 미니 프로젝트다.
핵심은 아래 4가지를 재현 가능하게 끝내는 것이다.

• 도구 설치와 실행 환경 준비

• 검색 도구를 붙인 CodeAgent 실행

• 결과를 JSON 파일로 저장

• 실패 패턴 3가지 이상을 스스로 복구

• 이전 편: 🤗 21. 본편 12

• 다음 편 예고: 실습편 06-2 (검증 루프 추가: 근거 링크 누락 자동 점검)

flowchart TD
  A[사용자 주제 입력] --> B[CodeAgent + DuckDuckGoSearchTool 실행]
  B --> C[웹 검색/요약]
  C --> D[구조화 결과(JSON) 생성]
  D --> E[briefing_result.json 저장]
  E --> F{검증 통과?}
  F -- Yes --> G[완료]
  F -- No --> H[프롬프트/환경 수정 후 재실행]
  H --> B

0) 실습 목표

입력 주제 1개를 넣으면, 에이전트가 웹 근거를 찾아 5줄 브리핑 + 출처를 JSON으로 저장하게 만든다.

---

1) 환경 준비

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

mkdir -p ~/hf-agents-lab22
cd ~/hf-agents-lab22
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 키 + 모델 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 > lab22_research_briefing.py <<'PY'
from __future__ import annotations
 
import json
import os
from datetime import datetime
from pathlib import Path
 
from smolagents import CodeAgent, DuckDuckGoSearchTool, LiteLLMModel
 
OUT = Path("briefing_result.json")
TOPIC = "한국 AI 에이전트 시장에서 2026년에 실무자가 바로 적용할 만한 트렌드 3가지"
 
PROMPT = f"""
아래 주제에 대해 웹 검색 기반으로 5줄 브리핑을 작성하라.
주제: {TOPIC}
 
출력은 반드시 JSON 문자열 1개만 반환:
{{
  "topic": "...",
  "summary_5_lines": ["...", "...", "...", "...", "..."],
  "sources": [
    {{"title": "...", "url": "..."}},
    {{"title": "...", "url": "..."}},
    {{"title": "...", "url": "..."}}
  ]
}}
 
규칙:
- sources는 최소 3개
- URL은 실제 웹 주소여야 함
- 추정/환각 금지, 찾지 못하면 찾지 못했다고 명시
"""
 
 
def main() -> None:
    model = LiteLLMModel(model_id=os.getenv("MODEL_ID", "openai/gpt-4o-mini"))
    agent = CodeAgent(
        model=model,
        tools=[DuckDuckGoSearchTool()],
        max_steps=8,
        additional_authorized_imports=["json", "datetime"],
    )
 
    raw = agent.run(PROMPT)
    text = str(raw)
 
    # 모델 출력이 코드블록으로 감싸질 수 있어 방어적으로 처리
    text = text.strip()
    if text.startswith("```"):
        text = text.strip("`")
        text = text.replace("json", "", 1).strip()
 
    obj = json.loads(text)
    obj["generated_at"] = datetime.now().isoformat(timespec="seconds")
 
    OUT.write_text(json.dumps(obj, ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"saved: {OUT}")
    print(json.dumps({
        "topic": obj.get("topic"),
        "summary_count": len(obj.get("summary_5_lines", [])),
        "source_count": len(obj.get("sources", [])),
    }, ensure_ascii=False))
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • lab22_research_briefing.py 생성
  • 코드에 DuckDuckGoSearchTool, CodeAgent 확인

4) 실행 및 결과 저장

• 도구: Python
• 입력: TOPIC 문자열
• 실행명령:

python lab22_research_briefing.py
cat briefing_result.json

• 성공판정:
  • saved: briefing_result.json 출력
  • JSON에 summary_5_lines(5개), sources(3개 이상) 포함

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

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

python - <<'PY'
import json
from urllib.parse import urlparse
 
obj = json.load(open('briefing_result.json', encoding='utf-8'))
 
assert isinstance(obj.get('summary_5_lines'), list), 'summary_5_lines must be list'
assert len(obj['summary_5_lines']) == 5, 'summary must be exactly 5 lines'
assert isinstance(obj.get('sources'), list) and len(obj['sources']) >= 3, 'sources >= 3 required'
 
for s in obj['sources']:
    u = s.get('url', '')
    p = urlparse(u)
    assert p.scheme in ('http', 'https') and p.netloc, f'invalid url: {u}'
 
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. ImportError: DuckDuckGoSearchTool

• 원인: smolagents 구버전 또는 패키지 불일치
• 조치:

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

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

• 원인: 모델이 설명 문장을 섞어 출력
• 조치:
  • 프롬프트에 JSON 문자열 1개만 규칙 유지
  • 필요 시 코드에서 코드블록/잡문 제거 후 파싱

4. 품질 게이트에서 URL 검증 실패

• 원인: sources.url이 빈 값 또는 비정상 문자열
• 조치:
  • 프롬프트에 URL은 실제 웹 주소 규칙 강화
  • sources 최소 개수와 형식을 assert로 고정

---

체크리스트

• CodeAgent + DuckDuckGoSearchTool 실행 성공
• briefing_result.json 저장 완료
• 5줄 요약 + 출처 3개 이상 충족
• 품질 게이트 스크립트 PASS
• 트러블슈팅 3개 이상 재현/정리

참고 링크 (우선순위)

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

생성형 AI 활용 고지

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