🤗 21. 본편 12: smolagents CodeAgent 추가 import 허용으로 실무 자동화 넓히기

이번 편에서는 smolagents의 CodeAgent를 쓸 때 자주 만나는 질문, **“기본 import 제한을 어떻게 안전하게 풀어서 실무 작업에 연결할까?”**를 다룬다.

핵심은 간단하다.

• 기본값은 안전을 위해 import가 제한된다.

• 필요한 라이브러리만 명시적으로 허용하면 자동화 범위를 넓힐 수 있다.

• 허용 목록을 넓힐수록 리스크도 커지므로, 최소 권한 원칙으로 운영해야 한다.

• 이전 편: 🤗 20. 본편 11

• 다음 편 예고: 툴 실패 시 재시도·대체경로(fallback) 정책을 코드 레벨에서 표준화하기

한 줄 목표

동일한 작업을 “import 허용 전/후”로 실행해 실패→성공 전환을 재현하고, 운영용 허용 정책 템플릿을 만든다.

flowchart TD
  A[사용자 작업 요청] --> B[CodeAgent 실행]
  B --> C{필요 모듈 import 가능?}
  C -- 아니오 --> D[ImportError/실패 로그]
  D --> E[허용 목록에 최소 모듈 추가]
  E --> B
  C -- 예 --> F[정상 실행]
  F --> G[결과 저장 + 운영 정책 반영]

---

0) 실습 범위

• 범위 포함
  • additional_authorized_imports 미설정/설정 비교
  • 같은 입력으로 실패와 성공을 각각 1회 이상 재현
  • 실행 로그(run_import_policy.json)로 결과 증빙
• 범위 제외
  • 외부 API 대규모 호출
  • 멀티에이전트 구조

1) 환경 준비

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

mkdir -p ~/hf-agents-lab21
cd ~/hf-agents-lab21
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"

• 성공판정:

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

• OPENAI_API_KEY set: True 확인

3) 비교 실험 코드 작성

아래 코드는 같은 작업을 2번 실행한다.

1. import 허용 없음 ([]) → 실패 기대
2. datetime 허용 (["datetime"]) → 성공 기대

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

cat > lab21_import_policy_compare.py <<'PY'
from __future__ import annotations
 
import json
import os
import time
from pathlib import Path
 
from smolagents import CodeAgent, LiteLLMModel
 
OUT = Path("run_import_policy.json")
TASK = (
    "파이썬 코드로 datetime 모듈을 import해 현재 연-월-일 문자열을 만들고, "
    "'운영 리포트 날짜: YYYY-MM-DD' 형식 한 줄만 출력해라."
)
 
 
def run_once(allowed_imports: list[str]) -> dict:
    model = LiteLLMModel(model_id=os.getenv("MODEL_ID", "openai/gpt-4o-mini"))
    agent = CodeAgent(
        model=model,
        tools=[],
        max_steps=6,
        additional_authorized_imports=allowed_imports,
    )
 
    t0 = time.perf_counter()
    ok = True
    output_text = ""
    error = ""
 
    try:
        result = agent.run(TASK)
        output_text = str(result)
    except Exception as e:
        ok = False
        error = f"{type(e).__name__}: {e}"
 
    return {
        "allowed_imports": allowed_imports,
        "success": ok,
        "elapsed_sec": round(time.perf_counter() - t0, 3),
        "output_preview": output_text[:200],
        "error": error,
    }
 
 
def main() -> None:
    rows = [
        run_once([]),
        run_once(["datetime"]),
    ]
    OUT.write_text(json.dumps(rows, ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"saved: {OUT}")
    for r in rows:
        print(r)
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • lab21_import_policy_compare.py 파일 생성
  • 코드에 additional_authorized_imports 키워드 확인

4) 실행

• 도구: Python
• 입력: 동일 태스크 + import 허용 목록 2종
• 실행명령:

python lab21_import_policy_compare.py
cat run_import_policy.json

• 성공판정:
  • saved: run_import_policy.json 출력
  • JSON에 allowed_imports, success, error 키 존재
  • 보통 [] 실행은 실패, ["datetime"] 실행은 성공 패턴이 관찰됨

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

• 도구: 터미널
• 입력: run_import_policy.json
• 실행명령:

python - <<'PY'
import json
rows = json.load(open('run_import_policy.json', encoding='utf-8'))
for r in rows:
    print(f"imports={r['allowed_imports']} success={r['success']} sec={r['elapsed_sec']}")
    if not r['success']:
        print('  error=', r['error'][:140])
 
safe_policy = [r for r in rows if r['success']]
if safe_policy:
    print('RECOMMEND: 성공에 필요한 최소 import만 허용 목록에 유지')
else:
    print('RECOMMEND: 모델/API키/버전 및 태스크 문구 재점검')
PY

• 성공판정:
  • RECOMMEND: 문장 1줄 이상 출력

---

실무 적용 포인트

1. 최소 권한 원칙

   • 처음부터 pandas, requests, os를 전부 열지 말고,
   • 실패 로그를 보고 필요한 모듈만 순차 허용한다.

2. 작업별 허용 템플릿 분리

   • 리포트 작성 작업: datetime, json 중심
   • 데이터 가공 작업: math, statistics 등
   • 템플릿을 분리하면 장애 분석이 빨라진다.

3. 운영 로그를 반드시 파일로 남기기

   • 이번 실습처럼 JSON 로그를 남기면
   • “언제 어떤 허용 정책이 실패/성공했는지”를 회고할 수 있다.

트러블슈팅

1. 둘 다 실패하는 경우

• 원인: API 키/모델 설정 오류 가능성
• 조치:

python - <<'PY'
import os
print(bool(os.getenv('OPENAI_API_KEY')), os.getenv('MODEL_ID'))
PY

2. 허용했는데도 import 오류가 나는 경우

• 원인: 모듈명 오타 또는 환경 미설치
• 조치: 모듈명 정확히 확인, 필요한 패키지 설치 후 재시도

3. 결과 형식이 흔들리는 경우

• 원인: 태스크 지시가 느슨함
• 조치: 출력 포맷 문구를 더 엄격히 지정
  • 예: 정확히 한 줄, 접두어는 '운영 리포트 날짜:'

체크리스트

• import 허용 전/후 실행 결과를 모두 확보했다
• run_import_policy.json 파일을 저장했다
• 업무별 최소 허용 목록 초안을 만들었다
• 팀 운영 문서에 허용 정책과 근거 로그를 기록했다

참고 링크 (우선순위)

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

생성형 AI 활용 고지

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