🤗 01. 에이전트 기초: 이론 + 첫 실습

이번 1편은 “에이전트가 뭔지 이해했다”에서 끝나지 않고, 실제 업무에 바로 적용 가능한 **초기 설계안(v0.1)**을 완성하는 데 목표가 있다. 개념을 짧게 정리하고, 사례를 충분히 본 뒤, 과제로 손에 익히는 흐름으로 구성했다.

flowchart TD
  A[사용자 목표] --> B[문제 정의]
  B --> C[도구 선택]
  C --> D[실행 루프]
  D --> E[결과 검증]
  E --> F[운영 자동화]

0) 30초 요약

• LLM은 생성 엔진, 에이전트는 실행 시스템이다.
• 에이전트의 핵심 가치는 답변 품질 + 반복 가능성 + 자동화 가능성이다.
• 오늘 산출물은 “내 업무에 맞는 최소 에이전트 설계서 1개”다.

1) 왜 에이전트가 실무를 바꾸는가

기존에는 사람이 검색 → 정리 → 판단 → 보고를 반복했다. 에이전트는 이 과정을 루프로 고정한다.

1. 속도 향상: 반복 작업 시간을 줄임
2. 품질 안정화: 검증 규칙을 내장함
3. 운영 확장성: 예약 실행/조건 기반 실행 가능

결국 중요한 건 “잘 답한 1회”가 아니라 “같은 품질로 계속 돌아가는 구조”다.

2) 핵심 개념 3개

2-1) LLM vs Agent

• LLM: 텍스트 생성/요약/추론을 잘함
• Agent: 목표와 절차를 따라 도구를 호출해 작업을 완수함

예시:

• LLM: “시장 조사 방법은 이렇게 하세요.”
• Agent: 자료 수집 → 분류 → 비교표 생성 → 보고서 작성 → 전달까지 수행

2-2) Tool Calling

현실 데이터는 도구를 통해 접근해야 한다.

• 검색: 최신 이슈 수집
• 캘린더/메일: 일정/요청 처리
• 파일/DB/API: 결과 저장과 자동화

sequenceDiagram
  participant U as User
  participant A as Agent
  participant T1 as Search
  participant T2 as Fetch
  participant T3 as Summarize
  U->>A: 오늘 AI 뉴스 브리핑 만들어줘
  A->>T1: web_search("today AI news")
  T1-->>A: 링크 목록
  A->>T2: fetch_article(urls)
  T2-->>A: 본문 텍스트
  A->>T3: summarize(text)
  T3-->>A: 요약 결과
  A-->>U: 5줄 브리핑 + 링크

2-3) Plan → Act → Observe

• Plan: 작업 단계와 기준 설정
• Act: 도구 호출 및 실행
• Observe: 결과 품질 점검 후 보정

이 루프가 있어야 에이전트가 “한 번 반짝”이 아니라 “운영 가능한 시스템”이 된다.

3) 사례로 이해하기 (풍부한 실무 예시)

사례 A: 아침 AI 뉴스 브리핑 자동화

상황: 매일 아침 AI 뉴스를 직접 찾고 정리하느라 40분 소요

• 목표: 오전 7시, 3개 핵심 뉴스 + 왜 중요한지 1줄씩
• 도구: web_search, fetch_article, summarize
• 검증: 신뢰 도메인만 허용, 중복 기사 제거
• 핵심 변화: 40분 → 7분 검토 중심으로 전환

사례 B: 고객 문의 1차 분류

상황: CS 메일이 섞여 들어와 우선순위 판단이 느림

• 목표: 문의를 긴급/일반/결제/환불/기술문의로 자동 태깅
• 도구: 메일 수집 + 분류 룰 + 요약 생성
• 검증: 긴급 키워드(장애/결제오류/환불요청) 누락 여부
• 핵심 변화: 응답 SLA 준수율 개선

사례 C: 투자 메모 초안 생성

상황: 매주 종목/회사 검토 메모 작성 시간이 길다

• 목표: 핵심 지표·리스크·체크포인트 1페이지 초안 생성
• 도구: 데이터 조회 + 템플릿 채움 + 요약
• 검증: 숫자 출처 표기, 과장 표현 금지
• 핵심 변화: “빈 문서 시작” 부담 감소, 검토 중심 전환

사례 D: 콘텐츠 제작 파이프라인

상황: 영상 기획→스크립트→썸네일 문구까지 사람이 순차 처리

• 목표: 주제 입력 시 기획안·훅·목차·썸네일 카피 동시 생성
• 도구: 리서치 + 템플릿 생성 + 스타일 가이드 적용
• 검증: 톤 일관성, 길이 제한, 금지 표현 필터
• 핵심 변화: 제작 준비 시간이 크게 단축

4) 칠판 치트시트

아래 5문장으로 설계하면 대부분의 초안이 완성된다.

1. 목표: 무엇을 언제 어떤 형식으로 낼 것인가?
2. 입력: 어떤 데이터가 필요한가?
3. 도구: 어떤 함수/API를 호출할 것인가?
4. 규칙: 실패와 예외를 어떻게 처리할 것인가?
5. 검증: 결과가 합격인지 어떻게 판단할 것인가?

5) 실습 A — 내 업무 에이전트 설계 (기초)

Step 1. 목표 한 줄

예시: 매일 오전 7시, AI 뉴스 3개를 5줄 브리핑으로 보고한다.

Step 2. 입력/출력 정의

• 입력: 키워드, 날짜, 출처 조건
• 산출물: 제목/핵심/의미/링크

Step 3. 도구 목록 작성

• web_search(query, count)
• fetch_article(url)
• summarize(text)

Step 4. 실행 단계 설계

1) 검색
2) 신뢰 출처 필터링
3) 본문 추출
4) 요약
5) 중복 제거
6) 최종 브리핑 생성

Step 5. 검증 기준 설정

• 출처 신뢰도
• 사실/추측 구분
• 행동 제안 포함 여부

6) 실습 B — 실패 방지 설계 (중급)

flowchart LR
  A[검색 0건] --> B[대체 키워드 세트 호출]
  C[저품질 출처 포함] --> D[화이트리스트 강제]
  E[중복 기사 과다] --> F[유사도 기반 제거]
  G[요약 과장] --> H[근거문장 1개 첨부]

필수 예외처리:

1. 결과 0건일 때 재시도 전략
2. 출처 품질 기준 미달 시 제외 규칙
3. 중복 제거 기준(제목/URL 유사도)
4. 요약 과장 탐지(추측어 필터)

7) 실습 C — 운영 관점 확장 과제 (상급)

아래 과제는 실제 운영 가능한 수준으로 끌어올리는 훈련이다.

과제 1) KPI 정의 과제

• 목표 작업 1개를 정하고 전/후 지표 작성
• 필수 지표: 처리시간, 오류율, 재작업률

과제 2) 안전장치 과제

• “잘못 실행되면 위험한 작업” 3개를 적고
• 각 작업별 승인 단계(사람 검토)를 설계

과제 3) 출력 포맷 표준화 과제

• 결과물을 템플릿으로 강제
• 예: 요약 3줄 + 근거 2줄 + 링크 3개

과제 4) 스케줄링 과제

• 수동 실행/예약 실행/조건 실행을 구분하고
• 어떤 작업을 어떤 방식으로 돌릴지 표로 정리

과제 5) 재현성 과제

• 같은 입력으로 3회 실행해 결과 일관성 점검
• 편차 원인과 보정 방법 기록

8) 코드 실행 가이드 (설치 → 붙여넣기 → 실행)

아래 순서대로 하면 처음인 사람도 바로 실행할 수 있다.

8-0) 5분 퀵스타트 (먼저 1회 성공)

1. 문서 하단 실습 파일 다운로드에서 hf-agents-day1-starter.zip을 받는다.
2. 압축을 풀고 폴더로 이동한다.
3. 아래 3줄만 먼저 실행한다.

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt && python day1.py

목표: 우선 1회 정상 실행을 확인한 뒤, 세부 코드를 이해하는 순서로 진행한다.

8-1) 준비물

• Python 3.10+
• 터미널(맥: Terminal/iTerm, 윈도우: PowerShell)
• 코드 편집기(VS Code 권장)

8-2) 프로젝트 폴더 만들기

mkdir hf-agents-day1
cd hf-agents-day1
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\\Scripts\\activate

8-3) 라이브러리 설치

A. 최소 실습(순수 Python 예제)

아무 추가 라이브러리 없이 실행 가능.

B. Hugging Face 스타일 실습(smolagents)

pip install -U pip
pip install smolagents

선택적으로 자주 쓰는 패키지:

pip install requests python-dotenv

8-4) 코드 붙여넣기 방법

1. VS Code에서 hf-agents-day1 폴더 열기
2. day1.py 파일 생성
3. 아래 예제 코드를 그대로 붙여넣기
4. 저장(Ctrl/Cmd + S)

8-5) 실행 방법

python day1.py

8-5-1) 실행 결과 예시 (정상/실패)

정상 예시:

1. AI News A
- ...
- https://example.com/a
 
2. AI News B
- ...
- https://example.com/b

실패 예시:

python: command not found

또는

ModuleNotFoundError: No module named 'smolagents'

8-6) 자주 나는 오류와 해결

• python: command not found
  • python3 day1.py로 실행
• ModuleNotFoundError: smolagents
  • 가상환경 활성화 확인 후 pip install smolagents
• API/모델 호출 오류
  • 처음에는 예제 1(순수 Python)부터 먼저 성공시키고, 그 다음 예제 2로 확장

8-7) 코드 활용법(어떻게 내 업무에 붙일까)

• web_search("latest AI news") → 내 주제 키워드로 변경
• 출력 필드(title/summary/url) → 내 보고 포맷으로 변경
• 실행 함수를 스케줄러(cron 등)와 연결하면 자동 보고 루프 완성

---

아래 코드는 학습용 최소 예제다. 실제 프로덕션에는 에러 처리/로깅/권한 제어를 추가해야 한다.

예제 1) 순수 Python으로 Tool Calling 흉내내기

from typing import List, Dict
 
def web_search(query: str) -> List[Dict[str, str]]:
    # 실제 구현에서는 검색 API 호출
    return [
        {"title": "AI News A", "url": "https://example.com/a", "snippet": "..."},
        {"title": "AI News B", "url": "https://example.com/b", "snippet": "..."},
        {"title": "AI News C", "url": "https://example.com/c", "snippet": "..."},
    ]
 
def summarize(text: str) -> str:
    # 실제 구현에서는 LLM 요약 호출
    return text[:120] + "..."
 
def run_daily_briefing():
    results = web_search("latest AI news")
    top3 = results[:3]
    report = []
    for item in top3:
        report.append({
            "title": item["title"],
            "summary": summarize(item["snippet"]),
            "url": item["url"],
        })
    return report
 
if __name__ == "__main__":
    for i, row in enumerate(run_daily_briefing(), 1):
        print(f"{i}. {row['title']}\n- {row['summary']}\n- {row['url']}\n")

예제 2) Hugging Face 생태계 스타일(학습용 스켈레톤)

# pip install smolagents
from smolagents import CodeAgent, tool
 
@tool
def get_weather(city: str) -> str:
    """Return weather summary for a city."""
    # 실제 구현: 날씨 API 호출
    return f"{city}: 3°C, cloudy"
 
agent = CodeAgent(
    tools=[get_weather],
    model="Qwen/Qwen2.5-Coder-32B-Instruct"  # 예시. 환경에 맞게 변경
)
 
result = agent.run("서울 내일 날씨 요약하고 외출 팁 한 줄 추가해줘")
print(result)

예제 3) 실행 루프를 명시한 의사코드

def agent_loop(user_goal):
    plan = make_plan(user_goal)             # Plan
    raw = call_tools(plan)                  # Act
    checked = validate(raw, rules=[
        "출처 신뢰도",
        "중복 제거",
        "추측 표현 금지",
    ])                                      # Observe
    return format_output(checked)

9) 제출물 템플릿 (복붙)

### Agent Design v0.1
- 목표:
- 사용자:
- 입력 데이터:
- 출력 포맷:
- 도구 목록:
- 실행 단계:
- 예외 처리:
- 검증 기준:
- 운영 주기(수동/예약/조건):
- KPI(시간/오류/재작업):

9) 자기평가 루브릭

• A (실무 투입 가능): 목표/도구/예외/검증/KPI 모두 명확
• B (보완 후 가능): 기본 루프는 있으나 예외·지표 부족
• C (학습 단계): 설명 위주, 실행 구조 불명확

10) 자주 하는 실수 TOP 7

1. 목표가 추상적임 (“잘 정리해줘”)
2. 도구 없이 모델에게만 맡김
3. 출력 형식 미정의
4. 예외처리 부재
5. 검증 기준 부재
6. 자동 실행 전에 샌드박스 테스트 생략
7. 지표 없이 “좋아진 것 같음”으로 판단

11) 오늘 과제 제출 체크리스트

• 기초 과제(A) 완료
• 실패 방지(B) 완료
• 운영 확장(C) 2개 이상 완료
• 설계서 v0.1 제출
• 자기평가(A/B/C) 기록

12) 다음 편 예고 (02편)

02편은 오늘 만든 설계를 실제 Tool Calling 구조로 연결한다.

• 함수 시그니처 설계
• 호출 순서 고정
• 출력 포맷 강제
• 최소 실행 데모

참고 자료 (공식)

• Hugging Face Agents Course GitHub: https://github.com/huggingface/agents-course
• Hugging Face Learn (Agents Course): https://huggingface.co/learn/agents-course
• smolagents 공식 문서: https://huggingface.co/docs/smolagents

실습 파일 다운로드

• 실습 가이드 README
• day1.py
• requirements.txt
• hf-agents-day1-starter.zip

파일이 브라우저에서 바로 열리면, 우클릭 후 **“다른 이름으로 저장”**을 선택해 다운로드하면 됩니다.

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 작성 및 구조화를 수행했으며, 최종 공개 전 사람이 검토·보정한다.