🤗 35. HF Agents Course 본편 21 - smolagents 메모리로 장기 작업 컨텍스트 유지하기

이번 편에서는 smolagents 에이전트가 이전 실행 맥락을 기억해 다음 작업 정확도를 높이는 방법을 다룹니다.

핵심 참고:

• https://github.com/huggingface/agents-course
• https://huggingface.co/learn/agents-course
• https://huggingface.co/docs/smolagents

1) 왜 메모리가 필요한가

초보자가 가장 자주 겪는 문제는 다음입니다.

• 같은 지시를 매번 다시 설명해야 함
• 이전 출력 형식(JSON/표)을 다음 실행에서 잊어버림
• 장기 업무(주간 보고, 티켓 추적)에서 맥락 손실

메모리를 설계하면, 에이전트가 “이전 결론/규칙/출력 계약”을 재사용합니다.

2) 실습 목표

• 목표: 고객문의 요약 에이전트가 priority_rule과 output_schema를 기억해 재실행 시 일관된 결과 생성
• 성공 판정:
  1. 1차 실행에서 규칙 저장
  2. 2차 실행에서 규칙 재설명 없이 동일 스키마 출력
  3. 로그에 메모리 로드/적용 흔적 확인

3) 준비물

• 도구: Python 3.10+, venv, pip
• 입력 파일:
  • tickets_day1.txt
  • tickets_day2.txt
• 실행 명령:

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

4) 재현 단계

Step A. 입력 준비

tickets_day1.txt

결제 실패 문의 3건, 로그인 오류 1건, 기능 요청 1건

tickets_day2.txt

결제 실패 문의 1건, 환불 요청 2건, 로그인 오류 2건

Step B. 에이전트 스크립트 작성

memory_agent.py

from smolagents import CodeAgent
from pathlib import Path
import json
 
MEMORY_FILE = Path("agent_memory.json")
 
def load_memory():
    if MEMORY_FILE.exists():
        return json.loads(MEMORY_FILE.read_text(encoding="utf-8"))
    return {
        "priority_rule": "결제/환불 > 로그인 > 기능요청",
        "output_schema": ["date", "top_issue", "action"]
    }
 
def save_memory(mem):
    MEMORY_FILE.write_text(json.dumps(mem, ensure_ascii=False, indent=2), encoding="utf-8")
 
memory = load_memory()
agent = CodeAgent(tools=[])
 
def run(ticket_text, date):
    prompt = f"""
규칙:
- 우선순위: {memory['priority_rule']}
- 출력키: {memory['output_schema']}
 
입력: {ticket_text}
요청: 위 규칙에 따라 JSON 1개만 출력
date는 {date}로 채워라.
"""
    result = agent.run(prompt)
    return result
 
print(run(Path("tickets_day1.txt").read_text(encoding="utf-8"), "2026-05-26"))
save_memory(memory)

Step C. 실행

python memory_agent.py

Step D. 2차 실행(입력만 교체)

memory_agent.py 마지막 줄 입력 파일만 tickets_day2.txt로 바꿔 재실행:

python memory_agent.py

5) 성공 판정 체크리스트

• 두 실행 모두 JSON 단일 객체 출력
• 키가 date/top_issue/action 순서로 유지
• day2 실행에서도 우선순위 규칙(결제/환불 우선)이 반영
• agent_memory.json 파일 존재

6) 동작 구조

flowchart TD
    A[티켓 입력 파일] --> B[메모리 로드 agent_memory.json]
    B --> C[CodeAgent 프롬프트 구성]
    C --> D[모델 추론]
    D --> E[JSON 출력]
    E --> F[메모리 유지/업데이트]

7) 실무 적용 포인트

1. 출력 계약 고정: 자동화 연동(n8n, ETL)에서는 키 이름/순서를 메모리로 고정.
2. 우선순위 규칙 분리: 정책 변경 시 코드 수정 대신 메모리 값만 갱신.
3. 회귀 테스트: 샘플 입력 3~5개로 재실행해 포맷 일관성 점검.

8) 자주 나는 실수

• 메모리 파일을 프롬프트에 반영하지 않음 → 단순 저장만 하고 미사용
• 성공 판정 없이 “대충 좋아 보임”으로 종료 → 운영 시 품질 흔들림
• 입력 포맷이 바뀌었는데 스키마 고정만 유지 → 파서 오류

---

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 만들고, 실습 재현성(명령/입력/성공판정)과 링크를 사람이 검수해 보완했습니다.