🤗 32. 본편 19: smolagents 메모리 상태 누적으로 반복업무 정확도 올리기

이번 편은 같은 유형의 요청이 반복될 때, 에이전트가 이전 결과를 재활용해 더 빠르고 일관되게 처리하도록 만드는 기본 패턴을 다룬다.

• 이전 편: 🤗 31. 실습편 09

flowchart LR
  A[요청 입력] --> B[CodeAgent]
  B --> C{state.json에
이전 요약 있음?}
  C -- 있음 --> D[기존 요약 보강]
  C -- 없음 --> E[신규 요약 생성]
  D --> F[save_state 도구로 저장]
  E --> F
  F --> G[result.json 출력]

실습 목표

1. state.json에 이전 결과를 저장한다.
2. 다음 실행 때 state.json을 읽어 답변 품질을 높인다.
3. 결과를 result.json으로 남겨 재현 가능하게 검증한다.

---

1) 준비

Step 1-1. 작업 폴더 생성

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

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

• 성공판정:

pwd

출력이 ~/hf-agents-day19

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. 첫 요청 생성

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

cat <<'TXT' > task.txt
고객지원 요약:
- 배송 지연 문의 증가
- 결제 실패 이슈 간헐 발생
- 환불 문의 감소
TXT

• 성공판정:

test -f task.txt && echo FILE_OK

---

3) 에이전트 코드 작성

Step 3-1. day19_stateful_agent.py 저장

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

import json
from pathlib import Path
 
from smolagents import CodeAgent, HfApiModel, tool
 
STATE_PATH = Path("state.json")
RESULT_PATH = Path("result.json")
TASK_PATH = Path("task.txt")
 
 
@tool
def load_state() -> str:
    """저장된 상태(JSON 문자열)를 읽는다. 없으면 빈 상태를 반환한다."""
    if not STATE_PATH.exists():
        return json.dumps({"history": []}, ensure_ascii=False)
    return STATE_PATH.read_text(encoding="utf-8")
 
 
@tool
def save_state(payload: str) -> str:
    """상태(JSON 문자열)를 저장한다."""
    obj = json.loads(payload)
    STATE_PATH.write_text(json.dumps(obj, ensure_ascii=False, indent=2), encoding="utf-8")
    return f"saved:{STATE_PATH}"
 
 
def build_agent() -> CodeAgent:
    model = HfApiModel("Qwen/Qwen2.5-72B-Instruct")
    return CodeAgent(
        tools=[load_state, save_state],
        model=model,
        max_steps=6,
        additional_authorized_imports=["json"],
    )
 
 
if __name__ == "__main__":
    task_text = TASK_PATH.read_text(encoding="utf-8")
 
    prompt = f"""
너는 고객지원 요약 어시스턴트다.
반드시 다음 순서로 진행해:
1) load_state 호출
2) 입력 텍스트를 3줄로 요약
3) 기존 history에 이번 요약을 추가한 JSON을 만들고 save_state 호출
4) 최종으로 아래 JSON만 반환
 
출력 스키마:
{{
  "summary": ["...", "...", "..."],
  "history_count": 0,
  "applied_memory": true
}}
 
입력:
{task_text}
"""
 
    agent = build_agent()
    result = agent.run(prompt)
 
    # 모델 출력이 문자열일 수 있어, JSON 파싱 후 파일 저장
    if isinstance(result, str):
        cleaned = result.strip().removeprefix("```json").removesuffix("```").strip()
        obj = json.loads(cleaned)
    else:
        obj = result
 
    RESULT_PATH.write_text(json.dumps(obj, ensure_ascii=False, indent=2), encoding="utf-8")
    print("saved: result.json")

• 성공판정:

python -m py_compile day19_stateful_agent.py

오류 없이 종료되면 통과

---

4) 실행 및 검증

Step 4-1. 1차 실행

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

python day19_stateful_agent.py
cat result.json
cat state.json

• 성공판정:
  • saved: result.json 출력
  • state.json의 history 길이 1

Step 4-2. 2차 실행(메모리 적용 확인)

• 도구: 텍스트 파일 + Python
• 입력: 다른 요청
• 실행명령:

cat <<'TXT' > task.txt
고객지원 요약:
- 배송 지연 문의는 비슷한 수준
- 결제 실패 이슈 감소
- 반품 문의 소폭 증가
TXT
 
python day19_stateful_agent.py
python - <<'PY'
import json
state = json.load(open('state.json', encoding='utf-8'))
res = json.load(open('result.json', encoding='utf-8'))
print('history_len =', len(state.get('history', [])))
print('has_summary =', isinstance(res.get('summary'), list) and len(res['summary']) == 3)
PY

• 성공판정:
  • history_len = 2
  • has_summary = True

---

초보자용 쉬운 설명

• 매번 처음부터 답하면, 문맥이 끊겨 품질이 흔들릴 수 있다.
• 그래서 이전 결과를 state.json에 누적해 다음 실행에 참고하게 만든다.
• 즉, “기억(상태)“를 파일로 분리해 두면, 작은 자동화도 운영 품질이 올라간다.

실무 적용 포인트

1. 반복 리포트 자동화: 일/주간 요약에서 직전 결과를 참고해 일관성 유지.
2. 업무 인수인계 안정화: 담당자 교체 시에도 파일 상태로 히스토리 유지.
3. 확장 쉬움: 다음 단계에서 상태에 score, owner, retry_count를 추가해 운영 지표화 가능.

체크리스트

• smolagents 설치 완료
• day19_stateful_agent.py 문법 검사 통과
• 1차 실행 후 state.json 생성
• 2차 실행 후 history 길이 2 확인
• result.json에 summary/history_count/applied_memory 존재

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 작성했고, 실습 절차(도구/입력/실행명령/성공판정)와 예시 코드는 사람이 검토해 확정했다.