SmolAgents, HuggingFace🤗가 공개한 LLM 중심의 Agent 기능 구현 라이브러리

[9bow (박정환)]

SmolAgents 소개

Hugging Face는 AI 언어 모델(LLM)을 기반으로 워크플로우를 간소화하고 에이전트를 구축할 수 있는 경량 라이브러리인 Smolagents를 공개했습니다. 이 라이브러리는 LLM이 외부 도구와 상호작용하며 작업을 처리하는 능력을 제공합니다. Smolagents는 단순성과 효율성에 중점을 두고 설계되어 Python 코드 기반의 액션을 작성하는 에이전트를 쉽게 만들 수 있습니다:

from smolagents import CodeAgent, DuckDuckGoSearchTool, HfApiModel

agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=HfApiModel())

agent.run("표범이 전속력으로 퐁데자르(Pont des Arts) 거리를 달리는데 몇 초나 걸릴까요?")

Agent란 무엇인가요?

AI Agent는 LLM의 출력으로 워크플로우를 제어하는 프로그램입니다.

AI Agents are programs where LLM outputs control the workflow .

이러한 AI Agent의 정의에서 '에이전트'는 (0 또는 1과 같은) 불연속적인 정의가 아니라, 워크플로우에서 LLM에 더 많거나 적은 권한을 부여함에 따라 연속적인 스펙트럼으로 진화할 수 있습니다. 아래 표와 같이 시스템에 따라 에이전시가 어떻게 달라지는지를 확인할 수 있습니다:

에이전시 수준(Agency Level)	설명	호출 방식	예시 패턴(Example Pattern)
☆☆☆	LLM 출력은 프로그램 흐름에 영향을 미치지 않음	단순 프로세서(Simple Processor)	process_llm_output(llm_response)
★☆☆	LLM 출력으로 기본 제어 흐름을 결정	라우터(Router)	if llm_decision(): path_a() else: path_b()
★★☆	LLM 출력으로 함수 실행을 결정	도구 호출(Tool Call)	run_function(llm_chosen_tool, llm_chosen_args)
★★★	LLM 출력으로 반복과 프로그램 연속성 제어	다단계 에이전트(Multi-step Agent)	while llm_should_continue(): execute_next_step()
★★★	하나의 에이전트 워크플로가 다른 에이전트 워크플로를 시작할 수 있음	멀티 에이전트(Multi-Agent)	if llm_trigger(): execute_agent()

다단계 에이전트는 다음과 같은 코드 구조를 갖습니다:

memory = [user_defined_task]                 # 사용자가 사전에 정의한 작업
while llm_should_continue(memory):       # 다단계(Multi-Step) 반복 부분
    action = llm_get_next_action(memory) # 도구 호출 부분
    observations = execute_action(action)
    memory += [action, observations]

이러한 시스템은 주어진 작업을 만족스럽게 해결했다고 판단할 때까지 각 단계마다 새로운 작업을 실행하는 루프를 반복합니다. 다음은 다단계 에이전트가 간단한 수학 문제를 푸는 예시입니다:

Agent는 언제 사용하고 언제 사용하지 않아야 할까요?

에이전트를 사용하는 상황

에이전트는 AI 언어 모델(LLM)이 앱의 워크플로우를 결정해야 하는 상황에서 유용합니다. 특히, 사전에 워크플로우를 명확히 정의하기 어려운 복잡한 문제를 해결할 때 필수적입니다.

예시: 복잡한 사용자 요청

• 사용자가 복잡한 조건을 제시하며 특정한 요구를 할 경우:
  • 요청: "월요일에 올 수 있지만, 여권을 잊어 수요일로 지연될 가능성이 있습니다. 화요일 아침에 나와 짐을 함께 서핑 장소로 이동시키고 싶습니다. 취소 보험을 추가할 수 있을까요?"
  • 특징: 이러한 요청은 여러 변수(날씨, 거리, 직원 가용성 등)에 의존하며, 미리 정의된 기준만으로 처리할 수 없습니다.

이런 경우, 에이전트 기반 설계가 필요합니다. 에이전트는 다음과 같은 도구와 상호작용하여 문제를 해결합니다:

• 날씨 API: 날씨 정보를 확인
• Google Maps API: 이동 거리 계산
• 직원 대시보드: 직원 가용성 조회
• RAG 시스템: 지식 기반 검색

에이전트를 사용하지 않는 상황

간단하고 고정된 워크플로우를 처리하는 경우, 에이전트는 불필요하며 오히려 비효율적일 수 있습니다.

예시: 서핑 여행 웹사이트의 기본 요청

• 요청이 명확하게 두 가지 범주로 나뉘는 경우:
  1. 여행 정보 요청: 사용자가 검색창에서 정보를 탐색.
  2. 영업팀 상담 요청: 사용자가 연락 양식을 작성.

이와 같은 결정론적 워크플로우는 다음과 같은 특징을 가집니다:

• 예측 가능성: 요청의 범주가 사전에 정의 가능.
• 신뢰성: 에이전트를 도입하지 않아도 100% 신뢰 가능한 결과 제공.
• 단순성: LLM의 예측 오류로 인한 위험 제거.

결론적으로, 단순하고 명확한 워크플로우에서는 에이전트를 배제하고 전통적인 코딩 방식으로 구현하는 것이 더 효율적입니다.

코드 에이전트(Code Agents)

다단계 에이전트(Multi-Step Agents)에서 각 단계마다 LLM은 외부 도구에 대한 호출의 형태로 액션(Action)을 작성할 수 있습니다. OpenAI나 Anthropic 등에서는 이러한 액션을 '사용할 도구(함수) 이름과 인자를 JSON 형태'로 작성하고, 이를 파싱하여 어떠한 도구를 어떠한 인수를 사용하여 실행할지 파악합니다.

그러나 다수의 연구 결과들([1][2][3])에 따르면, JSON 대신 코드로 도구 호출을 작성하는 방식이 훨씬 더 효율적이고 유연하다는 점이 입증되었습니다. 이는 우리가 컴퓨터가 작업을 수행하기 위한 방식으로 JSON 조각(Snippet) 대신 프로그래밍 언어를 사용하고 있기 때문입니다. 다음은 "Executable Code Actions Elicit Better LLM Agents" 연구에서 코드로 액션을 작성할 때의 몇 가지 이점을 정리한 글입니다:

특히, 구성 가능성(Composability), 객체 관리(Object Management), 일반성(Generality) 및 LLM 학습 데이터의 표현(Representation in LLM training data)에서 JSON보다 프로그래밍 언어로 작성한 코드로 액션을 작성하는 것이 더 낫습니다.

SmolAgnets 소개: 더 간단하고 강력한 에이전트 구축을 위한 라이브러리

SmolAgents는 transformers.agents의 후속 버전으로, 향후 transformers.agents가 더 이상 사용되지 않게 되면 이를 대체할 예정입니다.

SmolAgents를 만들 때 다음과 같은 목표들을 고려하였습니다:

• 단순성(Simplicity)
  • 에이전트 로직은 약 1000줄의 코드로 구성됩니다.
  • 불필요한 추상화를 제거하고 원시 코드 위에 최소한의 구조만 추가했습니다.
• 코드 에이전트 지원(First-class support for Code Agents)
  • 에이전트가 Python 코드로 동작을 작성합니다.
  • 보안을 위해 E2B를 통한 샌드박스 환경을 지원합니다.
  • JSON 기반 텍스트 액션을 작성하는 ToolCallingAgent도 지원합니다.
• 허브 통합(Hub integrations)
  • 도구를 Hugging Face Hub에 공유하거나 Hub에서 로드할 수 있습니다.
• 다양한 LLM 지원(Support for any LLM)
  • Hugging Face의 transformers 모델과 API를 지원합니다.
  • OpenAI, Anthropic 등 다양한 클라우드 LLM을 LiteLLM을 통해 통합 지원합니다.

에이전트 구축 방법

SmolAgents를 사용하여 에이전트를 구축하려면 다음 두 가지 요소가 필요합니다:

• Tools (도구)
  에이전트가 접근 가능한 도구의 목록입니다.
  도구는 Python 함수로 작성되며, 함수의 입력과 출력에 타입 힌트를 추가합니다. @tool 데코레이터를 사용하여 도구로 등록할 수 있습니다.
• Model (모델)
  에이전트의 엔진 역할을 하는 언어 모델(LLM)입니다.
  • Hugging Face API를 사용하는 HfApiModel
  • 100개 이상의 클라우드 LLM을 지원하는 LiteLLMModel

다음은 Google Maps API를 사용하여 두 장소 간 이동 시간을 계산하는 사용자 정의 도구와 이를 활용한 여행 계획 에이전트를 구성하는 예시 코드입니다:

from typing import Optional
from smolagents import CodeAgent, HfApiModel, tool

@tool
def get_travel_duration(start_location: str, destination_location: str, departure_time: Optional[int] = None) -> str:
    """Gets the travel time in car between two places.
    
    Args:
        start_location: the place from which you start your ride
        destination_location: the place of arrival
        departure_time: the departure time, provide only a `datetime.datetime` if you want to specify this
    """
    import googlemaps # All imports are placed within the function, to allow for sharing to Hub.
    import os

    gmaps = googlemaps.Client(os.getenv("GMAPS_API_KEY"))

    if departure_time is None:
        from datetime import datetime
        departure_time = datetime(2025, 1, 6, 11, 0)

    directions_result = gmaps.directions(
        start_location,
        destination_location,
        mode="transit",
        departure_time=departure_time
    )
    return directions_result[0]["legs"][0]["duration"]["text"]

agent = CodeAgent(tools=[get_travel_duration], model=HfApiModel(), additional_authorized_imports=["datetime"])

agent.run("파리 시내를 둘러볼 수 있는 장소와 시간을 알려주시겠어요? 시내든 외곽이든 상관없지만 하루 정도면 충분합니다. 저는 대중교통으로만 이동합니다.")

위와 같은 사용자의 입력에 따라 여러 도구들을 호출한 뒤, 다음과 같은 여행 일정을 제안할 것입니다:

파리에서의 하루 일정:
- 09:00~10:30: 에펠탑 방문
- 11:00~12:30: 루브르 박물관 방문
- 13:00~14:30: 노트르담 대성당 방문
- 15:30~17:00: 베르사유 궁전 방문
* 주의: 노트르담 대성당에서 베르사유 궁전까지 이동 시간은 약 59분입니다.

또한, 이러한 도구를 Hub에 공유하는 방법도 간단합니다:

get_travel_duration.push_to_hub("{your_username}/get-travel-duration-tool")

공유된 도구는 Hub의 스페이스에서 확인할 수 있습니다.

성능 비교

SmolAgents를 사용하여 오픈소스 모델과 상용 모델을 이 벤치마크로 비교한 결과, **코드 기반 에이전트(Code Agents)**가 JSON 기반 에이전트보다 성능이 뛰어난 것으로 나타났습니다.

더 읽어보기

• 가이드 투어를 통해 라이브러리 사용법에 익숙해지세요.

• 도구(Tools) 및 일반적인 모범 사례(General Best Practices)

• 특정 시스템을 설정하기 위한 예제를 살펴보세요: Text-to-SQL 및 Agent RAG, 멀티에이전트 오케스트레이션

• 에이전트에 대해서 더 알아보세요:

  • Anthropic의 이 훌륭한 블로그 게시물은 에이전트에 대한 일반적인 지식을 제공합니다.

  • 이 컬렉션은 에이전트에 관한 영향력 있는 연구 논문을 모았습니다.

SmolAgents 소개 블로그 글

Introducing smolagents: simple agents that write actions in code.

SmolAgents Github 저장소

GitHub - huggingface/smolagents: 🤗 smolagents: a barebones library for agents....

더 읽어보기

---

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~