JSON 대신 파이썬을 쓰는 이유 — smolagents의 20줄과 없는 체크포인트

JSON 대신 파이썬을 쓰는 이유 — smolagents의 20줄과 없는 체크포인트

Hugging Face가 2024년 연말에 낸 라이브러리의 이름부터 태도다. smolagents.

공식 문서의 첫 문장: "몇 줄의 Python으로 에이전트를 빌드하고 실행할 수 있도록." 기본값은 CodeAgent. 모델이 JSON 툴 호출을 내뱉는 대신 Python을 쓰고 실행한다.

실측 리뷰의 한 줄: "1.26.0에서 pip 패키지는 12개 파일에 13,355줄이다. '1,000줄'이라는 초기 주장과 13배 차이." 이름은 작지만, 코어는 "몇 시간에 걸쳐 읽고 이해할 수 있는" 크기로 남아 있다.

이 글은 코드-액션이라는 하나의 베팅과, 그 베팅이 지불하는 비용을 정리한다.

1. 무엇이 강한 베팅인가

코드의 합성성. 한 단계에서 두 툴을 호출하고 결과를 결합하고, 리스트를 순회하고, 조건을 나눈다. JSON은 중첩과 재사용이 어렵다. Python은 프로그래밍 언어다.

GAIA. 멀티 에이전트 시스템이 GAIA 벤치마크 44.2%로 1위, Microsoft AutoGen(40%)을 4포인트 앞선 기록. 마케팅이 아니라 점수다.

토큰. 변수 재사용·중간 계산이 필요한 작업에서 CodeAgent가 툴 호출 횟수를 줄여 토큰을 덜 쓴다는 경향. (제어된 비교 측정은 아직 부족하다는 리뷰의 단서.)

읽을 수 있는 코어. 실행 경로가 짧고 보인다. 무거운 프레임워크에서 "원인 후보 3~4개가 설정 레이어에 파묻힌" 것과 대비된다.

HF Hub. 에이전트와 툴이 Hub의 일급 개체다. 커뮤니티 에이전트를 모델처럼 공유·로드. GradioUI(agent).launch() 한 줄로 웹 인터페이스.

2. 무엇이 프로덕션 전가인가

체크포인트 없음. 메모리는 프로세스 안의 Python 리스트다. PostgreSQL·Redis·체크포인터 없음. "프로세스가 중간에 죽으면 실행이 사라진다." LangGraph와의 핵심 차이.

API는 실험 라벨. "실험적이며 언제든 바뀔 수 있다." 27K 스타 프레임워크에서 이례적인 선언. 버전 업그레이드는 파괴를 감수하라.

코드 실행의 보안. 문서가 명시한다: 로컬 실행기는 보안 경계가 아니다. 신뢰할 수 없는 데이터를 만진다면 E2B·Modal·Docker·WASM으로 옮겨야 하고, 그때부터 인프라 오버헤드가 시작된다. 프롬프트 인젝션은 코드 에이전트에서 폭발력이 커진다.

모델 품질 의존. 약한 모델은 잘못된 Python을 쓴다. 디버깅할 때 가장 강한 모델부터 쓰라는 문서의 조언이 곧 사용 규칙이다.

MCP 서버 없음. MCP 클라이언트는 되지만, 자신의 에이전트를 MCP 엔드포인트로 노출하지 않는다. Hub 통합은 이식성의 한 형태이지, MCP 생태계의 일원이 아니다.

관측 없음. LangSmith 대응 없음. OpenTelemetry는 옵트인 extras. 프로덕션 트레이스는 외부 도구.

3. 누가 쓰나

실무자의 한 문장: "스킬 있는 손에 있는 극소 프레임워크가, 아무도 이해 못 하는 위원회 구성의 무거운 프레임워크를 이긴다."

4. 결론 — 작게 시작하는 법

smolagents의 사용자 기록은 한 문장으로 압축된다. JSON의 의례를 버리고 Python의 표현력을 얻은, 실험 라벨 붙은 최소 코어.

강점은 연구·프로토타입·통제 환경의 데이터 에이전트에서 실측된다. 약점은 "체크포인트·관측·MCP 서버·API 안정성"이라는 프로덕션 체크리스트에서 드러난다. 그 항목들은 프레임워크의 실패가 아니라 최소주의의 정직한 거래다.

smolagents를 쓸 계획이라면: ① 강한 모델, ② 신뢰 데이터만, ③ 실패 시 재시작이 가능한 작업, ④ 그 밖이면 LangGraph로. 그 경계 안에서, 지금까지 읽을 수 있는 가장 투명한 에이전트 코어 중 하나다.

관련 글: CrewAI 사용자 리뷰 · Pydantic AI 사용자 리뷰 · smolagents 에이전트 허브 항목

출처

• 설계 리뷰: Hugging Face's smolagents Framework (AgentsDecoded, 2025-01)
• 소스 실측: smolagents Review: Real LOC Count (BenchClaw, 2026-08)
• 종합: Smolagents — Minimal Code-First Agent Framework (ChatForest, 2026-05) · When Minimal Beats Heavyweight (Orange ITS, 2026-05)
• 공식: smolagents docs (Hugging Face)