In questa visita guidata imparerete come costruire un agente, come eseguirlo e come personalizzarlo per farlo funzionare meglio per il vostro caso d'uso.
Costruire il vostro agente #
Per inizializzare un agente minimo, sono necessari almeno questi due argomenti:
modelloun modello di generazione del testo per alimentare il vostro agente - perché l'agente è diverso da un semplice LLM, è un sistema che usa un LLM come motore. È possibile utilizzare una qualsiasi di queste opzioni:- TrasformatoriModello prende un oggetto preinizializzato
trasformatoriper eseguire l'inferenza sulla propria macchina locale usandotrasformatori. - HfApiModel fa leva su un
huggingface_hub.InferenceClientsotto il cofano. - Modello LiteLLMM consente di chiamare oltre 100 modelli diversi attraverso LiteLLM!
- TrasformatoriModello prende un oggetto preinizializzato
strumenti, Un elenco diStrumentiche l'agente può utilizzare per risolvere il compito. Può essere un elenco vuoto. È anche possibile aggiungere la casella degli strumenti predefinita in cima al proprio elenco di strumentistrumentidefinendo l'argomento opzionaleadd_base_tools=True.
Una volta che si dispone di questi due argomenti, strumenti e modelloè possibile creare un agente ed eseguirlo. È possibile utilizzare qualsiasi LLM, sia tramite Viso abbracciato API, trasformatori, ollama, o LiteLLM.
Viso abbracciato API
Modello di trasformatori locali
OpenAI o API antropica
Ollama
L'API di Hugging Face può essere utilizzata gratuitamente senza un token, ma avrà una limitazione di velocità.
Per accedere ai modelli con accesso limitato o per aumentare i limiti tariffari con un account PRO, è necessario impostare la variabile d'ambiente HF_TOKEN o passare gettone all'inizializzazione di HfApiModel.
Copiato
da smolagents import CodeAgent, HfApiModel
model_id = "meta-llama/Llama-3.3-70B-Instruct"
model = HfApiModel(model_id=model_id, token="")
agent = CodeAgent(tools=[], model=model, add_base_tools=True)
agent.run(
"Potresti darmi il 118° numero della sequenza di Fibonacci?",
)CodeAgent e ToolCallingAgent #
Il CodiceAgente è il nostro agente predefinito. Scriverà ed eseguirà frammenti di codice python a ogni passo.
Per impostazione predefinita, l'esecuzione avviene nell'ambiente locale. Questo dovrebbe essere sicuro, perché le uniche funzioni che possono essere chiamate sono gli strumenti forniti dall'utente (specialmente se si tratta solo di strumenti di Hugging Face) e un insieme di funzioni sicure predefinite come stampa o le funzioni del programma matematica per cui si è già limitati in ciò che si può eseguire.
Inoltre, l'interprete Python non consente importazioni predefinite al di fuori di un elenco sicuro, quindi tutti gli attacchi più ovvi non dovrebbero essere un problema. È possibile autorizzare importazioni aggiuntive passando i moduli autorizzati come elenco di stringhe nell'argomento importazioni_autorizzate_aggiuntive all'inizializzazione dell'applicazione CodiceAgente:
Copiato
model = HfApiModel()
agent = CodeAgent(tools=[], model=model, additional_authorized_imports=['requests', 'bs4'])
agent.run("Potresti farmi avere il titolo della pagina all'url 'https://huggingface.co/blog'?")L'LLM può generare codice arbitrario che verrà poi eseguito: non aggiungere importazioni non sicure!
L'esecuzione si interrompe in caso di codice che tenta di eseguire un'operazione illegale o se si verifica un errore regolare di Python con il codice generato dall'agente.
Si può anche utilizzare Esecutore di codice E2B al posto dell'interprete locale di Python, prima di tutto impostazione del E2B_API_KEY variabile d'ambiente e poi passare use_e2b_executor=True all'inizializzazione dell'agente.
Per saperne di più sull'esecuzione del codice in questa esercitazione.
Supportiamo anche il modo ampiamente diffuso di scrivere le azioni come blob di tipo JSON: si tratta di Agente di chiamata dello strumentofunziona più o meno come CodiceAgente, naturalmente senza importazioni_autorizzate_aggiuntive poiché non esegue codice:
Copiato
da smolagents import ToolCallingAgent
agent = ToolCallingAgent(tools=[], model=model)
agent.run("Potresti trovarmi il titolo della pagina all'URL 'https://huggingface.co/blog'?")Ispezione di un'esecuzione dell'agente #
Ecco alcuni attributi utili per verificare cosa è successo dopo una corsa:
agent.logsmemorizza i log a grana fine dell'agente. A ogni passo dell'esecuzione dell'agente, tutto viene memorizzato in un dizionario che poi viene aggiunto aagent.logs.- In corsa
agent.write_inner_memory_from_logs()crea una memoria interna dei registri dell'agente per la visualizzazione da parte di LLM, come un elenco di messaggi di chat. Questo metodo analizza ogni fase del registro e memorizza in un messaggio solo ciò che gli interessa: ad esempio, salverà il prompt di sistema e l'attività in messaggi separati, poi per ogni fase memorizzerà l'output di LLM in un messaggio e l'output della chiamata allo strumento in un altro messaggio. Si può usare questo metodo se si desidera una visione di livello superiore di ciò che è accaduto, ma non tutti i registri saranno trascritti con questo metodo.
Strumenti #
Uno strumento è una funzione atomica che deve essere utilizzata da un agente. Per essere utilizzato da un LLM, ha bisogno anche di alcuni attributi che costituiscono la sua API e che saranno utilizzati per descrivere al LLM come chiamare questo strumento:
- Un nome
- Una descrizione
- Tipi di ingresso e descrizioni
- Un tipo di uscita
È possibile, ad esempio, controllare il valore StrumentoInterpretePython: ha un nome, una descrizione, descrizioni di input, un tipo di output e un in avanti per eseguire l'azione.
Quando l'agente viene inizializzato, gli attributi dello strumento vengono utilizzati per generare una descrizione dello strumento che viene inserita nel prompt di sistema dell'agente. In questo modo l'agente sa quali strumenti può usare e perché.
Casella degli strumenti predefinita #
Transformers viene fornito con un set di strumenti predefinito per il potenziamento degli agenti, che si può aggiungere al proprio agente al momento dell'inizializzazione con l'argomento add_base_tools = Vero:
- Ricerca web DuckDuckGo*: esegue una ricerca sul Web utilizzando il browser DuckDuckGo.
- Interprete di codice Python: esegue il codice Python generato da LLM in un ambiente sicuro. Questo strumento sarà aggiunto solo a Agente di chiamata dello strumento se lo si inizializza con
add_base_tools=Truepoiché l'agente basato sul codice può già eseguire nativamente il codice Python - Trascrittore: una pipeline speech-to-text costruita su Whisper-Turbo che trascrive un audio in testo.
È possibile utilizzare manualmente uno strumento chiamandolo con i suoi argomenti.
Copiato
da smolagents importiamo DuckDuckGoSearchTool
search_tool = DuckDuckGoSearchTool()
print(search_tool("Chi è l'attuale presidente della Russia?"))Creare un nuovo strumento #
È possibile creare strumenti personalizzati per casi d'uso non coperti dagli strumenti predefiniti di Hugging Face. Ad esempio, creiamo uno strumento che restituisca il modello più scaricato per una determinata attività dall'Hub.
Iniziate con il codice qui sotto.
Copiato
da huggingface_hub importa elenco_modelli compito = "classificazione del testo" most_downloaded_model = next(iter(list_models(filter=task, sort="downloads", direction=-1)) print(most_downloaded_model.id)
Questo codice può essere rapidamente convertito in uno strumento, semplicemente avvolgendolo in una funzione e aggiungendo l'opzione strumento decoratore: Questo non è l'unico modo per costruire lo strumento: è possibile definirlo direttamente come una sottoclasse di Strumentoche offre una maggiore flessibilità, ad esempio la possibilità di inizializzare attributi di classe pesanti.
Vediamo come funziona per entrambe le opzioni:
Decorare una funzione con @tool
Strumento di sottoclasse
Copiato
da smolagents importiamo lo strumento
@strumento
def model_download_tool(task: str) -> str:
"""
È uno strumento che restituisce il modello più scaricato di una determinata attività sull'hub Hugging Face.
Restituisce il nome del punto di controllo.
Args:
attività: L'attività per cui ottenere il conteggio dei download.
"""
most_downloaded_model = next(iter(list_models(filter=task, sort="downloads", direction=-1))
restituire most_downloaded_model.idLa funzione necessita di:
- Un nome chiaro. Il nome deve essere sufficientemente descrittivo di ciò che fa questo strumento per aiutare il cervello LLM che alimenta l'agente. Dal momento che questo strumento restituisce il modello con il maggior numero di download per un compito, chiamiamolo
strumento_di_download_del_modello. - Suggerimenti di tipo su ingressi e uscite
- Una descrizione, che include una parte "Args:" in cui viene descritto ogni argomento (senza indicazione del tipo, questa volta, che sarà ricavato dal suggerimento del tipo). Come per il nome dello strumento, questa descrizione è un manuale di istruzioni per l'LLM che alimenta l'agente, quindi non trascuratela. Tutti questi elementi saranno automaticamente inseriti nel prompt di sistema dell'agente al momento dell'inizializzazione: sforzatevi quindi di renderli il più chiari possibile!
Questo formato di definizione è lo stesso degli schemi degli strumenti utilizzati in applica_template_chatl'unica differenza è l'aggiunta di strumento decoratore: per saperne di più sull'uso dello strumento API qui.
Quindi è possibile inizializzare direttamente l'agente:
Copiato
da smolagents import CodeAgent, HfApiModel
agent = CodeAgent(tools=[model_download_tool], model=HfApiModel())
agent.run(
"Puoi darmi il nome del modello che ha il maggior numero di download nell'attività 'text-to-video' sull'Hub Hugging Face?".
)Si ottengono i seguenti log:
Copiato
╭──────────────────────────────────────── nuova corsa ─────────────────────────────────────────╮
│ │
│ Potete darmi il nome del modello che ha il maggior numero di download nel task 'text-to-video' │
│ nell'attività "Hugging Face Hub"? │
│ │
╰─ HfApiModel - Qwen/Qwen2.5-Coder-32B-Instruct ───────────────────────────────────────────╯
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Passo 0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─ Esecuzione di questo codice: ───────────────────────────────────────────────────────────────────╮
│ 1 model_name = model_download_tool(task="text-to-video") │
│ 2 print(nome_modello) │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
Registri di esecuzione:
ByteDance/AnimateDiff-Lightning
Uscita: Nessuno
[Passo 0: Durata 0,27 secondi| Gettoni di input: 2.069 | Gettoni di output: 60]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Passo 1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Esecuzione del codice: ───────────────────────────────────────────────────────────────────╮
│ 1 final_answer("ByteDance/AnimateDiff-Lightning") │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
Uscita - Risposta finale: ByteDance/AnimateDiff-Lightning
[Passo 1: Durata 0,10 secondi| Gettoni di input: 4.288 | Gettoni di output: 148]
Uscita[20]: 'ByteDance/AnimateDiff-Lightning'Per saperne di più sugli strumenti, consultare la sezione Tutorial dedicato.
Agenti multipli #
I sistemi multi-agente sono stati introdotti con il framework Microsoft Autogen.
In questo tipo di struttura, ci sono diversi agenti che lavorano insieme per risolvere il compito, invece di uno solo. Questo tipo di struttura offre empiricamente prestazioni migliori nella maggior parte dei benchmark. Il motivo di queste prestazioni migliori è concettualmente semplice: per molti compiti, piuttosto che usare un sistema "tuttofare", si preferisce specializzare le unità su sottocompiti. In questo caso, avere agenti con set di strumenti e memorie separati permette di ottenere una specializzazione efficiente. Ad esempio, perché riempire la memoria dell'agente che genera codice con tutti i contenuti delle pagine web visitate dall'agente di ricerca web? È meglio tenerli separati.
Si possono facilmente costruire sistemi multi-agente gerarchici con smolagents.
Per farlo, incapsulare l'agente in un oggetto Agente gestito oggetto. Questo oggetto ha bisogno di argomenti agente, nome, e un descrizioneche sarà poi incorporato nel prompt di sistema dell'agente manager per fargli sapere come chiamare questo agente gestito, come facciamo anche per gli strumenti.
Ecco un esempio di creazione di un agente che gestisca uno specifico agente di ricerca web, utilizzando il nostro AnatraDuckGoSearchTool:
Copiato
da smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool, ManagedAgent
model = HfApiModel()
web_agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model)
managed_web_agent = ManagedAgent(
agent=web_agent,
name="web_search",
description="Esegue ricerche sul web per voi. Fornitegli la vostra query come argomento".
)
manager_agent = CodeAgent(
tools=[], model=model, managed_agents=[managed_web_agent]
)
manager_agent.run("Chi è l'amministratore delegato di Hugging Face?")Per un esempio approfondito di un'efficiente implementazione multi-agente, vedere come abbiamo spinto il nostro sistema multi-agente in cima alla classifica di GAIA.
Parlate con il vostro agente e visualizzate i suoi pensieri in un'interfaccia Gradio di grande impatto. #
È possibile utilizzare GradioUI per inviare in modo interattivo compiti all'agente e osservare il suo processo di pensiero ed esecuzione; ecco un esempio:
Copiato
da smolagents importiamo (
load_tool,
CodeAgent,
HfApiModel,
GradioUI
)
# Strumento di importazione da Hub
strumento_di_generazione_immagine = load_tool("m-ric/text-to-image")
modello = HfApiModel(model_id)
# Inizializzare l'agente con lo strumento di generazione delle immagini
agent = CodeAgent(tools=[image_generation_tool], model=modello)
GradioUI(agent).launch()Sotto il cofano, quando l'utente digita una nuova risposta, l'agente viene lanciato con agent.run(user_request, reset=False). Il reset=False significa che la memoria dell'agente non viene svuotata prima di lanciare questo nuovo task, lasciando che la conversazione continui.
È inoltre possibile utilizzare questo reset=False per mantenere la conversazione in qualsiasi altra applicazione agenziale.
Le prossime tappe #
Per un utilizzo più approfondito, si consiglia di consultare le nostre esercitazioni:
Italian 
English 
Russian 
French 
German 
Chinese (China) 
Chinese (Taiwan) 
Japanese 
Korean 
Spanish 
Thai 
Hindi 
Arabic 
Vietnamese