🤗 12. 본편 06: CodeAgent 샌드박스 실행과 실패 복구

이번 편은 **“코드 실행형 에이전트를 운영할 때 왜 샌드박스가 중요한가”**를 초보자 관점에서 다룬다.
핵심은 단순하다.

에이전트 성능보다 먼저, 실행 안전성과 실패 복구 루틴을 고정해야 실무에서 오래 쓴다.

• 이전 편: 🤗 11. 본편 05

한 줄 결론

CodeAgent를 “로컬 직실행”으로 바로 쓰기보다, 샌드박스(격리 실행) + 실패 판정표 + 재시도 규칙을 같이 설계하면 운영 안정성이 크게 올라간다.

flowchart TD
  A[사용자 요청] --> B[CodeAgent 계획]
  B --> C{도구/코드 실행 필요?}
  C -->|예| D[샌드박스 실행]
  D --> E{성공 판정}
  E -->|성공| F[근거 포함 최종 응답]
  E -->|실패| G[오류 분류]
  G --> H[재시도 or 대체 경로]
  H --> D
  C -->|아니오| F

---

실습 목표

1. smolagents CodeAgent를 실행한다.
2. 의도적으로 실패 케이스를 만들어 복구 흐름을 검증한다.
3. 실무형 성공판정(정확성/재현성/안전성)을 체크한다.

준비물

• Python 3.10+
• Hugging Face 토큰(권장): HF_TOKEN
• 작업 경로: /home/tw2/Documents/n8n/data/shared/syn/8.quartz/Agent/🤗 HF-Agents-Course/downloads

---

1) 환경 준비

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

cd "/home/tw2/Documents/n8n/data/shared/syn/8.quartz/Agent/🤗 HF-Agents-Course/downloads"
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install "smolagents[toolkit]"

• 성공판정:

python -c "import smolagents; print('smolagents ok')"

smolagents ok가 출력되면 통과.

2) 실습 코드 작성 (정상 경로 + 실패 경로)

• 도구: 파일 편집기
• 입력: 아래 코드
• 실행명령:

cat > day12_sandbox_recovery.py <<'PY'
from smolagents import CodeAgent, InferenceClientModel, tool
 
@tool
def divide(a: float, b: float) -> str:
    """두 수를 나눠 문자열로 반환한다."""
    if b == 0:
        return "error: division_by_zero"
    return f"result={a / b:.4f}"
 
@tool
def kpi_grade(score: float) -> str:
    """점수를 등급으로 변환한다."""
    if score >= 90:
        return "A"
    if score >= 80:
        return "B"
    if score >= 70:
        return "C"
    return "D"
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[divide, kpi_grade],
    model=model,
    max_steps=6,
)
 
if __name__ == "__main__":
    task_ok = "120을 8로 나누고, 결과를 소수점 4자리로 보여준 뒤 KPI 점수 88의 등급을 같이 알려줘."
    task_fail = "120을 0으로 나누고, 실패 원인을 1줄로 설명해줘."
 
    print("\n=== CASE 1: 정상 ===")
    print(agent.run(task_ok))
 
    print("\n=== CASE 2: 실패 복구 ===")
    print(agent.run(task_fail))
PY

• 성공판정:
  • day12_sandbox_recovery.py 파일이 생성된다.

3) 실행

• 도구: Python 실행
• 입력: 위 스크립트
• 실행명령:

export HF_TOKEN="<your_hf_token>"
python day12_sandbox_recovery.py

• 성공판정:
  • CASE 1에서 result=15.0000와 등급 B가 함께 나온다.
  • CASE 2에서 division_by_zero 원인이 명시된다.
  • (권장) 최소 1회 이상 tool 호출 흔적(step 로그) 확인.

4) 실무형 체크리스트 (바로 적용)

A. 정확성

• 수치 계산 결과가 기대값과 일치하는가?

B. 재현성

• 동일 명령을 다시 실행했을 때 같은 결과가 나오는가?

C. 안전성

• 실패 시 원인 문자열(division_by_zero)을 구조적으로 반환하는가?

D. 운영성

• max_steps로 무한 루프를 방지했는가?

---

초보자용 쉬운 설명

• @tool은 **“에이전트가 호출할 수 있는 함수 등록”**이다.
• CodeAgent는 답을 바로 찍는 대신, 필요하면 코드를 써서 도구를 실행한다.
• 샌드박스 실행은 실수 코드가 시스템 전체에 영향 주지 않도록 격리하는 운영 습관이다.

실무 적용 포인트

1. 오류 문자열 표준화
   • error: division_by_zero처럼 고정 포맷을 쓰면 모니터링/알림 연동이 쉬워진다.
2. 성공판정 자동화
   • CI에서 result=15.0000 같은 기대값 체크를 자동으로 돌린다.
3. 단계 제한 기본값 고정
   • 초반 운영은 max_steps=4~8 범위로 시작하면 안정적이다.

트러블슈팅

1. 401 Unauthorized
   • 원인: HF_TOKEN 미설정 또는 권한 문제
   • 해결: 토큰 재발급 후 export HF_TOKEN=...
2. ModuleNotFoundError: smolagents
   • 원인: 가상환경 비활성화
   • 해결: source .venv/bin/activate 후 재설치
3. 결과가 들쭉날쭉함
   • 원인: 프롬프트 조건이 느슨함
   • 해결: 출력 형식을 문장으로 강제(예: “반드시 result=… 형식으로 답변”)

다음 편 예고

다음 본편에서는 **ToolCallingAgent와 정책 기반 허용 목록(Allowlist)**을 결합해, “업무별 도구 권한 분리” 패턴을 다룬다.

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 작성했으며, 실습 절차/명령어/성공 판정 기준/링크 무결성은 사람이 검토해 확정했다.