- \n
- Strumenti<\/a>\n
- \n
- Che cos'\u00e8 uno strumento e come si costruisce?<\/a><\/li>\n\n\n\n
- Condividete il vostro strumento all'Hub<\/a><\/li>\n\n\n\n
- Importare uno spazio come strumento<\/a><\/li>\n\n\n\n
- Utilizzare gli strumenti di LangChain<\/a><\/li>\n\n\n\n
- Gestire la cassetta degli attrezzi dell'agente<\/a><\/li>\n\n\n\n
- Utilizzare una collezione di strumenti<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n
<\/a>Che cos'\u00e8 uno strumento e come si costruisce?<\/h3>\n\n\n\n
Uno strumento \u00e8 per lo pi\u00f9 una funzione che un LLM pu\u00f2 utilizzare in un sistema agenziale.<\/p>\n\n\n\n
Ma per utilizzarlo, \u00e8 necessario fornire all'LLM un'API: nome, descrizione dello strumento, tipi e descrizioni di input, tipo di output.<\/p>\n\n\n\n
Quindi non pu\u00f2 essere solo una funzione. Dovrebbe essere una classe.<\/p>\n\n\n\n
In sostanza, lo strumento \u00e8 una classe che avvolge una funzione con metadati che aiutano il LLM a capire come usarla.<\/p>\n\n\n\n
Ecco come si presenta:<\/p>\n\n\n\n
Copiato<\/p>\n\n\n\n
da smolagents importiamo Tool\n\nclasse HFModelDownloadsTool(Tool):\n name = \"model_download_counter\"\n description = \"\"\"\n Questo strumento restituisce il modello pi\u00f9 scaricato di una determinata attivit\u00e0 sull'hub Hugging Face.\n Restituisce il nome del punto di controllo.\"\"\"\n input = {\n \"task\": \n \"type\": \"string\",\n \"description\": \"la categoria dell'attivit\u00e0 (come la classificazione del testo, la stima della profondit\u00e0, ecc)\",\n }\n }\n output_type = \"string\"\n\n def forward(self, task: str):\n da huggingface_hub import list_models\n\n model = next(iter(list_models(filter=task, sort=\"downloads\", direction=-1))\n return model.id\n\nmodel_downloads_tool = HFModelDownloadsTool()<\/pre>\n\n\n\nLe sottoclassi degli strumenti personalizzati\u00a0Strumento<\/a>\u00a0per ereditare metodi utili. La classe figlio definisce anche:<\/p>\n\n\n\n
- \n
- Un attributo\u00a0
nome<\/code>che corrisponde al nome dello strumento stesso. Il nome di solito descrive le funzioni dello strumento. Poich\u00e9 il codice restituisce il modello con il maggior numero di download per un'attivit\u00e0, chiamiamolo\u00a0contatore_di_download_del_modello<\/code>.<\/li>\n\n\n\n- Un attributo\u00a0
descrizione<\/code>\u00a0\u00e8 usato per riempire il prompt di sistema dell'agente.<\/li>\n\n\n\n- Un\u00a0
ingressi<\/code>\u00a0che \u00e8 un dizionario con chiavi\u00a0\"tipo\"<\/code>\u00a0e\u00a0\"descrizione\"<\/code>. Contiene informazioni che aiutano l'interprete Python a fare scelte oculate sull'input.<\/li>\n\n\n\n- Un\u00a0
tipo_uscita<\/code>\u00a0che specifica il tipo di output. I tipi per entrambi\u00a0ingressi<\/code>\u00a0e\u00a0tipo_uscita<\/code>\u00a0dovrebbe essere\u00a0Formati pidocchiosi<\/a>, possono essere uno di questi:\u00a0~TIPOLOGIE_AUTORIZZATE()<\/code>.<\/li>\n\n\n\n- A\u00a0
in avanti<\/code>\u00a0che contiene il codice di inferenza da eseguire.<\/li>\n<\/ul>\n\n\n\nE questo \u00e8 tutto ci\u00f2 che serve per essere utilizzato in un agente!<\/p>\n\n\n\n
C'\u00e8 un altro modo per costruire uno strumento. Nel\u00a0visita guidata<\/a>abbiamo implementato uno strumento che utilizza il metodo\u00a0
@strumento<\/code>\u00a0decoratore. Il\u00a0strumento()<\/a>\u00a0\u00e8 il modo consigliato per definire strumenti semplici, ma a volte \u00e8 necessario qualcosa di pi\u00f9: usare diversi metodi in una classe per una maggiore chiarezza o usare attributi aggiuntivi della classe.<\/p>\n\n\n\nIn questo caso, si pu\u00f2 costruire il proprio strumento sottoclassificando\u00a0Strumento<\/a>\u00a0come descritto sopra.<\/p>\n\n\n\n
<\/a>Condividete il vostro strumento all'Hub<\/h3>\n\n\n\n
\u00c8 possibile condividere lo strumento personalizzato con l'Hub chiamando\u00a0push_to_hub()<\/a>\u00a0sullo strumento. Assicurarsi di aver creato un repository sull'Hub e di utilizzare un token con accesso in lettura.<\/p>\n\n\n\n
Copiato<\/p>\n\n\n\n
model_downloads_tool.push_to_hub(\"{your_username}\/hf-model-downloads\", token=\"\")<\/pre>\n\n\n\nAffinch\u00e9 il push to Hub funzioni, lo strumento deve rispettare alcune regole:<\/p>\n\n\n\n
- \n
- Tutti i metodi sono autosufficienti, ad esempio utilizzano variabili che provengono dai loro argomenti.<\/li>\n\n\n\n
- Come da punto precedente,\u00a0tutte le importazioni devono essere definite direttamente all'interno delle funzioni dello strumento<\/strong>altrimenti si otterr\u00e0 un errore quando si cercher\u00e0 di richiamare il file\u00a0salvare()<\/a>\u00a0o\u00a0push_to_hub()<\/a>\u00a0con lo strumento personalizzato.<\/li>\n\n\n\n
- Se si sottoclasse la classe\u00a0
__init__<\/code>\u00a0si pu\u00f2 dare al metodo un argomento diverso da\u00a0s\u00e9<\/code>. Questo perch\u00e9 gli argomenti impostati durante l'inizializzazione di un'istanza di uno strumento specifico sono difficili da tracciare, il che impedisce di condividerli correttamente con l'hub. E comunque, l'idea di creare una classe specifica \u00e8 che si possono gi\u00e0 impostare gli attributi della classe per qualsiasi cosa sia necessario codificare (basta impostare\u00a0tua_variabile=(...)<\/code>\u00a0direttamente sotto il\u00a0classe YourTool(Tool):<\/code>\u00a0). E naturalmente si pu\u00f2 sempre creare un attributo di classe in qualsiasi punto del codice, assegnando qualcosa a\u00a0self.your_variable<\/code>.<\/li>\n<\/ul>\n\n\n\nUna volta che lo strumento \u00e8 stato inviato a Hub, \u00e8 possibile visualizzarlo.\u00a0Qui<\/a>\u00a0\u00e8 il\u00a0
strumento_modello_downloads<\/code>\u00a0che ho spinto. Ha una bella interfaccia gradio.<\/p>\n\n\n\nQuando ci si immerge nei file dello strumento, si scopre che tutta la logica dello strumento si trova sotto la voce\u00a0strumento.py<\/a>. \u00c8 qui che si pu\u00f2 ispezionare uno strumento condiviso da qualcun altro.<\/p>\n\n\n\n
Poi si pu\u00f2 caricare lo strumento con\u00a0load_tool()<\/a>\u00a0o crearlo con\u00a0da_hub()<\/a>\u00a0e passarlo al metodo\u00a0
strumenti<\/code>\u00a0nel proprio agente. Dal momento che l'esecuzione degli strumenti implica l'esecuzione di codice personalizzato, \u00e8 necessario assicurarsi di fidarsi del repository, quindi \u00e8 necessario passare il parametro\u00a0trust_remote_code=True<\/code>\u00a0per caricare uno strumento dall'Hub.<\/p>\n\n\n\nCopiato<\/p>\n\n\n\n
da smolagents import load_tool, CodeAgent\n\nmodel_download_tool = load_tool(\n \"{your_username}\/hf-model-downloads\",\n trust_remote_code=True\n)<\/pre>\n\n\n\n<\/a>Importare uno spazio come strumento<\/h3>\n\n\n\n
\u00c8 possibile importare direttamente uno spazio dall'Hub come strumento utilizzando il comando\u00a0Strumento.from_space()<\/a>\u00a0metodo!<\/p>\n\n\n\n
\u00c8 sufficiente fornire l'id dello spazio sull'Hub, il suo nome e una descrizione che aiuti l'agente a capire cosa fa lo strumento. Sotto il cofano, questo utilizzer\u00e0\u00a0
gradio-client<\/code><\/a>\u00a0per chiamare lo Spazio.<\/p>\n\n\n\nPer esempio, importiamo il file\u00a0FLUX.1-dev<\/a>\u00a0spazio dall'Hub e utilizzarlo per generare un'immagine.<\/p>\n\n\n\n
Copiato<\/p>\n\n\n\n
strumento_di_generazione_immagine = Tool.from_space(\n \"black-forest-labs\/FLUX.1-schnell\",\n name=\"image_generator\",\n description=\"Genera un'immagine da un prompt\"\n)\n\nstrumento_di_generazione_immagine(\"Una spiaggia assolata\")<\/pre>\n\n\n\n
E voil\u00e0, ecco la vostra immagine! \ud83c\udfd6\ufe0f<\/p>\n\n\n\n
![\"\"](\"https:\/\/smolagents.org\/wp-content\/uploads\/2025\/01\/sunny_beach.webp\")
<\/figure>\n\n\n\nQuindi \u00e8 possibile utilizzare questo strumento come qualsiasi altro strumento. Ad esempio, miglioriamo il prompt
un coniglio che indossa una tuta spaziale<\/code> e generarne un'immagine.<\/p>\n\n\n\nCopiato<\/p>\n\n\n\n
da smolagents import CodeAgent, HfApiModel\n\nmodel = HfApiModel(\"Qwen\/Qwen2.5-Coder-32B-Instruct\")\nagent = CodeAgent(tools=[image_generation_tool], model=model)\n\nagent.run(\n \"Migliora questo prompt, poi genera un'immagine di esso\", prompt='Un coniglio che indossa una tuta spaziale'\n)<\/pre>\n\n\n\n
Copiato<\/p>\n\n\n\n
=== Pensieri dell'agente:\nimproved_prompt potrebbe essere \"Un coniglio in tuta spaziale blu brillante, sulla superficie della luna, sotto un tramonto arancione brillante, con la Terra visibile sullo sfondo\".\n\nOra che ho migliorato il prompt, posso usare lo strumento generatore di immagini per generare un'immagine basata su questo prompt.\n>>> L'agente sta eseguendo il codice sottostante:\nimage = image_generator(prompt=\"Un coniglio in tuta spaziale blu brillante, sulla superficie della luna, sotto un tramonto arancione brillante, con la Terra visibile sullo sfondo\")\nrisposta_finale(immagine)<\/pre>\n\n\n\n
![\"\"](\"https:\/\/smolagents.org\/wp-content\/uploads\/2025\/01\/rabbit_spacesuit_flux.webp\")
<\/figure>\n\n\n\nQuanto \u00e8 bello questo? \ud83e\udd29<\/p>\n\n\n\n
<\/a>Utilizzare gli strumenti di LangChain<\/h3>\n\n\n\n
Amiamo Langchain e pensiamo che abbia una suite di strumenti molto interessante. Per importare uno strumento da LangChain, usare il comando
da_langchain()<\/code> metodo.<\/p>\n\n\n\nEcco come si pu\u00f2 utilizzare per ricreare il risultato della ricerca dell'introduzione utilizzando uno strumento di ricerca web LangChain. Questo strumento avr\u00e0 bisogno di
pip installare langchain google-search-results -q<\/code> per funzionare correttamente.<\/p>\n\n\n\nCopiato<\/p>\n\n\n\n
da langchain.agents import load_tools\n\nsearch_tool = Tool.from_langchain(load_tools([\"serpapi\"])[0])\n\nagent = CodeAgent(tools=[search_tool], model=model)\n\nagent.run(\"Quanti blocchi in pi\u00f9 (indicati anche come strati) ci sono nel codificatore BERT di base rispetto al codificatore dell'architettura proposta in Attention is All You Need?\")<\/pre>\n\n\n\n
<\/a>Gestire la cassetta degli attrezzi dell'agente<\/h3>\n\n\n\n
\u00c8 possibile gestire la cassetta degli attrezzi di un agente aggiungendo o sostituendo uno strumento nell'attributo
agente.strumenti<\/code>, poich\u00e9 si tratta di un dizionario standard.<\/p>\n\n\n\nAggiungiamo il
strumento_di_download_del_modello<\/code> a un agente esistente inizializzato solo con la casella degli strumenti predefinita.<\/p>\n\n\n\nCopiato<\/p>\n\n\n\n
da smolagents importare HfApiModel\n\nmodel = HfApiModel(\"Qwen\/Qwen2.5-Coder-32B-Instruct\")\n\nagent = CodeAgent(tools=[], model=model, add_base_tools=True)\nagent.tools[model_download_tool.name] = model_download_tool<\/pre>\n\n\n\n
Ora possiamo sfruttare il nuovo strumento:<\/p>\n\n\n\n
Copiato<\/p>\n\n\n\n
agent.run(\n \"Puoi darmi il nome del modello che ha il maggior numero di download nell'attivit\u00e0 'text-to-video' sull'Hub Hugging Face ma invertendo le lettere?\".\n)<\/pre>\n\n\n\n
Attenzione a non aggiungere troppi strumenti a un agente: questo pu\u00f2 sovraccaricare i motori LLM pi\u00f9 deboli.<\/p>\n\n\n\n
<\/a>Utilizzare una collezione di strumenti<\/h3>\n\n\n\n
\u00c8 possibile sfruttare le raccolte di strumenti utilizzando l'oggetto ToolCollection, con lo slug della raccolta che si desidera utilizzare. Quindi passarle come elenco per inizializzare l'agente e iniziare a usarle!<\/p>\n\n\n\n
Copiato<\/p>\n\n\n\n
da smolagents import ToolCollection, CodeAgent\n\nimage_tool_collection = ToolCollection(\n collection_slug=\"huggingface-tools\/diffusion-tools-6630bb19a942c2306a2cdb6f\",\n token=\"\"\n)\nagent = CodeAgent(tools=[*image_tool_collection.tools], model=model, add_base_tools=True)\n\nagent.run(\"Per favore, disegnami un'immagine di fiumi e laghi\").<\/pre>\n\n\n\n
Per velocizzare l'avvio, gli strumenti vengono caricati solo se chiamati dall'agente.<\/p>","protected":false},"excerpt":{"rendered":"
Here, we\u2019re going to see advanced tool usage. If you\u2019re new to building agents, make sure to first read the\u00a0intro to agents\u00a0and the\u00a0guided tour of smolagents. What is a tool, and how to build one? A tool is mostly a function that an LLM can use in an agentic system. But to use it, the…<\/p>","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"_kadence_starter_templates_imported_post":false,"_kad_post_transparent":"","_kad_post_title":"","_kad_post_layout":"","_kad_post_sidebar_id":"","_kad_post_content_style":"","_kad_post_vertical_padding":"","_kad_post_feature":"","_kad_post_feature_position":"","_kad_post_header":false,"_kad_post_footer":false,"footnotes":""},"doc_category":[8],"doc_tag":[],"class_list":["post-591","docs","type-docs","status-publish","hentry","doc_category-tutorials"],"year_month":"2026-04","word_count":1431,"total_views":"5903","reactions":{"happy":"0","normal":"0","sad":"0"},"author_info":{"name":"smolagents","author_nicename":"wd-gstargmail-com","author_url":"https:\/\/smolagents.org\/it\/author\/wd-gstargmail-com\/"},"doc_category_info":[{"term_name":"Tutorials","term_url":"https:\/\/smolagents.org\/it\/docs-category\/tutorials\/"}],"doc_tag_info":[],"_links":{"self":[{"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/docs\/591","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/comments?post=591"}],"version-history":[{"count":1,"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/docs\/591\/revisions"}],"predecessor-version":[{"id":594,"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/docs\/591\/revisions\/594"}],"wp:attachment":[{"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/media?parent=591"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/doc_category?post=591"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/doc_tag?post=591"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
- Se si sottoclasse la classe\u00a0
- Un attributo\u00a0
- Condividete il vostro strumento all'Hub<\/a><\/li>\n\n\n\n
- Che cos'\u00e8 uno strumento e come si costruisce?<\/a><\/li>\n\n\n\n