🤗 30. 본편 18: smolagents 실행로그 추적과 실패 재시도 패턴

이번 편은 에이전트를 “돌아가게” 만드는 것보다 한 단계 더 나아가, 실패해도 다시 시도하고 실행 흔적을 남기는 운영형 패턴을 다룬다.

flowchart LR
  A[task.txt 입력] --> B[CodeAgent 실행]
  B --> C[tool 호출]
  C -->|성공| D[result.json 저장]
  C -->|실패| E[retry 1회 재시도]
  E -->|재성공| D
  E -->|재실패| F[error 로그 저장]
  B --> G[run_log.jsonl 누적]

실습 목표

1. CodeAgent + 커스텀 도구를 실행한다.
2. 도구 실패 시 1회 자동 재시도를 붙인다.
3. 실행 로그(run_log.jsonl)를 남긴다.
4. 결과 파일/로그 파일/성공 조건으로 재현성을 검증한다.

---

1) 준비

Step 1-1. 작업 폴더 생성

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

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

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

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. task.txt 생성

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

cat <<'TXT' > task.txt
이번 주 고객문의 로그를 3줄 요약해줘.
- 지연 배송 문의가 늘었다.
- 결제 오류가 간헐적으로 발생했다.
- 환불 문의는 전주 대비 감소했다.
TXT

• 성공판정:

test -f task.txt && echo FILE_OK

---

3) 에이전트 코드 작성

Step 3-1. day18_observe_retry.py 저장

• 도구: Python 파일
• 입력: 아래 코드

import json
import random
from datetime import datetime, timezone
from pathlib import Path
 
from smolagents import CodeAgent, HfApiModel, tool
 
 
def log_event(path: Path, payload: dict):
    payload["ts"] = datetime.now(timezone.utc).isoformat()
    with path.open("a", encoding="utf-8") as f:
        f.write(json.dumps(payload, ensure_ascii=False) + "\n")
 
 
@tool
def unstable_save(path: str, content: str) -> str:
    """가끔 실패하는 저장 도구(실습용)."""
    if random.random() < 0.4:
        raise RuntimeError("temporary io error")
    Path(path).write_text(content, encoding="utf-8")
    return f"saved:{path}"
 
 
@tool
def save_with_retry(path: str, content: str) -> str:
    """실패 시 1회 재시도 후 저장한다."""
    try:
        return unstable_save(path, content)
    except Exception:
        return unstable_save(path, content)
 
 
def build_agent() -> CodeAgent:
    model = HfApiModel("Qwen/Qwen2.5-72B-Instruct")
    return CodeAgent(
        tools=[save_with_retry],
        model=model,
        max_steps=6,
    )
 
 
if __name__ == "__main__":
    random.seed(7)  # 재현 가능한 실습을 위한 고정 시드
 
    run_log = Path("run_log.jsonl")
    out_file = Path("result.json")
    task_text = Path("task.txt").read_text(encoding="utf-8")
 
    if run_log.exists():
        run_log.unlink()
    if out_file.exists():
        out_file.unlink()
 
    agent = build_agent()
    prompt = f"""
아래 텍스트를 한국어 3줄로 요약해.
반드시 save_with_retry 도구를 사용해서 result.json에 아래 JSON 형태로 저장해.
{{"summary": ["...", "...", "..."]}}
 
입력:
{task_text}
"""
 
    log_event(run_log, {"event": "start"})
    try:
        result = agent.run(prompt)
        log_event(run_log, {"event": "finish", "result": str(result)})
        print("[FINISH] run completed")
    except Exception as e:
        log_event(run_log, {"event": "error", "message": str(e)})
        print(f"[ERROR] {e}")

• 성공판정:

python -m py_compile day18_observe_retry.py

오류 없이 종료되면 통과.

---

4) 실행 및 검증

Step 4-1. 실행

• 도구: day18_observe_retry.py
• 입력: task.txt
• 실행명령:

python day18_observe_retry.py

• 성공판정: [FINISH] run completed 출력

Step 4-2. 검증

• 도구: 터미널
• 입력: result.json, run_log.jsonl
• 실행명령:

test -f result.json && echo RESULT_OK
test -f run_log.jsonl && echo LOG_OK
grep -E '"summary"' result.json >/dev/null && echo FIELD_OK

• 성공판정: RESULT_OK, LOG_OK, FIELD_OK 3개 모두 출력

---

5) 초보자용 쉬운 설명

• 에이전트는 잘 동작할 때보다, 가끔 실패할 때 운영 난도가 급격히 올라간다.
• 이번 패턴은 아주 단순하다.
  1. 실패 가능 도구를 감싼다.
  2. 1회 재시도한다.
  3. 시작/종료/오류를 로그로 남긴다.
• 이 3가지만 해도 “왜 실패했는지 모르는 상태”를 크게 줄일 수 있다.

6) 실무 적용 포인트

1. 야간 배치 안정화: 일시 오류(네트워크/파일락)로 전체 실패하는 비율 감소.
2. 장애 분석 시간 단축: run_log.jsonl로 실패 지점 추적이 쉬워짐.
3. 운영 표준화: 모든 도구에 동일한 retry/log 래퍼를 적용 가능.
4. 확장 방향: 다음 단계에서 재시도 횟수, 백오프, 알림(슬랙/이메일) 추가.

체크리스트

• smolagents 설치 완료
• task.txt 생성 완료
• day18_observe_retry.py 문법 검사 통과
• 실행 후 result.json 생성
• 실행 후 run_log.jsonl 생성
• summary 필드 존재 확인

참고 링크 (우선순위)

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

생성형 AI 활용 고지

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