Smolagents van Hugging Face: een gids met voorbeelden

Wat is Smolagents van Hugging Face?

Zoals beschreven in Hugging Face’s aankondigingsblog is smolagents “een heel eenvoudige bibliotheek die agentische capaciteiten voor taalmodellen ontsluit.” Maar waarom hebben we bibliotheken nodig om agents te bouwen?

In de kern worden agents aangestuurd door LLM’s om dynamisch een taak op te lossen door hun omgeving te observeren, plannen te maken en die plannen uit te voeren met de middelen die ze hebben. Het bouwen van deze agents vereist, hoewel niet onmogelijk, dat je veel componenten vanaf nul schrijft. Die componenten zorgen ervoor dat agents goed functioneren zonder je API-krediet en uitvoeringstijd te verbranden. Agentische frameworks maken dit makkelijker, zodat je het wiel niet opnieuw hoeft uit te vinden.

AI-agentframeworks krijgen vaak twee soorten kritiek:

1. Ze bouwen te veel abstractielagen, waardoor ze star en lastig te debuggen zijn.
2. Ze focussen op “workflows” in plaats van agents die zelfstandig dynamisch kunnen samenwerken.

Smolagents daarentegen heeft eigenschappen die het veelbelovend maken voor dit soort agentische toepassingen:

• De abstracties van het framework worden tot een minimum beperkt.
• Terwijl de meeste frameworks acties van agents in JSON-/tekstformaat laten definiëren, is de hoofdbenadering van smolagents Code Agents, waarbij acties worden geschreven als Python-codefragmenten (anders dan agents die code schrijven).
• Als Hugging Face-framework integreert smolagents goed met de Hub en de Transformers-bibliotheek. Je kunt veel modellen uit de Hub gebruiken (sommige alleen als Pro-gebruiker) en ook werken met proprietaire modellen van OpenAI, Anthropic, enz.
• Je kunt de al meegeleverde tools eenvoudig inzetten of met minimale moeite eigen tools definiëren, bijna net zo simpel als een Python-functie schrijven.

Deze eigenschappen maken smolagents op papier tot een plug-and-play-oplossing voor AI-agents met weinig moeite, dus laten we kijken of dat in de praktijk standhoudt.

Een demoproject bouwen met Smolagents

In deze sectie bouwen we een eenvoudige demo met smolagents. Onze applicatie laat een agent het meest upvotede paper ophalen op de Hugging Face Daily Papers-pagina. We bouwen eigen tools voor de agent en bekijken hoe het werkt.

Daily Papers, een goede bron om bij te blijven met de beste dagelijkse onderzoeksartikelen.

Smolagents instellen

Om smolagents te gebruiken hoef je alleen de bibliotheek te installeren en een Hugging Face-token op te geven. De eenvoudige setup van het framework is een pluspunt.

Installeer het pakket met:

pip install smolagentsMogelijk gemaakt door

Aangepaste tools bouwen

Hoewel het framework ingebouwde tools biedt die je direct kunt gebruiken (bijv. DuckDuckGoSearchTool), is eigen tools bouwen net zo rechttoe rechtaan. Voor ons doel bouwen we vier tools, elk met een specifiek doel:

• De titel van het beste dagelijkse paper ophalen.
• De ID van het paper ophalen aan de hand van de titel.
• Het paper downloaden van arXiv met de ID.
• Het gedownloade PDF-bestand lezen.

Een veelvoorkomende oorzaak van agentfouten is verkeerd gebruik van tools. Om tools te optimaliseren voor agentisch gebruik is het belangrijk dat agents duidelijk begrijpen welke tool ze moeten gebruiken en hoe. Wees daarom zo expliciet mogelijk bij het definiëren van deze tools:

• Kies een informatieve naam voor de functie.
• De input en output van de functie moeten typehints hebben.
• Neem een beschrijving op van het doel van de tool. Dit dient als handleiding voor de agent.

Laten we nu onze eerste aangepaste tool bouwen om de Daily Papers-pagina te parsen en de titel van het top-paper op te halen:

from smolagents import tool 
# import packages that are used in our tools
import requests
from bs4 import BeautifulSoup
import json

@tool
def get_hugging_face_top_daily_paper() -> str:
    """
    This is a tool that returns the most upvoted paper on Hugging Face daily papers.
    It returns the title of the paper
    """
    try:
      url = "<https://huggingface.co/papers>"
      response = requests.get(url)
      response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
      soup = BeautifulSoup(response.content, "html.parser")

      # Extract the title element from the JSON-like data in the "data-props" attribute
      containers = soup.find_all('div', class_='SVELTE_HYDRATER contents')
      top_paper = ""

      for container in containers:
          data_props = container.get('data-props', '')
          if data_props:
              try:
                  # Parse the JSON-like string
                  json_data = json.loads(data_props.replace('&quot;', '"'))
                  if 'dailyPapers' in json_data:
                      top_paper = json_data['dailyPapers'][0]['title']
              except json.JSONDecodeError:
                  continue

      return top_paper
    except requests.exceptions.RequestException as e:
      print(f"Error occurred while fetching the HTML: {e}")
      return NoneMogelijk gemaakt door

Let op de @tool-decorator, de duidelijke naam van de tool, de typehints en de docstring. Op dezelfde manier definiëren we de tool get_paper_id_by_title om de paper-ID op te halen aan de hand van de titel, zodat we die van arXiv kunnen downloaden. Voor deze tool gebruiken we de API van Hugging Face.

from huggingface_hub import HfApi

@tool
def get_paper_id_by_title(title: str) -> str:
    """
    This is a tool that returns the arxiv paper id by its title.
    It returns the title of the paper

    Args:
        title: The paper title for which to get the id.
    """
    api = HfApi()
    papers = api.list_papers(query=title)
    if papers:
        paper = next(iter(papers))
        return paper.id
    else:
        return NoneMogelijk gemaakt door

Het paper downloaden met de ID kan met het Python-pakket arxiv. We slaan het paper lokaal op met een specifieke naam, die we daarna gebruiken om het te lezen:

import arxiv

@tool
def download_paper_by_id(paper_id: str) -> None:
    """
    This tool gets the id of a paper and downloads it from arxiv. It saves the paper locally 
    in the current directory as "paper.pdf".

    Args:
        paper_id: The id of the paper to download.
    """
    paper = next(arxiv.Client().results(arxiv.Search(id_list=[paper_id])))
    paper.download_pdf(filename="paper.pdf")
    return NoneMogelijk gemaakt door

Om een PDF-bestand te lezen kun je het pakket pypdf gebruiken. We lezen alleen de eerste drie pagina’s van het paper om tokens te besparen.

from pypdf import PdfReader

@tool
def read_pdf_file(file_path: str) -> str:
    """
    This function reads the first three pages of a PDF file and returns its content as a string.
    Args:
        file_path: The path to the PDF file.
    Returns:
        A string containing the content of the PDF file.
    """
    content = ""
    reader = PdfReader('paper.pdf')
    print(len(reader.pages))
    pages = reader.pages[:3]
    for page in pages:
        content += page.extract_text()
    return contentMogelijk gemaakt door

Als je eigen tools definieert en de agent moeite heeft om ze correct te gebruiken of de juiste argumenten door te geven, maak dan de functie- en variabelenamen, evenals de toolbeschrijvingen, duidelijker en explicieter.

De agent uitvoeren

Met onze tools klaar kunnen we de agent initialiseren en draaien. We gebruiken het model Qwen2.5-Coder-32B-Instruct, dat gratis te gebruiken is. De tools die een agent nodig heeft kun je meegeven bij het definiëren van de agent. Je ziet dat het definiëren en draaien van een agent maar weinig code vereist:

from smolagents import CodeAgent, HfApiModel

model_id = "Qwen/Qwen2.5-Coder-32B-Instruct"

model = HfApiModel(model_id=model_id, token=<YOUR-API>)
agent = CodeAgent(tools=[get_hugging_face_top_daily_paper,
                         get_paper_id_by_title,
                         download_paper_by_id,
                         read_pdf_file],
                  model=model,
                  add_base_tools=True)

agent.run(
    "Summarize today's top paper on Hugging Face daily papers by reading it.",
)Mogelijk gemaakt door

Terwijl de agent draait, geeft hij zijn proces stap voor stap weer. Zo kun je zien hoe hij zijn acties in code definieert en daarbij de door ons geleverde tools benut:

Agentoutput in stap 0

De agent kan het paper al in de eerste stap (stap 0) lezen. In de tweede stap somt het model de kernpunten van het paper op, opnieuw in een Python-lijst.

Agentoutput in stap 1

In de derde stap (stap 2) maakt de agent een samenvatting van de kernpunten en print die in de laatste stap (stap 3).

Agentoutput in stap 2 en 3.

De agent wist te bepalen welke tools in elke stap nodig waren en rondde de taak foutloos af. Let op: de hele pijplijn kan worden geoptimaliseerd om minder tools te gebruiken, maar ik was benieuwd hoe de agent meerdere tool-calls inzet.

Voor uitdagendere taken die complexere redenering of toolgebruik vereisen, kun je ook krachtigere modellen als ruggengraat van je agents gebruiken, zoals die van OpenAI of Claude.

Conclusie

Wat zoek jij in een agentisch framework? Jouw antwoord bepaalt welke je gebruikt, maar als je een simpel framework wilt dat niet verzuipt in abstracties, je controle geeft, goed integreert en de basis levert zonder het stuur over te nemen, dan is smolagents een goede optie om te proberen.

Dankzij de goede integratie in het Hugging Face-ecosysteem heb je meer modellen en tools bij de hand, plus de steun van de open-sourcegemeenschap. Het framework doet wat het belooft. Het zou baat hebben bij meer ingebouwde tools, en laten we hopen dat dat gebeurt terwijl het verder ontwikkeld wordt.

Ben je benieuwd naar meer over AI-agents en smolagents? Mis deze bronnen niet:

• Introductie tot AI-agents: aan de slag met Auto-GPT, AgentGPT en BabyAGI
• AI-agents begrijpen: de toekomst van autonome systemen
• Smolagents-documentatie: 
• Smolagents-repository