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

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

기존 LLM 에이전트들이 복잡한 JSON 구조에 의존하던 것과 달리, Hugging Face의 `smolagents`는 LLM이 직접 파이썬 코드를 작성하여 도구를 제어하는 방식을 채택했다. 이 라이브러리는 `@tool` 데코레이터를 통해 일반 함수를 에이전트용 도구로 변환하고, `CodeAgent`를 통해 이를 실행하는 간결한 워크플로우를 제공한다. 본문에서는 `Qwen2.5-Coder-32B-Instruct` 모델을 활용해 실시간 날씨 데이터를 조회하고 파일로 저장하는 에이전트 구현 과정을 40줄 내외의 코드로 보여준다. 이를 통해 개발자는 복잡한 프레임워크 없이도 자율적으로 작업을 수행하는 경량 AI 에이전트를 빠르게 프로덕션에 도입할 수 있다.

배경

Python 기초 지식 (변수, 함수, pip 설치), Hugging Face API 토큰, 기본적인 API 연동 개념

대상 독자

파이썬 기반으로 경량 AI 에이전트를 빠르게 구축하려는 개발자

의미 / 영향

이 기술은 복잡한 에이전트 프레임워크의 진입 장벽을 낮추어 소규모 프로젝트에서도 강력한 자율 에이전트를 도입할 수 있게 한다. 특히 코드를 직접 생성하고 실행하는 방식은 LLM의 논리적 추론 능력을 극대화하여 기존의 단순 텍스트 기반 에이전트보다 정교한 작업 수행을 가능하게 한다.

섹션별 상세

기존 에이전트 프레임워크는 도구 선택을 위해 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를 생성 및 실행하는 예시

실무 Takeaway

`smolagents`의 `@tool` 데코레이터와 Docstring을 활용하면 기존 파이썬 함수를 별도의 복잡한 설정 없이 AI 에이전트의 도구로 즉시 통합할 수 있다.
JSON 기반의 도구 호출 대신 파이썬 코드를 직접 생성하는 `CodeAgent`를 사용하면 복잡한 데이터 조작이나 반복문이 필요한 작업에서 더 높은 정확도를 얻을 수 있다.
Hugging Face의 `InferenceClientModel`을 활용해 `Qwen2.5-Coder`와 같은 오픈 소스 모델을 연결함으로써 고성능 에이전트 시스템을 저비용으로 구축 가능하다.

언급된 리소스

API DocsHugging Face smolagents Documentation

GitHubHugging Face smolagents GitHub Repository