Smolagents di Hugging Face: guida con esempi

Che cos’è Smolagents di Hugging Face?

Come descritto nel post di annuncio di Hugging Face, smolagents è “una libreria molto semplice che sblocca capacità agentiche per i modelli linguistici”. Ma perché abbiamo bisogno di librerie per costruire agenti?

Alla base, gli agenti sono alimentati da LLM per risolvere dinamicamente un compito osservando l’ambiente, elaborando piani ed eseguendoli con la propria cassetta degli attrezzi. Costruire questi agenti, pur non essendo impossibile, richiede di scrivere da zero molti componenti. Questi componenti assicurano che gli agenti funzionino correttamente senza bruciare credito API e tempo di esecuzione. I framework agentici rendono tutto più semplice, così non devi reinventare la ruota.

I framework per agenti AI sono spesso criticati per due motivi:

1. Costruiscono troppi strati di astrazione, risultando rigidi e difficili da fare debug.
2. Si concentrano sui “workflow” invece di creare agenti che possano collaborare autonomamente in modo dinamico.

D’altra parte, smolagents ha qualità che lo rendono molto promettente per queste applicazioni agentiche:

• Le astrazioni del framework sono ridotte al minimo.
• Mentre la maggior parte dei framework fa definire agli agenti le azioni in formato JSON/testo, l’approccio principale di smolagents sono i Code Agents, in cui le azioni sono scritte come snippet di codice Python (diverso dagli agenti che scrivono codice).
• Essendo un framework Hugging Face, smolagents si integra bene con l’Hub e con la libreria Transformers. Puoi usare molti modelli dall’hub (alcuni sono disponibili solo come utente Pro) e puoi anche lavorare con modelli proprietari di OpenAI, Anthropic, ecc.
• Puoi utilizzare facilmente gli strumenti già forniti o definire i tuoi strumenti personalizzati con il minimo sforzo, quasi come scrivere una funzione Python.

Queste qualità sono, sulla carta, ciò che rende smolagents plug-and-play con gli agenti AI con poco sforzo, quindi vediamo se reggono in pratica.

Creare un progetto demo con Smolagents

In questa sezione costruiremo una semplice demo con smolagents. La nostra applicazione avrà un agente che recupera l’articolo con più upvote nella pagina Daily Papers di Hugging Face. Creiamo strumenti personalizzati per l’agente e lo vediamo all’opera.

Daily Papers, una buona fonte per restare aggiornati sui principali paper di ricerca giornalieri.

Configurare smolagents

Per usare smolagents ti basta installare la libreria e fornire un token di Hugging Face. La semplicità di setup del framework è un punto a favore.

Per installare il pacchetto, esegui:

pip install smolagentsOfferto da

Creare strumenti personalizzati

Sebbene il framework fornisca strumenti integrati utilizzabili subito (ad es. DuckDuckGoSearchTool), creare i tuoi strumenti personalizzati è altrettanto semplice. Per il nostro scopo, creiamo quattro strumenti, ciascuno con un obiettivo specifico:

• Ottenere il titolo del paper giornaliero in cima alla classifica.
• Ottenere l’ID del paper a partire dal suo titolo.
• Scaricare il paper da arXiv con l’ID.
• Leggere il file PDF scaricato.

Una causa comune di errori degli agenti è l’uso degli strumenti. Per ottimizzare gli strumenti per scopi agentici, è importante assicurarsi che gli agenti capiscano chiaramente quale strumento usare e come usarlo. Per riuscirci, sii il più esplicito possibile quando definisci questi strumenti:

• Scegli un nome informativo per la funzione.
• Gli input e gli output della funzione dovrebbero avere type hint.
• Includi una descrizione dello scopo dello strumento. Funziona come un manuale per l’agente.

Ora creiamo il nostro primo strumento personalizzato per analizzare la pagina dei daily papers e ottenere il titolo del paper in cima:

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 NoneOfferto da

Nota il decorator @tool, la denominazione chiara dello strumento, i type hint e la docstring. Allo stesso modo, definiamo lo strumento get_paper_id_by_title per ottenere l’ID del paper dal titolo, così da poterlo scaricare da arXiv. Per questo strumento, utilizziamo le API di 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 NoneOfferto da

Scaricare il paper usando il suo ID si può fare con il pacchetto Python arxiv. Salviamo il paper in locale con un nome specifico, che poi useremo per leggerlo:

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 NoneOfferto da

Per leggere un file PDF puoi usare il pacchetto pypdf. Leggeremo solo le prime tre pagine del paper per risparmiare token.

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 contentOfferto da

Se definisci strumenti personalizzati e l’agente fatica a usarli correttamente o a passare gli argomenti giusti, valuta di rendere più chiari ed espliciti i nomi di funzioni e variabili, oltre alle descrizioni degli strumenti.

Esecuzione dell’agente

Con i nostri strumenti pronti, possiamo inizializzare ed eseguire l’agente. Usiamo il modello Qwen2.5-Coder-32B-Instruct, che è gratuito. Gli strumenti necessari a un agente possono essere passati durante la definizione dell’agente. Come vedi, definire ed eseguire un agente richiede pochissimo codice:

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.",
)Offerto da

Mentre l’agente opera, mostra in output il suo processo passo dopo passo. Questo ci permette di vedere come definisce le azioni in codice utilizzando gli strumenti personalizzati che abbiamo fornito:

Output dell’agente allo step 0

L’agente può finire di leggere il paper già nel primo passaggio (Step 0). Nel secondo passaggio, il modello elenca i punti chiave del paper, di nuovo, in una lista Python.

Output dell’agente allo step 1

Nel terzo passaggio (Step 2), l’agente crea un riassunto dei punti chiave e lo stampa nel passaggio finale (Step 3).

Output dell’agente negli step 2, 3.

L’agente è stato in grado di identificare quali strumenti usare a ogni passaggio e ha completato il compito senza errori. Nota che l’intera pipeline potrebbe essere ottimizzata per usare meno strumenti, ma ero curioso di vedere come l’agente gestisce più chiamate a strumenti.

Per compiti più impegnativi, che richiedono ragionamento o uso degli strumenti più complessi, puoi anche usare modelli più capaci come base dei tuoi agenti, come quelli offerti da OpenAI o Claude.

Conclusione

Cosa cerchi in un framework agentico? La tua risposta chiarisce quale usare, ma se è un framework semplice, non appesantito da astrazioni, che ti dà controllo, ha buone integrazioni e fornisce le basi senza toglierti il volante, allora smolagents è una buona opzione da provare.

Essere ben integrato nell’ecosistema Hugging Face significa avere a disposizione più modelli e strumenti, oltre al supporto della community open source. Il framework mantiene ciò che promette. Potrebbe trarre vantaggio da più strumenti integrati e possiamo incrociare le dita per vedere che accada man mano che viene sviluppato.

Se sei curioso di leggere di più sugli agenti AI e su smolagents, non perderti queste risorse:

• Introduzione agli agenti AI: iniziare con Auto-GPT, AgentGPT e BabyAGI
• Capire gli agenti AI: il futuro dei sistemi autonomi
• Documentazione di Smolagents: 
• Repository di Smolagents