smolagents

만든 곳 Hugging Face

코드를 작성·실행해 행동하는 에이전트를 위한 Hugging Face의 미니멀 라이브러리

웹사이트 ↗ 저장소 ↗ 문서 ↗

v1.26.02026-05-29PythonApache-2.0

#code-agents #huggingface #litellm #python

28.5k 완전 무료 오픈소스

문서버전 1.0 · 업데이트 2026년 6월 28일

개요

smolagents는 의도적으로 아주 작은 Hugging Face 라이브러리입니다 — 에이전트 로직이 약 1,000줄에 담깁니다 — 그리고 코드 에이전트, 즉 Python을 작성·실행해 행동하는 방식을 중심으로 설계됐습니다.
모델에 구애받지 않아 로컬 transformers, Hugging Face Hub 모델, 또는 LiteLLM을 통한 임의 제공자를 쓸 수 있습니다.

flowchart LR
  task[task] --> agent[CodeAgent]
  agent --> code[writes Python]
  code --> run[executes]
  run --> agent
  agent --> out[answer]

코드 샘플 탭에서 LiteLLM 기반 코드 에이전트를 보여줍니다.

언제 쓰면 좋은가

최소한의, 손대기 쉬운 에이전트 루프를 원하거나, JSON 함수 호출보다 코드 작성 방식이 과제(수학·데이터 가공·다단계 도구 사용)에 더 잘 맞을 때 고르세요.

예제

Python · code agent

언제 쓰나

JSON 도구 호출 대신 코드를 작성해 행동하는 에이전트를 원할 때 — 계산 과제는 보통 더 적은 단계로 끝납니다.

흐름

CodeAgent가 Python을 작성해 샌드박스에서 실행하고, 결과를 관찰하며 답이 나올 때까지 반복합니다.

구조

flowchart LR
  task[task] --> agent[CodeAgent]
  agent --> code[writes Python]
  code --> run[executes]
  run --> agent
  agent --> out[answer]

from smolagents import CodeAgent, LiteLLMModel

# Code agents act by writing and running Python; LiteLLM routes to any provider.
model = LiteLLMModel(model_id="anthropic/claude-opus-4-8")
agent = CodeAgent(tools=[], model=model)
print(agent.run("Compute 2 ** 10 + 5 in Python and return the number."))

예제

smolagents — 구현 샘플

실제로 실행 가능한 미니 프로젝트입니다. 받아서 Docker로 실행해 보세요.

GitHub에서 samples/smolagents_1 보기 ↗

2026년 6월 28일

smolagents — 구현 샘플

아주 작은 smolagents 샘플입니다. 코드를 작성·실행해 과제를 푸는 코드 에이전트를 실행합니다. 모델은 LiteLLM으로 라우팅되므로 MODEL로 어떤 제공자든 쓸 수 있습니다.

설정

cd samples/smolagents_1
cp .env.sample .env
# .env 편집: ANTHROPIC_API_KEY 설정(또는 MODEL과 해당 키로 교체)

Docker로 실행

cd samples/smolagents_1
docker build -t aas-smolagents .
docker run --rm --env-file .env aas-smolagents "Compute 2 ** 10 + 5 in Python and return the number."

Docker로 실행 (DooD를 쓰는 devcontainer에서)

Docker-outside-of-Docker에서는 포그라운드 docker run이 아무것도 출력하지 않을 수 있습니다 — detached로 실행하고 로그를 따라가세요:

docker logs -f "$(docker run -d --env-file .env aas-smolagents "Compute 2 ** 10 + 5 in Python and return the number.")"

로컬에서 실행

cd samples/smolagents_1
pip install -r requirements.txt
python app.py "Compute 2 ** 10 + 5 in Python and return the number."

실행 결과

에이전트가 추론 단계를 출력하고, 마지막 줄이 정답입니다. 표현은 달라져도 계산된 값은 일정합니다. claude-opus-4-8로 실행한 한 예입니다:

result: 1029

파일

.env.sample

# Copy to `.env` and add your Anthropic API key (or swap MODEL for another
# provider that LiteLLM supports, with the matching key).
#   cp .env.sample .env
ANTHROPIC_API_KEY=

MODEL=anthropic/claude-opus-4-8

app.py

"""smolagents: a code agent that acts by writing and running Python.

The agent writes Python to solve the task, runs it, and returns the result.
Model is routed through LiteLLM, so any provider works via MODEL.

Run:
    docker build -t aas-smolagents .
    docker run --rm --env-file .env aas-smolagents "Compute 2 ** 10 + 5."
"""

import os
import sys

from dotenv import load_dotenv
from smolagents import CodeAgent, LiteLLMModel

load_dotenv()

MODEL = os.environ.get("MODEL", "anthropic/claude-opus-4-8")


def main() -> None:
    task = " ".join(sys.argv[1:]) or "Compute 2 ** 10 + 5 in Python and return the number."
    agent = CodeAgent(tools=[], model=LiteLLMModel(model_id=MODEL))
    print("result:", agent.run(task))


if __name__ == "__main__":
    main()

Dockerfile

FROM python:3.13-slim

ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

ENTRYPOINT ["python", "app.py"]