{"id":589,"date":"2025-01-11T15:17:25","date_gmt":"2025-01-11T15:17:25","guid":{"rendered":"https:\/\/smolagents.org\/?post_type=docs&#038;p=589"},"modified":"2025-01-11T15:41:32","modified_gmt":"2025-01-11T15:41:32","password":"","slug":"building-good-smolagents","status":"publish","type":"docs","link":"https:\/\/smolagents.org\/it\/docs\/building-good-smolagents\/","title":{"rendered":"Costruire buoni Smolagent"},"content":{"rendered":"<p>C'\u00e8 una grande differenza tra costruire un agente che funziona e uno che non funziona. Come possiamo costruire agenti che rientrano in quest'ultima categoria? In questa guida vedremo le migliori pratiche per la costruzione di agenti.<\/p>\n\n\n\n<p>Se siete alle prime armi con la costruzione di agenti, assicuratevi di leggere prima la sezione\u00a0<a href=\"https:\/\/huggingface.co\/docs\/smolagents\/conceptual_guides\/intro_agents\" target=\"_blank\" rel=\"noopener\">introduzione<\/a><a href=\"https:\/\/huggingface.co\/docs\/smolagents\/conceptual_guides\/intro_agents\" target=\"_blank\" rel=\"noreferrer noopener nofollow\"> <\/a><a href=\"https:\/\/huggingface.co\/docs\/smolagents\/conceptual_guides\/intro_agents\" target=\"_blank\" rel=\"noopener\">agli agenti<\/a>\u00a0e il\u00a0<a href=\"https:\/\/huggingface.co\/docs\/smolagents\/guided_tour\" target=\"_blank\" rel=\"noreferrer noopener nofollow\">visita guidata agli smolagent<\/a>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\"><a href=\"https:\/\/huggingface.co\/docs\/smolagents\/tutorials\/building_good_agents#the-best-agentic-systems-are-the-simplest-simplify-the-workflow-as-much-as-you-can\" target=\"_blank\" rel=\"noopener\"><\/a>I migliori sistemi agenziali sono i pi\u00f9 semplici: semplificate il pi\u00f9 possibile il flusso di lavoro.<\/h3>\n\n\n\n<p>Dare a un LLM una certa autonomia nel flusso di lavoro comporta un certo rischio di errori.<\/p>\n\n\n\n<p>I sistemi agenziali ben programmati hanno comunque buoni meccanismi di registrazione degli errori e di riprova, in modo che il motore LLM abbia la possibilit\u00e0 di autocorreggere il proprio errore. Ma per ridurre al massimo il rischio di errore di LLM, \u00e8 necessario semplificare il flusso di lavoro!<\/p>\n\n\n\n<p>Rivediamo l'esempio di [intro_agents]: un bot che risponde alle domande degli utenti per una compagnia di viaggi per surfisti. Invece di lasciare che l'agente faccia due diverse chiamate alle \"API della distanza di viaggio\" e alle \"API del meteo\" ogni volta che gli viene chiesto un nuovo posto per il surf, si potrebbe creare uno strumento unificato \"return_spot_information\", una funzione che chiama entrambe le API in una volta sola e restituisce all'utente i loro risultati concatenati.<\/p>\n\n\n\n<p>In questo modo si riducono i costi, la latenza e il rischio di errori!<\/p>\n\n\n\n<p>La linea guida principale \u00e8: Ridurre il pi\u00f9 possibile il numero di chiamate LLM.<\/p>\n\n\n\n<p>Questo porta ad alcune considerazioni:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Quando \u00e8 possibile, raggruppare 2 strumenti in uno, come nel nostro esempio delle due API.<\/li>\n\n\n\n<li>Quando possibile, la logica deve basarsi su funzioni deterministiche piuttosto che su decisioni agite.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\"><a href=\"https:\/\/huggingface.co\/docs\/smolagents\/tutorials\/building_good_agents#improve-the-information-flow-to-the-llm-engine\" target=\"_blank\" rel=\"noopener\"><\/a>Migliorare il flusso di informazioni verso il motore LLM<\/h3>\n\n\n\n<p>Ricordate che il vostro motore LLM \u00e8 come un robot ~intelligente~, inserito in una stanza in cui l'unica comunicazione con il mondo esterno \u00e8 costituita da note passate sotto una porta.<\/p>\n\n\n\n<p>Non sapr\u00e0 nulla di ci\u00f2 che \u00e8 accaduto se non lo si indica esplicitamente nel prompt.<\/p>\n\n\n\n<p>Quindi, per prima cosa, iniziate a rendere il vostro compito molto chiaro! Poich\u00e9 un agente \u00e8 alimentato da un LLM, piccole variazioni nella formulazione del compito potrebbero produrre risultati completamente diversi.<\/p>\n\n\n\n<p>Quindi, migliorare il flusso di informazioni verso il vostro agente nell'uso degli strumenti.<\/p>\n\n\n\n<p>Linee guida particolari da seguire:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Ogni strumento dovrebbe registrare (semplicemente usando\u00a0<code>stampa<\/code>\u00a0all'interno dello strumento\u00a0<code>in avanti<\/code>\u00a0tutto ci\u00f2 che pu\u00f2 essere utile per il motore LLM.\n<ul class=\"wp-block-list\">\n<li>In particolare, la registrazione degli errori di esecuzione degli strumenti sarebbe di grande aiuto!<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<p>Ad esempio, ecco uno strumento che recupera i dati meteo in base alla posizione e alla data:<\/p>\n\n\n\n<p>Innanzitutto, ecco una versione povera:<\/p>\n\n\n\n<p>Copiato<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">importare datetime\nda smolagents importare lo strumento\n\ndef get_weather_report_at_coordinates(coordinate, date_time):\n    <em># Funzione fittizia, restituisce un elenco di [temperatura in \u00b0C, rischio di pioggia su una scala 0-1, altezza delle onde in m].<\/em>\n    ritorno [28.0, 0.35, 0.85]\n\ndef get_coordinates_from_location(location):\n    <em># Restituisce le coordinate fittizie<\/em>\n    ritorno [3.3, -42.0]\n\n@tool\ndef get_weather_api(location: str, date_time: str) -&gt; str:\n    \"\"\"\n    Restituisce il bollettino meteo.\n\n    Args:\n        location: il nome del luogo per il quale si vuole il meteo.\n        data_ora: la data e l'ora per le quali si desidera il rapporto.\n    \"\"\"\n    lon, lat = convert_location_to_coordinates(location)\n    date_time = datetime.strptime(date_time)\n    return str(get_weather_report_alle_coordinate((lon, lat), date_time))<\/pre>\n\n\n\n<p>Perch\u00e9 \u00e8 un male?<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>non c'\u00e8 alcuna precisione sul formato da utilizzare per\u00a0<code>data_ora<\/code><\/li>\n\n\n\n<li>non ci sono dettagli su come debba essere specificata la posizione.<\/li>\n\n\n\n<li>non c'\u00e8 un meccanismo di logging legato a casi di fallimento espliciti, come la posizione che non \u00e8 in un formato corretto o la data_ora che non \u00e8 formattata correttamente.<\/li>\n\n\n\n<li>il formato di uscita \u00e8 difficile da capire<\/li>\n<\/ul>\n\n\n\n<p>Se la chiamata allo strumento fallisce, la traccia degli errori registrata in memoria pu\u00f2 aiutare il LLM a fare il reverse engineering dello strumento per correggere gli errori. Ma perch\u00e9 lasciargli un compito cos\u00ec gravoso?<\/p>\n\n\n\n<p>Un modo migliore per costruire questo strumento sarebbe stato il seguente:<\/p>\n\n\n\n<p>Copiato<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">@tool\ndef get_weather_api(location: str, date_time: str) -&gt; str:\n    \"\"\"\n    Restituisce il bollettino meteo.\n\n    Args:\n        location: il nome del luogo per il quale si desidera il meteo. Dovrebbe essere il nome di un luogo, seguito eventualmente dal nome di una citt\u00e0 e poi di un paese, come \"Anchor Point, Taghazout, Marocco\".\n        date_time: la data e l'ora per cui si desidera il rapporto, formattata come '%m\/%d\/%y %H:%M:%S'.\n    \"\"\"\n    lon, lat = convert_location_to_coordinates(location)\n    try:\n        date_time = datetime.strptime(date_time)\n    except Exception as e:\n        raise ValueError(\"Conversione di `date_time` in formato datetime fallita, assicurarsi di fornire una stringa nel formato '%m\/%d\/%y %H:%M:%S'. Traccia completa:\" + str(e))\n    temperatura_celsius, rischio_pioggia, altezza_onda = get_weather_report_at_coordinates((lon, lat), date_time)\n    return f \"Rapporto meteo per {localit\u00e0}, {data_ora}: La temperatura sar\u00e0 di {temperatura_celsius}\u00b0C, il rischio di pioggia \u00e8 di {rischio_di_pioggia*100:.0f}%, l'altezza dell'onda \u00e8 di {altezza_onda}m\".<\/pre>\n\n\n\n<p>In generale, per alleggerire il carico del vostro LLM, la domanda da porsi \u00e8: \"Quanto sarebbe facile per me, se fossi muto e usassi questo strumento per la prima volta, programmare con questo strumento e correggere i miei stessi errori?\".<\/p>\n\n\n\n<h3 class=\"wp-block-heading\"><a href=\"https:\/\/huggingface.co\/docs\/smolagents\/tutorials\/building_good_agents#give-more-arguments-to-the-agent\" target=\"_blank\" rel=\"noopener\"><\/a>Fornire pi\u00f9 argomenti all'agente<\/h3>\n\n\n\n<p>Per passare all'agente alcuni oggetti aggiuntivi, oltre alla semplice stringa che descrive il compito, si pu\u00f2 usare l'opzione&nbsp;<code>argomenti_aggiuntivi<\/code>&nbsp;per passare qualsiasi tipo di oggetto:<\/p>\n\n\n\n<p>Copiato<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">da smolagents import CodeAgent, HfApiModel\n\nmodel_id = \"meta-llama\/Llama-3.3-70B-Instruct\"\n\nagent = CodeAgent(tools=[], model=HfApiModel(model_id=model_id), add_base_tools=True)\n\nagent.run(\n    \"Perch\u00e9 Mike non conosce molte persone a New York?\",\n    additional_args={\"mp3_sound_file_url\":'https:\/\/huggingface.co\/datasets\/huggingface\/documentation-images\/resolve\/main\/transformers\/recording.mp3'}\n)<\/pre>\n\n\n\n<p>Per esempio, si pu\u00f2 usare questo&nbsp;<code>argomenti_aggiuntivi<\/code>&nbsp;per passare immagini o stringhe che si vuole che l'agente sfrutti.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><a href=\"https:\/\/huggingface.co\/docs\/smolagents\/tutorials\/building_good_agents#how-to-debug-your-agent\" target=\"_blank\" rel=\"noopener\"><\/a>Come eseguire il debug dell'agente<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\"><a href=\"https:\/\/huggingface.co\/docs\/smolagents\/tutorials\/building_good_agents#1-use-a-stronger-llm\" target=\"_blank\" rel=\"noopener\"><\/a>1. Utilizzare un LLM pi\u00f9 forte<\/h3>\n\n\n\n<p>In un flusso di lavoro agenziale, alcuni errori sono errori veri e propri, altri sono colpa del motore LLM che non ragiona correttamente. Per esempio, si consideri questa traccia per un&nbsp;<code>CodiceAgente<\/code>&nbsp;che ho chiesto di creare un'immagine dell'auto:<\/p>\n\n\n\n<p>Copiato<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">==================================================================================================== New task ====================================================================================================\nFammi una foto di un'auto figa\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Nuovo passo \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nL'agente sta eseguendo il codice sottostante: \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nimage_generator(prompt=\"Un'auto sportiva fresca e futuristica con fari a LED, design aerodinamico e colori vivaci, ad alta risoluzione e fotorealistica\")\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nUltimo risultato dello snippet di codice: \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\/var\/folders\/6m\/9b1tts6d5w960j80wbw9tx3m0000gn\/T\/tmpx09qfsdd\/652f0007-3ee9-44e2-94ac-90dae6bb89a4.png\nPasso 1:\n\n- Tempo impiegato: 16,35 secondi\n- Gettoni in ingresso: 1.383\n- Gettoni in uscita: 77\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Nuovo passo \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nL'agente sta eseguendo il codice sottostante: \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nfinal_answer(\"\/var\/folders\/6m\/9b1tts6d5w960j80wbw9tx3m0000gn\/T\/tmpx09qfsdd\/652f0007-3ee9-44e2-94ac-90dae6bb89a4.png\")\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nUscite di stampa:\n\nUltimo output del frammento di codice: \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\/var\/folders\/6m\/9b1tts6d5w960j80wbw9tx3m0000gn\/T\/tmpx09qfsdd\/652f0007-3ee9-44e2-94ac-90dae6bb89a4.png\nRisposta finale:\n\/var\/folders\/6m\/9b1tts6d5w960j80wbw9tx3m0000gn\/T\/tmpx09qfsdd\/652f0007-3ee9-44e2-94ac-90dae6bb89a4.png<\/pre>\n\n\n\n<p>L'utente vede che, invece di un'immagine, gli viene restituito un percorso. Potrebbe sembrare un bug del sistema, ma in realt\u00e0 non \u00e8 il sistema agenziale a causare l'errore: \u00e8 solo che il cervello di LLM ha commesso l'errore di non salvare l'immagine in una variabile. In questo modo non pu\u00f2 accedere nuovamente all'immagine se non sfruttando il percorso che \u00e8 stato registrato durante il salvataggio dell'immagine, quindi restituisce il percorso invece dell'immagine.<\/p>\n\n\n\n<p>Il primo passo per il debug del vostro agente \u00e8 quindi \"Utilizzare un LLM pi\u00f9 potente\". Alternative come&nbsp;<code>Qwen2\/5-72B-Istruzione<\/code>&nbsp;non avrebbe commesso questo errore.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\"><a href=\"https:\/\/huggingface.co\/docs\/smolagents\/tutorials\/building_good_agents#2-provide-more-guidance--more-information\" target=\"_blank\" rel=\"noopener\"><\/a>2. Fornire pi\u00f9 indicazioni\/pi\u00f9 informazioni<\/h3>\n\n\n\n<p>\u00c8 possibile utilizzare anche modelli meno potenti, a patto di guidarli in modo pi\u00f9 efficace.<\/p>\n\n\n\n<p>Mettetevi nei panni del vostro modello: se foste il modello che risolve il compito, fareste fatica con le informazioni a vostra disposizione (dal prompt del sistema + formulazione del compito + descrizione dello strumento)?<\/p>\n\n\n\n<p>Avete bisogno di ulteriori chiarimenti?<\/p>\n\n\n\n<p>Per fornire ulteriori informazioni, si sconsiglia di cambiare subito il prompt di sistema: il prompt di sistema predefinito ha molte regolazioni che non si vogliono sbagliare, a meno che non si capisca molto bene il prompt. I modi migliori per guidare il motore LLM sono:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Se si tratta del compito da risolvere: aggiungete tutti questi dettagli al compito. Il compito potrebbe essere lungo 100 pagine.<\/li>\n\n\n\n<li>Se si tratta di come utilizzare gli strumenti: l'attributo description dei vostri strumenti.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\"><a href=\"https:\/\/huggingface.co\/docs\/smolagents\/tutorials\/building_good_agents#3-change-the-system-prompt-generally-not-advised\" target=\"_blank\" rel=\"noopener\"><\/a>3. Modificare il prompt di sistema (generalmente sconsigliato)<\/h3>\n\n\n\n<p>Se i chiarimenti di cui sopra non sono sufficienti, \u00e8 possibile modificare il prompt di sistema.<\/p>\n\n\n\n<p>Vediamo come funziona. Ad esempio, controlliamo il prompt di sistema predefinito per il comando\u00a0<a href=\"https:\/\/huggingface.co\/docs\/smolagents\/v1.2.2\/en\/reference\/agents#smolagents.CodeAgent\" target=\"_blank\" rel=\"noreferrer noopener nofollow\">CodiceAgente<\/a>\u00a0(la versione seguente \u00e8 abbreviata saltando gli esempi a colpo zero).<\/p>\n\n\n\n<p>Copiato<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">print(agent.system_prompt_template)<\/pre>\n\n\n\n<p>Ecco cosa si ottiene:<\/p>\n\n\n\n<p>Copiato<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">Sei un assistente esperto in grado di risolvere qualsiasi compito utilizzando i blob di codice. Vi verr\u00e0 assegnato un compito da risolvere al meglio.\nPer farlo, vi \u00e8 stato dato accesso a un elenco di strumenti: questi strumenti sono fondamentalmente funzioni Python che potete richiamare con il codice.\nPer risolvere il compito, dovete pianificare una serie di passi, in un ciclo di sequenze \"Pensiero:\", \"Codice:\" e \"Osservazione:\".\n\nIn ogni fase, nella sequenza 'Pensiero:', dovrete innanzitutto spiegare il vostro ragionamento per risolvere il compito e gli strumenti che volete utilizzare.\nPoi, nella sequenza \"Codice:\", si deve scrivere il codice in Python semplice. La sequenza di codice deve terminare con la sequenza ''.\nDurante ogni fase intermedia, si pu\u00f2 usare 'print()' per salvare qualsiasi informazione importante di cui si avr\u00e0 bisogno.\nQuesti output di stampa appariranno poi nel campo \"Osservazione:\", che sar\u00e0 disponibile come input per il passo successivo.\nAlla fine si dovr\u00e0 restituire una risposta finale utilizzando lo strumento `risposta_finale`.\n\nEcco alcuni esempi che utilizzano strumenti fittizi:\n---\n{esempi}\n\nGli esempi precedenti utilizzano strumenti fittizi che potrebbero non esistere per voi. Oltre a eseguire calcoli negli snippet di codice Python che create, avete accesso solo a questi strumenti:\n\n{{descrizioni_strumenti}}\n\n{{descrizioni_agenti_gestiti}}\n\nEcco le regole da seguire sempre per risolvere il vostro compito:\n1. Fornire sempre una sequenza 'Thought:' e una sequenza 'Code:\\n``py' che termina con la sequenza '```', altrimenti si fallir\u00e0.\n2. Utilizzate solo le variabili che avete definito!\n3. Utilizzate sempre gli argomenti giusti per gli strumenti. NON passate gli argomenti come dict, come in \"answer = wiki({'query': \"Qual \u00e8 il posto dove vive James Bond?\"})\", ma usate direttamente gli argomenti come in \"answer = wiki(query=\"Qual \u00e8 il posto dove vive James Bond?\")\".\n4. Fate attenzione a non concatenare troppe chiamate sequenziali allo strumento nello stesso blocco di codice, soprattutto quando il formato dell'output \u00e8 imprevedibile. Per esempio, una chiamata a search ha un formato di ritorno imprevedibile, quindi non bisogna avere un'altra chiamata a uno strumento che dipenda dal suo output nello stesso blocco: piuttosto, si devono produrre i risultati con print() per utilizzarli nel blocco successivo.\n5. Richiamare uno strumento solo quando \u00e8 necessario e non ripetere mai una chiamata a uno strumento che \u00e8 stata fatta in precedenza con gli stessi parametri.\n6. Non nominare una nuova variabile con lo stesso nome di uno strumento: ad esempio, non nominare una variabile \"final_answer\".\n7. Non creare mai variabili fittizie nel nostro codice, perch\u00e9 la presenza di queste nei log potrebbe farvi perdere di vista le vere variabili.\n8. \u00c8 possibile utilizzare importazioni nel codice, ma solo dal seguente elenco di moduli: {{importazioni_autorizzate}}.\n9. Lo stato persiste tra le esecuzioni del codice: quindi, se in un passaggio si sono create variabili o importati moduli, questi persistono tutti.\n10. Non arrendetevi! Siete incaricati di risolvere il compito, non di fornire indicazioni per risolverlo.\n\nOra iniziate! Se risolverete il compito correttamente, riceverete una ricompensa di $1.000.000.<\/pre>\n\n\n\n<p>Come si pu\u00f2 vedere, ci sono segnaposti come&nbsp;<code>\"{{tool_descriptions}}\"<\/code>: saranno utilizzati all'inizializzazione dell'agente per inserire alcune descrizioni generate automaticamente degli strumenti o degli agenti gestiti.<\/p>\n\n\n\n<p>Quindi, mentre \u00e8 possibile sovrascrivere questo modello di prompt di sistema passando il prompt personalizzato come parametro al metodo&nbsp;<code>prompt_di_sistema<\/code>&nbsp;il nuovo prompt di sistema deve contenere i seguenti segnaposto:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>\"{{tool_descriptions}}\"<\/code>\u00a0per inserire le descrizioni degli strumenti.<\/li>\n\n\n\n<li><code>\"{{managed_agents_description}}\"<\/code>\u00a0per inserire la descrizione degli agenti gestiti, se ce ne sono.<\/li>\n\n\n\n<li>Per\u00a0<code>CodiceAgente<\/code>\u00a0solo:\u00a0<code>\"{{authorized_imports}}\"<\/code>\u00a0per inserire l'elenco delle importazioni autorizzate.<\/li>\n<\/ul>\n\n\n\n<p>Quindi \u00e8 possibile modificare il prompt di sistema come segue:<\/p>\n\n\n\n<p>Copiato<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">da smolagents.prompts import CODE_SYSTEM_PROMPT\n\nmodified_system_prompt = CODE_SYSTEM_PROMPT + \"\\nEcco a voi!\" <em># Modificare il prompt di sistema qui<\/em>\n\nagent = CodeAgent(\n    tools=[],\n    model=HfApiModel(),\n    system_prompt=modified_system_prompt\n)<\/pre>\n\n\n\n<p>Questo funziona anche con l'opzione\u00a0<a href=\"https:\/\/huggingface.co\/docs\/smolagents\/v1.2.2\/en\/reference\/agents#smolagents.ToolCallingAgent\" target=\"_blank\" rel=\"noreferrer noopener nofollow\">Agente di chiamata dello strumento<\/a>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\"><a href=\"https:\/\/huggingface.co\/docs\/smolagents\/tutorials\/building_good_agents#4-extra-planning\" target=\"_blank\" rel=\"noopener\"><\/a>4. Pianificazione extra<\/h3>\n\n\n\n<p>Forniamo un modello per una fase di pianificazione supplementare, che un agente pu\u00f2 eseguire regolarmente tra le normali fasi di azione. In questa fase non c'\u00e8 una chiamata allo strumento, ma viene semplicemente chiesto all'LLM di aggiornare un elenco di fatti che conosce e di riflettere su quali passi dovrebbe compiere successivamente in base a tali fatti.<\/p>\n\n\n\n<p>Copiato<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">da smolagents import load_tool, CodeAgent, HfApiModel, DuckDuckGoSearchTool\nda dotenv importare load_dotenv\n\nload_dotenv()\n\n<em># Strumento di importazione da Hub<\/em>\nimage_generation_tool = load_tool(\"m-ric\/text-to-image\", trust_remote_code=True)\n\nstrumento di ricerca = DuckDuckGoSearchTool()\n\nagent = CodeAgent(\n    tools=[search_tool],\n    model=HfApiModel(\"Qwen\/Qwen2.5-72B-Instruct\"),\n    intervallo_di_pianificazione=3 <em># Qui si attiva la pianificazione!<\/em>\n)\n\n<em># Esegui!<\/em>\nrisultato = agent.run(\n    \"Quanto tempo impiegherebbe un ghepardo a tutta velocit\u00e0 per percorrere la lunghezza di Pont Alexandre III?\",\n)<\/pre>","protected":false},"excerpt":{"rendered":"<p>There\u2019s a world of difference between building an agent that works and one that doesn\u2019t. How can we build agents that fall into the latter category? In this guide, we\u2019re going to see best practices for building agents. If you\u2019re new to building agents, make sure to first read the\u00a0intro to agents\u00a0and the\u00a0guided tour of&#8230;<\/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-589","docs","type-docs","status-publish","hentry","doc_category-tutorials"],"year_month":"2026-04","word_count":2268,"total_views":"6122","reactions":{"happy":"2","normal":"1","sad":"1"},"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\/589","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=589"}],"version-history":[{"count":1,"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/docs\/589\/revisions"}],"predecessor-version":[{"id":590,"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/docs\/589\/revisions\/590"}],"wp:attachment":[{"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/media?parent=589"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/doc_category?post=589"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/smolagents.org\/it\/wp-json\/wp\/v2\/doc_tag?post=589"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}