🤗 20. 본편 11: smolagents 계획 주기(planning_interval) 실무 적용

이번 편에서는 smolagents의 계획 주기(planning interval) 개념을 실무 관점에서 다룬다.
핵심은 간단하다.

• 계획을 너무 자주 다시 세우면 느리고 비용이 늘어난다.
• 계획을 너무 늦게 갱신하면 실패를 오래 끌고 간다.

즉, “몇 스텝마다 계획을 재수립할지”를 업무 성격에 맞게 조절해야 한다.

• 이전 편: 🤗 19. 실습편 05
• 다음 편 예고: 실패 로그를 근거로 자동 재시도 정책(재계획 + 도구 폴백) 설계

한 줄 목표

동일한 작업을 planning_interval 값만 바꿔 2회 실행하고, 실행 시간·스텝 수·성공률 변화를 비교해 운영 기본값을 정한다.

flowchart TD
  A[사용자 작업 요청] --> B[CodeAgent 실행]
  B --> C{planning_interval 도달?}
  C -- 아니오 --> D[현재 계획 유지 + 다음 도구 실행]
  C -- 예 --> E[계획 재수립]
  E --> D
  D --> F{완료/실패}
  F -- 완료 --> G[최종 결과 + 지표 기록]
  F -- 실패 --> H[실패 원인 기록 후 재실행 정책 검토]

---

0) 실습 범위

• 범위 포함
  • planning_interval=1 과 planning_interval=3 비교 실행
  • 같은 입력/같은 도구/같은 모델로 공정 비교
  • 성공 여부 + 처리 시간 + 로그 건수 저장
• 범위 제외
  • 외부 DB/벡터스토어
  • 복잡한 멀티에이전트 오케스트레이션

---

1) 환경 준비

• 도구: 터미널
• 입력: Python 3.10+, 가상환경
• 실행명령:

mkdir -p ~/hf-agents-lab20
cd ~/hf-agents-lab20
python3 -m venv .venv
source .venv/bin/activate
pip install -U smolagents litellm

• 성공판정:

python -V
pip show smolagents | head -n 5

• Python 버전 출력
• smolagents 패키지 정보가 보이면 성공

2) 모델 설정

• 도구: 터미널
• 입력: API 키, 모델 ID
• 실행명령:

export OPENAI_API_KEY="YOUR_API_KEY"
export MODEL_ID="openai/gpt-4o-mini"

• 성공판정:

echo "$MODEL_ID"
python - <<'PY'
import os
print("OPENAI_API_KEY set:", bool(os.getenv("OPENAI_API_KEY")))
PY

• OPENAI_API_KEY set: True 확인

3) 실험 코드 작성 (planning_interval 비교)

• 도구: 에디터/터미널
• 입력: 아래 코드
• 실행명령:

cat > lab20_planning_interval_compare.py <<'PY'
from __future__ import annotations
 
import json
import os
import time
from pathlib import Path
 
from smolagents import CodeAgent, LiteLLMModel, tool
 
OUT = Path("run_metrics.json")
 
@tool
def search_kb(topic: str) -> str:
    """topic 관련 운영 팁 3개를 문자열로 반환한다."""
    kb = {
        "incident": [
            "1) 상황 요약을 먼저 고정한다",
            "2) 담당자/기한/다음 액션을 분리한다",
            "3) 고객 영향도를 숫자로 명시한다",
        ],
        "release": [
            "1) 변경점은 사용자 영향 기준으로 정리",
            "2) 롤백 조건을 배포 전 확정",
            "3) 배포 직후 30분 관찰 지표 지정",
        ],
    }
    key = topic.lower().strip()
    items = kb.get(key, ["관련 팁 없음"])
    return "\n".join(items)
 
 
def run_once(interval: int) -> dict:
    model = LiteLLMModel(model_id=os.getenv("MODEL_ID", "openai/gpt-4o-mini"))
    agent = CodeAgent(
        model=model,
        tools=[search_kb],
        max_steps=8,
        planning_interval=interval,
    )
 
    task = (
        "incident 주제에 대해 search_kb 도구를 활용해 "
        "팀 공지용 3줄 요약을 만들고, 마지막 줄에 체크리스트 2개를 붙여라."
    )
 
    t0 = time.perf_counter()
    ok = True
    error = ""
    output_text = ""
 
    try:
        result = agent.run(task)
        output_text = str(result)
    except Exception as e:
        ok = False
        error = f"{type(e).__name__}: {e}"
 
    elapsed = round(time.perf_counter() - t0, 3)
 
    return {
        "planning_interval": interval,
        "success": ok,
        "elapsed_sec": elapsed,
        "output_preview": output_text[:300],
        "error": error,
    }
 
 
def main() -> None:
    runs = [run_once(1), run_once(3)]
    OUT.write_text(json.dumps(runs, ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"saved: {OUT}")
    for r in runs:
        print(r)
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • lab20_planning_interval_compare.py 파일 생성
  • 코드 내 planning_interval=interval 확인

4) 실행 및 지표 저장

• 도구: Python
• 입력: 동일 작업(task), interval 2종(1/3)
• 실행명령:

python lab20_planning_interval_compare.py
cat run_metrics.json

• 성공판정:
  • saved: run_metrics.json 출력
  • JSON에 planning_interval, success, elapsed_sec 키 존재

5) 결과 판독 기준(초보자용)

• 도구: 눈으로 확인 + 간단 규칙
• 입력: run_metrics.json
• 실행명령:

python - <<'PY'
import json
rows = json.load(open('run_metrics.json', encoding='utf-8'))
for r in rows:
    print(f"interval={r['planning_interval']} success={r['success']} sec={r['elapsed_sec']}")
 
# 단순 권장 규칙
ok_rows = [r for r in rows if r['success']]
if len(ok_rows) == 2:
    faster = min(ok_rows, key=lambda x: x['elapsed_sec'])
    print(f"RECOMMEND: planning_interval={faster['planning_interval']} (성공 + 더 빠름)")
elif len(ok_rows) == 1:
    print(f"RECOMMEND: planning_interval={ok_rows[0]['planning_interval']} (유일 성공)")
else:
    print("RECOMMEND: max_steps/도구정의/프롬프트 재점검 필요")
PY

• 성공판정:
  • RECOMMEND: ... 한 줄이 출력되면 판독 루프 정상

---

왜 실무에서 중요한가?

1. 비용/지연 관리: 계획 재수립은 모델 호출 비용과 직결된다.
2. 안정성 확보: 도구 오류가 나는 환경에서는 너무 긴 간격이 실패 복구를 늦춘다.
3. 운영 표준화: 팀별 기본값(예: 2 또는 3)을 정하면 디버깅이 쉬워진다.

실무 적용 포인트

• 고객 응답형(짧고 빠른 답변): planning_interval을 크게(예: 3~4) 시작
• 정확도 우선형(복잡한 도구 체인): planning_interval을 작게(예: 1~2) 시작
• 반드시 **작업별 벤치마크 파일(run_metrics.json)**을 남겨 회귀를 비교

트러블슈팅

1. 실행이 지나치게 느림

• 원인: planning 재수립이 너무 잦음
• 조치: planning_interval 1→3으로 올려 재측정

2. 정답 품질이 흔들림

• 원인: 재계획 주기가 너무 길어 중간 오류를 방치
• 조치: planning_interval 4→2로 낮추고 max_steps를 함께 조정

3. 모델 인증 오류(401/429)

• 원인: API 키/쿼터 문제
• 조치:

echo ${OPENAI_API_KEY:+SET}
# 필요 시 키 재발급 후 재설정

---

체크리스트

• 동일한 입력으로 interval 2종 비교 완료
• run_metrics.json 저장 확인
• 성공률/시간 기준으로 기본값 결정
• 팀 공용 문서에 기본값과 근거 기록

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI로 초안을 작성하고, 사람 검토를 통해 실습 재현성(도구/입력/명령/성공판정), 링크, 문서 형식을 확인해 확정했다.