🤗 28. 실습편 08: smolagents 로그 요약·알림 미니프로젝트 핸즈온 1

이번 편은 **“운영 로그 텍스트를 입력하면, 에이전트가 장애 요약 + 심각도 + 즉시 조치안을 JSON으로 반환하는 핸즈온”**이다.
HF Agents Course의 Hands-on 흐름(작게 만들고, 검증 가능하게 반복)과 smolagents 실무 패턴(CodeAgent + 구조화 출력)을 그대로 재현한다.

• 이전 편: 🤗 27. 본편 16
• 다음 편 예고: 실습편 08-2 (다중 서비스 로그 배치 처리 + 리포트 자동 저장)

flowchart TD
  A[raw_log.txt 입력] --> B[CodeAgent 실행]
  B --> C[로그 핵심 이벤트 추출]
  C --> D[심각도 분류 sev0~sev3]
  D --> E[조치안 + 근거 JSON 생성]
  E --> F[incident_summary.json 저장]
  F --> G{품질 게이트 통과?}
  G -- Yes --> H[완료]
  G -- No --> I[프롬프트/입력 수정 후 재실행]
  I --> B

0) 실습 목표

단일 로그 파일(raw_log.txt)을 넣어 incident_summary.json을 생성하고, 검증 스크립트까지 PASS한다.

---

1) 환경 준비

• 도구: 터미널
• 입력: Python 3.10+
• 실행명령:

mkdir -p ~/hf-agents-lab28
cd ~/hf-agents-lab28
python3 -m venv .venv
source .venv/bin/activate
pip install -U "smolagents[toolkit]" litellm

• 성공판정:

python -V
pip show smolagents | head -n 5
pip show litellm | head -n 5

• Python 버전 출력
• smolagents, litellm 패키지 정보 확인

2) 모델/API 설정

• 도구: 터미널
• 입력: 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) 실습 입력 로그 만들기

• 도구: 터미널
• 입력: 샘플 로그
• 실행명령:

cat > raw_log.txt <<'LOG'
2026-04-18T08:55:11Z INFO api-gateway request_id=aa12 path=/checkout latency_ms=92 status=200
2026-04-18T08:55:12Z WARN payment-service request_id=aa12 retry=1 reason=upstream_timeout
2026-04-18T08:55:14Z ERROR payment-service request_id=aa12 error=DBConnectionRefused host=db-prod-1
2026-04-18T08:55:16Z ERROR payment-service request_id=aa13 error=DBConnectionRefused host=db-prod-1
2026-04-18T08:55:20Z WARN api-gateway request_id=aa14 path=/checkout latency_ms=3200 status=504
2026-04-18T08:55:25Z INFO alertmanager fired=true service=payment-service rule=high_error_rate
LOG

• 성공판정:

wc -l raw_log.txt

• 6 raw_log.txt 출력

4) 미니 프로젝트 코드 작성

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

cat > lab28_incident_agent.py <<'PY'
from __future__ import annotations
 
import json
import os
from pathlib import Path
 
from smolagents import CodeAgent, LiteLLMModel
 
INPUT_PATH = Path("raw_log.txt")
OUTPUT_PATH = Path("incident_summary.json")
 
 
def strip_code_fence(text: str) -> str:
    t = text.strip()
    if t.startswith("```"):
        lines = t.splitlines()
        if lines and lines[0].startswith("```"):
            lines = lines[1:]
        if lines and lines[-1].startswith("```"):
            lines = lines[:-1]
        t = "\n".join(lines).strip()
    return t
 
 
def main() -> None:
    raw_log = INPUT_PATH.read_text(encoding="utf-8")
 
    model = LiteLLMModel(model_id=os.getenv("MODEL_ID", "openai/gpt-4o-mini"))
    agent = CodeAgent(
        model=model,
        tools=[],
        max_steps=6,
        additional_authorized_imports=["json", "re"],
    )
 
    prompt = f"""
너는 SRE 보조 에이전트다.
아래 운영 로그를 분석해 JSON만 반환하라.
 
[로그]
{raw_log}
 
출력 스키마(키 이름 고정):
{{
  "service": "string",
  "severity": "sev0|sev1|sev2|sev3",
  "summary": ["문장", "문장", "문장"],
  "probable_root_cause": "string",
  "immediate_actions": ["문장", "문장", "문장"],
  "evidence": [
    {{"line": "원문 일부", "reason": "판단 근거"}}
  ]
}}
 
규칙:
- summary는 정확히 3개
- immediate_actions는 정확히 3개
- evidence는 최소 2개
- JSON 외 텍스트 금지
"""
 
    result = agent.run(prompt)
    obj = json.loads(strip_code_fence(str(result)))
 
    OUTPUT_PATH.write_text(json.dumps(obj, ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"saved: {OUTPUT_PATH}")
    print(json.dumps({
        "service": obj.get("service"),
        "severity": obj.get("severity"),
        "evidence_count": len(obj.get("evidence", [])),
    }, ensure_ascii=False))
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • lab28_incident_agent.py 생성
  • 코드에 CodeAgent, JSON 스키마, strip_code_fence() 존재

5) 실행 및 결과 저장

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

python lab28_incident_agent.py
cat incident_summary.json

• 성공판정:
  • saved: incident_summary.json 출력
  • JSON에 severity, summary(3개), immediate_actions(3개) 확인

6) 품질 게이트(재현성 검증)

• 도구: Python
• 입력: incident_summary.json
• 실행명령:

python - <<'PY'
import json
 
obj = json.load(open('incident_summary.json', encoding='utf-8'))
 
assert obj.get('severity') in {'sev0','sev1','sev2','sev3'}, 'invalid severity'
assert isinstance(obj.get('summary'), list) and len(obj['summary']) == 3, 'summary must be 3'
assert isinstance(obj.get('immediate_actions'), list) and len(obj['immediate_actions']) == 3, 'immediate_actions must be 3'
assert isinstance(obj.get('evidence'), list) and len(obj['evidence']) >= 2, 'evidence must be >=2'
for ev in obj['evidence']:
    assert 'line' in ev and 'reason' in ev, 'evidence item must include line/reason'
 
print('PASS: 품질 게이트 통과')
PY

• 성공판정:
  • PASS: 품질 게이트 통과

---

트러블슈팅 (실전 5선)

1. AuthenticationError / 모델 호출 실패

• 원인: API 키 미설정, 모델 ID 오타
• 점검:

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

• 조치: 환경변수 재설정 후 재실행

2. ModuleNotFoundError: smolagents

• 원인: 가상환경 미활성화 또는 설치 누락
• 조치:

source .venv/bin/activate
pip install -U "smolagents[toolkit]" litellm

3. json.loads 파싱 실패

• 원인: 모델이 JSON 외 설명 문장을 섞어 출력
• 조치:
  • 프롬프트에 JSON 외 텍스트 금지 유지
  • strip_code_fence() 유지
  • 필요 시 max_steps를 줄여 산만한 응답 방지

4. 품질 게이트에서 summary/immediate_actions 개수 불일치

• 원인: 스키마 강제 규칙이 약함
• 조치:
  • 프롬프트 규칙에 정확히 3개를 명시
  • 실패 시 동일 입력으로 재실행하여 일관성 확인

5. severity 과대/과소 분류

• 원인: 로그 수가 적어 맥락 부족
• 조치:
  • 로그 20~50줄로 확장해 재실행
  • 경고/오류/장애 알림 라인을 반드시 포함

체크리스트

• raw_log.txt 준비
• lab28_incident_agent.py 실행 성공
• incident_summary.json 저장
• 품질 게이트 PASS
• 트러블슈팅 항목 최소 3개 재현/점검

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI로 초안을 작성하고, 사람이 실습 재현성(도구/입력/실행명령/성공판정), 트러블슈팅, 링크, 내부 링크를 검토·수정해 최종 확정했다.