🤗 17. 본편 09: smolagents 구조화 출력(JSON 계약)으로 자동화 연결

이번 편은 “사람이 읽기 좋은 답변”에서 한 단계 더 나아가, 자동화가 바로 먹을 수 있는 JSON 출력 계약을 만드는 실습이다.
핵심은 간단하다: 에이전트 성능보다 먼저 출력 스키마를 고정하면, n8n/스크립트 연동 실패가 크게 줄어든다.

• 이전 편: 🤗 16. 실습편 04
• 다음 확장: JSON Schema 검증 + 재시도 정책(ValidationError 시 1회 자동 재생성)

한 줄 결론

에이전트를 업무에 붙일 때는 “정답률”보다 먼저 “파싱 가능성(구조화 출력)“을 고정하라.

flowchart LR
  U[사용자 입력] --> A[CodeAgent]
  A --> T[DuckDuckGoSearchTool]
  T --> A
  A --> J[JSON 문자열 생성]
  J --> V[파이썬 json 검증]
  V --> O[자동화 파이프라인 전달]

---

실습 목표

• smolagents CodeAgent로 검색 기반 답변을 만든다.
• 결과를 반드시 JSON 계약으로 출력하게 만든다.
• 파싱 실패 시 즉시 실패 원인을 확인할 수 있게 만든다.

준비물

• 도구: Python 3.10+, 터미널
• 입력: API 키 1개(OpenAI 호환)
• 작업 폴더 예시: ~/hf-agents-lesson17

실무 팁: 팀 내 자동화 연동이 목적이면, 자연어 품질보다 먼저 “파싱 100%” 목표를 두는 게 유지보수에 유리하다.

---

1) 환경 준비

• 도구: 터미널
• 입력: 가상환경 + 패키지
• 실행명령:

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

• 성공판정:
  • (.venv) 표시
  • 설치 에러 없음

2) 환경변수 설정

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

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

• 성공판정:
  • echo $MODEL_ID 값 확인 가능
  • OPENAI_API_KEY 길이가 1보다 큼

3) JSON 계약 에이전트 작성

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

cat > lesson17_json_contract_agent.py <<'PY'
from __future__ import annotations
 
import json
import os
from typing import Any
 
from smolagents import CodeAgent, DuckDuckGoSearchTool, LiteLLMModel
 
 
SYSTEM_PROMPT = """
너는 실무 리서치 보조 에이전트다.
반드시 JSON 문자열만 출력하라(코드블록 금지, 설명문 금지).
스키마:
{
  "topic": "string",
  "key_points": ["string", "string", "string"],
  "sources": ["https://...", "https://..."]
}
규칙:
- key_points는 정확히 3개
- sources는 최소 2개
- 한국어로 작성
""".strip()
 
 
def build_agent() -> CodeAgent:
    model_id = os.getenv("MODEL_ID", "openai/gpt-4o-mini")
    model = LiteLLMModel(model_id=model_id)
    return CodeAgent(
        tools=[DuckDuckGoSearchTool()],
        model=model,
        system_prompt=SYSTEM_PROMPT,
        additional_authorized_imports=["json", "re"],
    )
 
 
def validate_payload(payload: dict[str, Any]) -> None:
    assert isinstance(payload.get("topic"), str) and payload["topic"].strip()
    assert isinstance(payload.get("key_points"), list) and len(payload["key_points"]) == 3
    assert all(isinstance(x, str) and x.strip() for x in payload["key_points"])
    assert isinstance(payload.get("sources"), list) and len(payload["sources"]) >= 2
    assert all(isinstance(x, str) and x.startswith("http") for x in payload["sources"])
 
 
def main() -> None:
    question = "중소 SaaS 팀이 AI 에이전트를 도입할 때 30일 내 체감 가능한 운영 이점 3가지를 정리해줘"
    agent = build_agent()
    raw = str(agent.run(question)).strip()
 
    try:
        data = json.loads(raw)
        validate_payload(data)
    except Exception as e:
        raise SystemExit(f"JSON 계약 검증 실패: {e}\n원문 출력:\n{raw}")
 
    print(json.dumps(data, ensure_ascii=False, indent=2))
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • lesson17_json_contract_agent.py 파일 생성
  • 코드에 json.loads + 검증 로직 포함

4) 실행 및 검증

• 도구: Python
• 입력: 질문 1개(코드 내부 기본값)
• 실행명령:

python lesson17_json_contract_agent.py

• 성공판정:
  • JSON 형태로 출력됨
  • key_points 정확히 3개
  • sources 2개 이상
  • 오류 없이 종료 코드 0

5) 실패 복구(초보자 체크)

• 도구: 터미널
• 입력: 진단 명령
• 실행명령:

pip show smolagents litellm duckduckgo-search
 
python - <<'PY'
import os
print("OPENAI_API_KEY set:", bool(os.getenv("OPENAI_API_KEY")))
print("MODEL_ID:", os.getenv("MODEL_ID", "openai/gpt-4o-mini"))
PY

• 성공판정:
  • 누락 패키지/환경변수 즉시 파악 가능

---

실무 적용 포인트

1. 출력 계약을 코드로 검증
   • “대충 맞는 답” 대신 “자동화가 소비 가능한 답”을 보장
2. 실패를 조용히 넘기지 않기
   • 검증 실패 시 즉시 종료하면 데이터 오염 방지 가능
3. 최소 스키마부터 시작
   • topic/key_points/sources 3필드만으로도 대부분의 리서치 자동화 시작 가능
4. 향후 확장 경로가 명확
   • 다음 단계: Pydantic 모델 검증, 재시도 정책, 로그 적재

---

자주 막히는 문제

1. 모델이 JSON 외 텍스트를 섞어 출력
   • 해결: 시스템 프롬프트에 “코드블록 금지/설명문 금지”를 명시
2. sources가 1개만 나오는 문제
   • 해결: 스키마 규칙 + 검증 assert로 강제
3. 검색 품질이 들쑥날쑥함
   • 해결: 질문에 기간/도메인/관점(예: 운영비용, SLA)을 명시

체크리스트

• 가상환경/패키지 설치 완료
• API 키/모델 설정 완료
• JSON 출력 파싱 성공
• key_points=3, sources>=2 검증 성공
• 실패 시 오류문으로 원인 확인 가능

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 구성, 실습 코드 정리, 체크리스트 구조화를 수행했으며, 최종 발행 전 사람이 링크/명령/출력 계약을 검토했다.