🤗 15. 본편 08: 웹검색 요약 실습

이번 편은 **“질문을 받아 웹 검색 → 핵심 3줄 요약”**까지 자동으로 처리하는 최소 에이전트를 만든다.
핵심은 복잡한 프레임워크가 아니라, 재현 가능한 실행 단계와 성공 판정 기준을 먼저 고정하는 것이다.

• 이전 편: HF-Agents-14-본편-07-ManagedAgent-위임-패턴과-팀-오케스트레이션
• 다음 실습 확장 포인트: 검색 품질 평가셋을 붙여 eval 자동화

한 줄 결론

초보자는 “작동하는 1개 에이전트 + 명확한 성공판정”부터 시작하면, 이후 멀티에이전트 확장이 훨씬 쉬워진다.

flowchart LR
  U[사용자 질문] --> A[CodeAgent]
  A --> T[WebSearchTool 호출]
  T --> R[검색 결과]
  R --> S[3줄 요약 생성]
  S --> O[최종 응답 + 출처]

---

실습 목표

• smolagents 기반 최소 웹검색 요약 에이전트를 실행한다.
• 입력/출력 계약을 고정해 실패 원인을 빠르게 진단한다.
• 실행 성공 여부를 눈으로 확인 가능한 기준으로 판정한다.

준비물

• 도구: Python 3.10+, 터미널, 인터넷 연결
• 입력: 모델 API 키 1개 (예: OpenAI 호환 키)
• 작업 폴더 예시: ~/hf-agents-lesson15

실무 팁: 팀 온보딩 문서에는 “지원 Python 버전”과 “검증한 패키지 버전”을 같이 남기면 재현률이 올라간다.

---

1) 환경 준비

• 도구: 터미널
• 입력: 가상환경 + 패키지 설치
• 실행명령:

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

• 성공판정:
  • (.venv) 프롬프트 표시
  • pip 설치 에러 없음

2) 환경변수 설정

• 도구: 터미널
• 입력: API 키
• 실행명령:

export OPENAI_API_KEY="YOUR_API_KEY"
# 필요 시 모델명도 명시
export MODEL_ID="openai/gpt-4o-mini"

• 성공판정:
  • echo $OPENAI_API_KEY | wc -c 결과가 1보다 큼

3) 에이전트 코드 작성

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

cat > lesson15_web_summary_agent.py <<'PY'
from __future__ import annotations
 
import os
from smolagents import CodeAgent, DuckDuckGoSearchTool, LiteLLMModel
 
 
def build_agent() -> CodeAgent:
    model_id = os.getenv("MODEL_ID", "openai/gpt-4o-mini")
    model = LiteLLMModel(model_id=model_id)
    tools = [DuckDuckGoSearchTool()]
 
    system_prompt = """
너는 실무형 리서치 보조 에이전트다.
반드시 아래 형식으로 답해라.
FINAL:
- summary_1: ...
- summary_2: ...
- summary_3: ...
- sources: [URL1, URL2]
""".strip()
 
    return CodeAgent(
        tools=tools,
        model=model,
        additional_authorized_imports=["json", "re"],
        system_prompt=system_prompt,
    )
 
 
def main() -> None:
    question = "2026년 AI 에이전트 도입 시 중소팀이 먼저 얻는 운영상 이점 3가지를 설명해줘"
    agent = build_agent()
    result = agent.run(question)
    print(result)
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • lesson15_web_summary_agent.py 파일 생성
  • 코드에 DuckDuckGoSearchTool, CodeAgent 포함

4) 실행

• 도구: Python
• 입력: 사용자 질문 1개(코드 내 기본값)
• 실행명령:

python lesson15_web_summary_agent.py

• 성공판정:
  • 출력에 FINAL: 문자열 포함
  • summary_1~3 항목 존재
  • sources에 URL 2개 이상 포함

5) 실패 복구(초보자 필수)

• 도구: 터미널
• 입력: 에러 유형별 점검
• 실행명령:

# 패키지 확인
pip show smolagents litellm duckduckgo-search
 
# 키 확인
python - <<'PY'
import os
print("OPENAI_API_KEY exists:", bool(os.getenv("OPENAI_API_KEY")))
print("MODEL_ID:", os.getenv("MODEL_ID", "openai/gpt-4o-mini"))
PY

• 성공판정:
  • 누락 패키지/환경변수를 즉시 식별 가능

---

실무 적용 포인트

1. 출력 계약(FINAL 블록) 고정
   → n8n/스크립트에서 안정적으로 파싱 가능
2. 도구 1개로 시작 후 확장
   → 검색 1개 안정화 뒤 계산/문서작성 툴 추가가 안전
3. 성공판정 기준을 코드 옆에 문서화
   → 팀원 간 “작동한다”의 기준을 통일
4. 오류 진단 명령을 함께 제공
   → 초보자 지원 비용을 크게 줄임

---

자주 막히는 문제와 해결

1. AuthenticationError 또는 키 관련 오류

   • 원인: 환경변수 미설정/오타
   • 해결: export OPENAI_API_KEY=... 재설정 후 동일 셸에서 재실행

2. 검색 결과가 비어 있음

   • 원인: 네트워크 제한 또는 일시적 검색 실패
   • 해결: 질문을 더 구체화(기간/키워드 추가), 잠시 후 재시도

3. 출력 형식이 FINAL 계약과 다름

   • 원인: 시스템 프롬프트가 약함
   • 해결: 형식 강제 문구(필드명/개수) 더 명시

---

체크리스트

• 가상환경 생성 및 패키지 설치 완료
• API 키/모델 환경변수 확인
• python lesson15_web_summary_agent.py 정상 출력
• FINAL 블록 + 출처 URL 2개 이상 확인
• 실패 복구 명령으로 원인 재현 가능

참고 링크 (우선순위)

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

생성형 AI 활용 고지

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