Smolagents로 구축한 로컬 AI 에이전트 사례와 함께, Smolagents 프레임워크에 대해 소개합니다.

안녕하세요,
최근에는 대형 언어 모델(LLM)의 발전을 넘어, 이를 기반으로 다양한 작업을 자동으로 수행하는 AI 에이전트에 대한 관심이 높아지고 있습니다. 오늘은 허깅페이스에서 공개한 경량화된 오픈소스 프레임워크 Smolagents를 소개드리려 합니다. Smolagents는 LLM을 쉽게 에이전트화하여 실제 동작 가능한 작업 수행자로 바꿔주는 도구로, 간단한 설정만으로도 코드 실행, 도구 호출, 반복 추론이 가능한 AI 에이전트를 만들 수 있습니다.
그럼 이제 Smolagents의 구조와 활용 방법을 함께 살펴보겠습니다.

---

반응형

Smolagents란

Smolagents는 Hugging Face에서 개발한 경량화된 오픈소스 Python 라이브러리로, LLM을 활용하여 AI 에이전트를 손쉽게 구축할 수 있도록 설계되었습니다. 이 라이브러리는 약 1,000줄의 코드로 구성되어 있으며, 복잡한 추상화를 최소화하여 개발자가 간단한 코드만으로도 강력한 에이전트를 만들 수 있게 도와줍니다.

Smolagents의 핵심은 LLM이 외부 도구와 상호작용하며 작업을 처리하는 능력을 제공하는 것입니다. 이를 통해 LLM이 단순한 텍스트 응답을 넘어, 실제 프로그램 흐름을 제어하고 다양한 작업을 수행할 수 있는 능동적인 에이전트로 발전할 수 있습니다.

 

• 허깅페이스 Smolagents 소개글 : https://huggingface.co/blog/smolagents

Introducing smolagents: simple agents that write actions in code.

 

 

주요 특징

1. 코드 기반 에이전트 (Code Agents)

Smolagents는 에이전트의 행동을 JSON이나 텍스트 명령이 아닌 Python 코드 조각으로 정의합니다. 이를 통해 LLM이 직접 코드를 작성하고 실행함으로써, 더 높은 실행 효율성과 유연성을 제공합니다.

 

2. 다양한 LLM 지원

Hugging Face Hub에 등록된 다양한 오픈소스 LLM은 물론, OpenAI, Anthropic 등 주요 클라우드 기반 LLM과도 연동이 가능합니다. 이를 통해 개발자는 자신에게 가장 적합한 모델을 선택하여 에이전트를 구축할 수 있습니다.

 

3. 도구 통합 및 공유

Smolagents는 Hugging Face Hub와의 긴밀한 통합을 통해, Gradio Spaces와 같은 도구를 쉽게 공유하고 불러올 수 있습니다. 또한, 개발자는 자신만의 커스텀 도구를 정의하고 이를 에이전트에 통합하여 활용할 수 있습니다.

 

4. 단순하고 직관적인 API

복잡한 설정 없이도 몇 줄의 코드로 에이전트를 생성하고 실행할 수 있는 간단한 API를 제공합니다. 이를 통해 초보자부터 전문가까지 누구나 쉽게 에이전트를 개발할 수 있습니다.

 

5. 다단계 작업 처리

Smolagents는 LLM의 출력을 기반으로 반복적인 작업 수행이 가능한 다단계 에이전트(Multi-step Agent)를 지원합니다. 이를 통해 복잡한 문제 해결이나 연속적인 작업 수행이 필요한 시나리오에서도 효과적으로 활용할 수 있습니다.

 

 

라이선스

Smolagents는 Apache License 2.0 하에 배포되는 오픈소스 라이브러리로, 상업적 사용이 자유롭게 허용됩니다. 해당 라이선스는 상업적 제품이나 서비스에 통합할 수 있으며, 코드를 수정하거나 배포하는 것도 가능합니다. 또한 소스코드를 공개하지 않고 내부적으로 활용하는 것도 허용되지만, 라이선스 고지와 코드 변경 사항에 대한 명시는 필수입니다. 따라서 Smolagents는 기업 내부 시스템에 적용하거나, 외부 고객에게 제공하는 상용 서비스의 일부로 활용하는 데에도 제약이 없습니다.

 

자세한 내용은 깃허브에서 확인하실 수 있습니다.

• smolagents 깃허브 : https://github.com/huggingface/smolagents

---

1. 실행 환경

• 운영체제 : Windows 11
• Python : 3.10.0
• torch : 2.6.0 + cu126
• GPU : NVIDIA GeForce RTX 4060 Ti

 

 

2. Smolagents로 구현하는 AI 에이전트

현재 Smolagents를 활용해 AI 에이전트를 구성할 수 있는 모델로는 허깅페이스 Inference API 기반 모델, OpenAI 및 호환 서버 모델, Anthropic과 Google 모델을 지원하는 LiteLLM 기반 모델, 로컬에서 직접 실행 가능한 Transformers 모델, Microsoft Azure OpenAI 모델, Amazon Bedrock 모델 등이 있습니다.
이처럼 다양한 선택지를 통해 사용자는 환경에 맞는 LLM을 자유롭게 활용할 수 있으며, 이번 포스팅에서는 그중 로컬에서 직접 실행 가능한 Transformers 기반의 "Qwen2.5-Coder-3B-Instruct" 모델을 사용해 AI 에이전트를 구현해보겠습니다.

 

1) Qwen2.5-Coder-3B-Instruct 모델 다운로드

아래 허깅페이스 페이지에서 모든 파일을 다운로드합니다.

• Qwen2.5-Coder-3B-Instruct 허깅페이스 : https://huggingface.co/Qwen/Qwen2.5-Coder-3B-Instruct/tree/main

출처: Qwen2.5-Coder-3B-Instruct 허깅페이스 (클릭시 이미지 확대)

 

 

2) 가상 환경 설치 (선택사항)

프로젝트를 보다 깔끔하고 안정적으로 관리하기 위해 가상 환경을 생성하는 것을 권장합니다. 가상 환경을 사용하면 시스템 파이썬 환경과 독립적으로 패키지를 설치하고 관리할 수 있어, 프로젝트 간 패키지 충돌을 방지할 수 있습니다.

 

아래 명령어를 통해 가상 환경을 생성할 수 있습니다.

# Windows PowerShell
cd /path/to/Smolagents        # Smolagents 폴더로 이동 (사용자 경로에 맞게 수정)
python -m venv .venv          # 가상 환경 생성
.\.venv\Scripts\Activate.ps1  # 가상 환경 실행

 

가상 환경이 정상적으로 활성화되면 명령어 입력창 왼쪽에 (.venv) 표시가 나타납니다. 이 표시가 보이면 가상 환경이 성공적으로 설정된 것입니다.

 

3) 필수 패키지 설치

아래 명령어를 통해 필수 패키지들을 설치합니다.

# Windows PowerShell
pip install transformers smolagents safetensors requests beautifulsoup4 selenium accelerate duckduckgo-search
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu126

 

⚠️ 참고사항
- 위 명령어는 CUDA 12.6 버전에 최적화되어 있으므로, 사용 중인 GPU 드라이버가 CUDA 12.6을 지원하는지 확인해 주세요.
- CUDA가 설치되어 있지 않거나 버전이 맞지 않을 경우, GPU 가속이 정상적으로 작동하지 않을 수 있습니다.

 

4) 코드 작성

환경 설정이 완료되었다면, 이제 모델을 실행할 코드를 작성합니다. 아래 예시 코드를 사용하여 파일을 만들고, 파일 이름은 "main.py"로 저장해 줍니다.

from transformers import AutoTokenizer, AutoModelForCausalLM
from smolagents import CodeAgent, TransformersModel
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
import time
import webbrowser
import os

# === 모델 경로 설정 ===
MODEL_PATH = "Phat/to/Qwen2.5-coder-3B-Instruct"  # 사용자 환경에 맞게 수정

# === 모델 로드 ===
print("모델 로딩 중...")
tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    MODEL_PATH,
    trust_remote_code=True,
    device_map="auto"
)

llm = TransformersModel(model=model, tokenizer=tokenizer)

# === 에이전트 생성 ===
agent = CodeAgent(
    model=llm,
    tools=[],
    add_base_tools=True,
    additional_authorized_imports=["requests", "bs4"]
)

# === 스크린샷 함수 ===
def capture_screenshot(url: str, save_path: str = "screenshots/screenshot.png"):
    os.makedirs(os.path.dirname(save_path), exist_ok=True)
    print(f"스크린샷 촬영 중: {url}")
    options = Options()
    options.add_argument("--headless")
    options.add_argument("--disable-gpu")
    options.add_argument("--window-size=1280,1024")

    try:
        driver = webdriver.Chrome(options=options)
        driver.get(url)
        time.sleep(2)
        driver.save_screenshot(save_path)
        driver.quit()
        print(f"스크린샷 저장 완료: {save_path}")
    except Exception as e:
        print("스크린샷 오류:", e)

# === 메인 루프 ===
print("\nQwen2.5 HTML 에이전트 실행 중")
print("   URL 입력 시 HTML 복사 및 스크린샷을 저장합니다.")
print("   종료하려면 'exit'을 입력하세요.\n")

while True:
    url = input("URL 입력: ").strip()
    if url.lower() == "exit":
        print("종료합니다.")
        break

    if not url.startswith("http"):
        print("URL은 http:// 또는 https://로 시작해야 합니다.")
        continue

    # 스크린샷 저장
    capture_screenshot(url)
    
    print("\nQwen2.5 모델 실행 중")

    # ChatML 기반 프롬프트 작성
    messages = [
        {
            "role": "system",
            "content": "You are a helpful assistant who only outputs clean and minimal HTML code when instructed."
        },
        {
            "role": "user",
            "content": f'''
    {url} 주소에 접속했을 때 보이는 웹페이지와 비슷한 정적 HTML을 만들어줘.

    - 실제 웹 요청이나 API 호출은 하지 말고, UI 구조만 흉내 내는 HTML만 생성해줘.
    - 출력 결과는 HTML 태그(`<!DOCTYPE html>`부터 `</html>`까지)만 포함해야 해.
    - Python 코드 형식이나 html = """...""" 같은 변수 할당 없이, 순수 HTML 코드만 출력해줘.
    - 출력은 마크다운 코드 블록 없이, HTML 코드만 텍스트 형태로 보여줘 (예: ```html ... ``` 사용하지 말 것).
    '''
        }
    ]
    prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)

    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    outputs = model.generate(**inputs, max_new_tokens=1024)
    result = tokenizer.decode(outputs[0], skip_special_tokens=True)

    # 코드 블록만 추출
    import re
    matches = re.findall(r"```[a-zA-Z]*\n(.*?)```", result, re.DOTALL)
    if matches:
        clean_html = matches[0].strip()
    else:
        # fallback: 전체에서 <!DOCTYPE html>부터 </html>까지 추출
        html_match = re.search(r"<!DOCTYPE html>.*?</html>", result, re.DOTALL | re.IGNORECASE)
        if html_match:
            clean_html = html_match.group(0).strip()
        else:
            print("HTML 코드를 찾지 못했습니다.")
            clean_html = ""

    # 저장
    if clean_html:
        os.makedirs("generated", exist_ok=True)
        file_path = "generated/fake_result.html"
        with open(file_path, "w", encoding="utf-8") as f:
            f.write(clean_html)

        print(f"생성된 HTML 저장 완료: {file_path}")
        webbrowser.open("file://" + os.path.abspath(file_path))

 

 

3. Qwen2.5-Coder-3B-Instruct 기반 에이전트 실행

이 에이전트는 사용자가 웹사이트 주소를 입력하면, 해당 사이트의 화면을 스크린샷으로 저장한 뒤 이를 참고해 AI가 유사한 형태의 HTML 페이지를 자동으로 생성하도록 구성되어 있습니다. Windows PowerShell에서 코드를 실행한 후, 원하는 URL을 입력하면 작동하며, 아래는 구글 홈페이지 주소를 입력하여 생성된 HTML 예시입니다.

실행 결과

 

이 모델을 실행하는 데에는 약 20GB의 VRAM이 사용되었으며, 생성에는 약 1분 정도가 소요되었습니다. 해당 결과는 비교적 작은 모델을 사용해 URL을 참고하여 생성된 것이기 때문에, 실제 구글 사이트와는 다소 차이가 있을 수 있습니다. 그럼에도 불구하고 단순히 URL만 입력하는 것만으로 해당 사이트를 유사하게 구현해낸 점은 매우 인상적이었습니다. 향후 더 정교하고 높은 품질의 HTML을 생성하려면, 다양한 모델을 활용해 더욱 고도화된 에이전트를 구축할 수 있을 것으로 기대됩니다.

---

 

이번 포스팅에서는 허깅페이스에서 개발한 Smolagents를 활용해, LLM을 기반으로 동작하는 간단한 AI 에이전트를 구현해보았습니다. URL 입력만으로 웹페이지의 구조를 흉내 내는 HTML을 자동 생성하는 흐름을 통해, Smolagents가 얼마나 직관적이면서도 유연한 프레임워크인지 직접 확인할 수 있었습니다.

 

앞으로 더 고성능의 모델을 활용하거나 기능을 확장해 나간다면, 실제 서비스 수준의 에이전트 자동화도 충분히 기대해볼 수 있을 것입니다. AI 에이전트 개발에 관심이 있다면 Smolagents는 훌륭한 출발점이 되어줄 수 있습니다.

 

읽어주셔서 감사합니다. 😊