Hugging Face smolagents 시작하기: 15분 만에 첫 번째 코드 에이전트 구축하기

섹션별 상세

기존 에이전트 프레임워크는 도구 선택을 위해 JSON이나 텍스트 매칭을 사용하지만, `smolagents`는 LLM이 직접 파이썬 코드를 작성하도록 유도한다. 파이썬 코드는 루프, 조건문, 데이터 가공을 표현하는 데 가장 정밀한 수단이므로 복잡한 논리 처리에 유리하다. 이를 통해 LLM은 도구 간의 연결을 추측하는 대신 명확한 스크립트로 실행 로직을 정의한다.

데코레이터를 활용한 직관적인 도구 정의 방식은 개발 생산성을 높인다. `@tool` 데코레이터를 사용하면 일반 파이썬 함수를 에이전트가 즉시 이해할 수 있는 도구로 래핑할 수 있으며, 함수의 Docstring은 에이전트가 도구의 용도와 인자 타입을 파악하는 핵심 데이터로 활용된다. 예제에서는 `wttr.in` API를 호출하는 함수를 정의하여 에이전트에게 외부 데이터 접근 권한을 부여하는 방식을 보여준다.

python

@tool
def get_weather(city: str) -> str:
    """
    Returns the current weather forecast for a specified city.
    Args:
        city: The name of the city to get the weather for.
    """
    response = requests.get(f"https://wttr.in/{city}?format=%C+%t")
    if response.status_code == 200:
        return f"The weather in {city} is: {response.text.strip()}"
    else:
        return "Sorry, I couldn't fetch the weather data."

@tool 데코레이터와 Docstring을 사용하여 에이전트가 사용할 수 있는 날씨 조회 도구를 정의하는 예시

CodeAgent와 LLM의 결합을 통해 자율적인 작업 수행이 가능하다. `CodeAgent` 클래스는 LLM의 추론 결과인 파이썬 코드를 샌드박스 환경에서 안전하게 실행하며, `InferenceClientModel`을 통해 Hugging Face에 호스팅된 `Qwen2.5-Coder-32B-Instruct` 같은 강력한 코드 특화 모델을 연결할 수 있다. 사용자의 자연어 요청을 입력받으면 에이전트는 필요한 도구를 조합한 코드를 생성하고 실행하여 최종 결과를 도출한다.

python

model = InferenceClientModel(
    model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
    token=hf_token
)

agent = CodeAgent(
    tools=[get_weather],
    model=model,
    add_base_tools=False
)

response = agent.run("Can you tell me the weather in Paris and also in Tokyo?")

Qwen2.5-Coder 모델을 연결하고 정의한 도구를 포함하여 CodeAgent를 생성 및 실행하는 예시

용어 해설

스몰에이전트(smolagents): — Hugging Face에서 개발한 경량 AI 에이전트 라이브러리로, LLM이 파이썬 코드를 직접 작성하고 실행하여 도구를 사용하게 함으로써 복잡한 로직 처리를 단순화한다.
코드 에이전트(Code Agent): — 텍스트나 JSON 대신 프로그래밍 코드(주로 파이썬)를 생성하여 작업을 수행하는 AI 에이전트로, 논리적 흐름과 데이터 처리가 정밀하다는 장점이 있다.
도구 호출(Tool Calling): — LLM이 외부 API 호출이나 함수 실행이 필요하다고 판단할 때, 적절한 도구를 선택하고 필요한 인자를 생성하여 실행하는 메커니즘이다.
추론 클라이언트 모델(Inference Client Model): — Hugging Face Hub에 호스팅된 대규모 언어 모델에 API를 통해 접근하여 추론을 수행할 수 있게 해주는 인터페이스이다.

기술

smolagents
Python
Qwen2.5-Coder-32B-Instruct
Hugging Face Inference API

활용 사례

실시간 날씨 정보 조회 에이전트
자동 데이터 저장 및 파일 관리 에이전트
API 연동형 자율 작업 봇

언급된 리소스

API DocsHugging Face smolagents Documentation

GitHubHugging Face smolagents GitHub Repository