🤗 27. 본편 16: CSV 리포트 자동화

이번 편은 “CSV 원본 → 에이전트 분석 → Markdown 보고서 저장” 흐름을 한 번에 재현한다.
핵심은 화려한 데모가 아니라, 팀에서 매일 반복 가능한 자동화 패턴을 만드는 것이다.

flowchart LR
  A[orders.csv 입력] --> B[CodeAgent]
  B --> C[load_orders 도구]
  B --> D[top_products 도구]
  B --> E[write_report 도구]
  E --> F[daily_report.md 생성]
  F --> G[사람 검토 후 공유]

실습 목표

1. smolagents CodeAgent를 실행한다.
2. CSV를 읽는 커스텀 도구를 연결한다.
3. 에이전트가 분석 후 daily_report.md를 저장하게 한다.
4. 성공 판정 기준(파일 생성/핵심 수치 포함)으로 재현성을 확인한다.

---

1) 준비

Step 1-1. 작업 폴더 생성

• 도구: 터미널
• 입력: 없음
• 실행명령:

mkdir -p ~/hf-agents-day16 && cd ~/hf-agents-day16

• 성공판정: pwd가 ~/hf-agents-day16

Step 1-2. 가상환경 + 패키지 설치

• 도구: Python 3.10+
• 입력: 없음
• 실행명령:

python3 -m venv .venv
source .venv/bin/activate
pip install -U smolagents

• 성공판정:

python -c "import smolagents; print('OK')"

출력 OK

Step 1-3. 모델 인증 키 설정

• 도구: 환경변수
• 입력: HF_TOKEN (또는 환경에 맞는 모델 키)
• 실행명령:

export HF_TOKEN="hf_xxx"

• 성공판정:

echo ${HF_TOKEN:+set}

출력 set

---

2) 샘플 데이터 만들기

Step 2-1. CSV 생성

• 도구: 텍스트 파일
• 입력: 아래 내용
• 실행명령:

cat <<'CSV' > orders.csv
order_id,product,qty,unit_price,channel
1001,Keyboard,2,45000,smartstore
1002,Mouse,1,25000,coupang
1003,Keyboard,1,45000,smartstore
1004,Monitor,1,220000,11st
1005,Mouse,3,25000,coupang
CSV

• 성공판정:

wc -l orders.csv

6 orders.csv이면 정상(헤더 1 + 데이터 5)

---

3) 에이전트 코드 작성

Step 3-1. day16_csv_report.py 저장

• 도구: Python 파일
• 입력: 아래 코드
• 실행명령: 파일 생성 후 저장

import csv
import json
from collections import Counter
from pathlib import Path
 
from smolagents import CodeAgent, HfApiModel, tool
 
 
@tool
def load_orders(csv_path: str) -> str:
    """주문 CSV를 읽어 총매출/총수량/주문건수를 JSON 문자열로 반환한다."""
    rows = []
    with open(csv_path, "r", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        rows = list(reader)
 
    total_qty = 0
    total_revenue = 0
    for r in rows:
        qty = int(r["qty"])
        unit_price = int(r["unit_price"])
        total_qty += qty
        total_revenue += qty * unit_price
 
    return json.dumps(
        {
            "orders": len(rows),
            "total_qty": total_qty,
            "total_revenue": total_revenue,
        },
        ensure_ascii=False,
    )
 
 
@tool
def top_products(csv_path: str, top_n: int = 3) -> str:
    """판매수량 기준 상위 상품을 JSON 문자열로 반환한다."""
    counter = Counter()
    with open(csv_path, "r", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        for r in reader:
            counter[r["product"]] += int(r["qty"])
 
    top = counter.most_common(top_n)
    return json.dumps(
        [{"product": p, "qty": q} for p, q in top],
        ensure_ascii=False,
    )
 
 
@tool
def write_report(path: str, content: str) -> str:
    """마크다운 리포트를 파일로 저장한다."""
    Path(path).write_text(content, encoding="utf-8")
    return f"saved:{path}"
 
 
def build_agent() -> CodeAgent:
    model = HfApiModel("Qwen/Qwen2.5-72B-Instruct")
    return CodeAgent(
        tools=[load_orders, top_products, write_report],
        model=model,
        max_steps=6,
    )
 
 
if __name__ == "__main__":
    agent = build_agent()
    prompt = """
다음 작업을 순서대로 수행해줘.
1) orders.csv를 읽어서 총주문건수, 총수량, 총매출을 계산
2) 판매수량 기준 상위 2개 상품 추출
3) 아래 형식의 Markdown을 만들어 daily_report.md로 저장
 
형식:
# Daily Sales Report
- orders: <숫자>
- total_qty: <숫자>
- total_revenue: <숫자>
- top_products: <상품명(수량), 상품명(수량)>
- note: 자동 생성 리포트 (human review required)
 
반드시 write_report 도구를 호출해 파일을 저장해.
"""
 
    result = agent.run(prompt)
    print("[AGENT_RESULT]", result)

• 성공판정:

python -m py_compile day16_csv_report.py

오류 없이 종료되면 통과.

---

4) 실행 및 검증

Step 4-1. 에이전트 실행

• 도구: day16_csv_report.py
• 입력: orders.csv
• 실행명령:

python day16_csv_report.py

• 성공판정: 출력에 saved:daily_report.md 또는 daily_report.md 저장 메시지 포함

Step 4-2. 결과 파일 검증

• 도구: 터미널
• 입력: 생성된 daily_report.md
• 실행명령:

test -f daily_report.md && echo "FILE_OK"
grep -E "^# Daily Sales Report" daily_report.md && echo "TITLE_OK"
grep -E "total_revenue" daily_report.md && echo "METRIC_OK"

• 성공판정: FILE_OK, TITLE_OK, METRIC_OK 3개 모두 출력

---

5) 초보자용 쉬운 설명

• @tool 함수는 에이전트가 사용할 업무 버튼이다.
• 이번 실습은 버튼 3개만 만든다.
  • load_orders: 요약 수치 계산
  • top_products: 상위 상품 집계
  • write_report: 파일 저장
• 에이전트는 “무슨 버튼을 어떤 순서로 누를지”를 결정하고, 우리는 성공판정 체크로 결과를 검증한다.

즉, LLM의 문장 품질에만 기대지 않고, 도구 중심으로 결과물을 고정하는 방식이다.

---

6) 실무 적용 포인트

1. 일일 리포트 자동화: 쇼핑몰/광고/CS CSV를 같은 패턴으로 보고서화.
2. 검증 기준 사전합의: 파일 생성 + 핵심 지표 포함 같은 기준을 팀 룰로 고정.
3. 휴먼 리뷰 게이트: 보고서 하단에 human review required를 넣어 무검토 배포 방지.
4. 확장 경로: 다음 단계에서 Slack/Notion 업로드 도구를 추가하면 운영 자동화로 연결 가능.

---

체크리스트

• 가상환경 생성 및 smolagents 설치 완료
• orders.csv 생성 확인(6줄)
• day16_csv_report.py 문법 검사 통과
• 실행 후 daily_report.md 생성
• total_revenue 포함 여부 확인
• 사람이 결과 수치 1회 검토

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 작성했고, 예시 코드/절차/표현은 사람 검토 후 확정했다.