Agenti AI con smolagents: quando conviene farli agire in Python

Per creare agenti AI in Python, smolagents è una scelta adatta quando occorre combinare strumenti e calcoli in modo dinamico e si può offrire al codice un ambiente di esecuzione controllato. Hugging Face mette a disposizione 2 classi di agenti, CodeAgent e ToolCallingAgent: la differenza sta nel modo in cui il modello esprime l'azione successiva, con codice Python o con una chiamata strutturata a uno strumento. Un'architettura essenziale aiuta a risolvere problemi ben delimitati, ma la gestione dei workflow persistenti, dei permessi e dell'isolamento resta a carico di chi sviluppa.

Contenuti verificati sulla documentazione online di Hugging Face, LangChain e OpenAI il 31 ottobre 2026. Le indicazioni che seguono mettono a confronto la composizione delle azioni, il controllo dei workflow e i confini di esecuzione. Sono valutazioni architetturali, non benchmark delle prestazioni.

Agenti AI con smolagents: che ruolo ha Python?

smolagents è la libreria Python open source di Hugging Face per creare agenti le cui azioni possono essere codice eseguibile. Un agente segue un ciclo guidato dal modello: sceglie un'azione, ne osserva l'esito e decide come proseguire. CodeAgent esprime l'azione in Python; ToolCallingAgent usa chiamate strutturate agli strumenti. Entrambi ricevono un modello e un insieme di strumenti. Riferimento degli agenti Hugging Face.

Si può immaginare CodeAgent come un ricercatore autorizzato a scrivere un breve script tra un'osservazione e l'altra. Può interrogare uno strumento consentito per ottenere dei record, trasformare i dati restituiti e calcolare una risposta. Chi sviluppa definisce capacità e vincoli; il modello costruisce parte della logica che li collega.

È un ruolo diverso da quello di un assistente che consegna un file di codice da revisionare. Qui il codice generato è il mezzo con cui l'agente compie la sua prossima azione.

Per scegliere, conviene chiedersi quale parte dell'applicazione abbia bisogno di flessibilità:

Le ultime due righe riassumono gli aspetti su cui si concentra la documentazione di LangGraph e di OpenAI Agents SDK, senza implicare che queste capacità siano esclusive. La scelta dipende dal punto in cui si vuole che il framework dia struttura all'applicazione.

CodeAgent di smolagents: il modello compone le azioni

CodeAgent ha senso quando il lavoro intermedio si esprime più facilmente in Python che con un elenco fisso di chiamate. Hugging Face indica tra i suoi punti di forza cicli, condizioni e combinazioni di strumenti, ricordando però che occorre gestire errori di sintassi, eccezioni e comportamenti inattesi. Visita guidata.

Si pensi a uno sviluppatore che indaga su incongruenze nei record di inventario. Uno strumento di consultazione in sola lettura restituisce i record candidati. Prima di decidere quali richiedano un'ulteriore verifica, l'agente potrebbe dover normalizzare i nomi, raggruppare le voci simili e sommare i valori di un campo. Python si presta bene a queste operazioni intermedie.

Il risultato dell'esecuzione fornisce elementi per la decisione successiva del modello. Un calcolo fallito è un'osservazione a cui l'agente può reagire, non la prova che riuscirà a correggersi.

ToolCallingAgent: azioni entro un insieme definito

ToolCallingAgent è il punto di partenza più adatto quando le operazioni hanno già contratti chiari. Emette chiamate JSON strutturate, con nomi degli strumenti e argomenti, anziché generare azioni in Python. Il confronto di Hugging Face.

A un assistente per il supporto che consulta un ordine e recupera una policy potrebbe bastare questo. Le trasformazioni prevedibili possono restare nel normale codice applicativo. Introdurre Python generato in un workflow già descrivibile con funzioni ben definite aggiunge una possibilità di errore senza un beneficio evidente.

Anche le chiamate strutturate richiedono autorizzazione. Una richiesta di annullamento formalmente corretta può essere l'azione sbagliata per quel cliente. Lo schema comunica al programma che cosa è stato richiesto; spetta all'applicazione stabilire se sia consentito.

Strumenti e modelli: due scelte indipendenti

Conviene limitare gli strumenti disponibili e scegliere il modello separatamente. È questo il vantaggio pratico della separazione proposta da smolagents: si può cambiare il modo in cui l'agente ragiona senza ridefinire ogni capacità operativa.

Uno strumento è una funzione con un contratto utilizzabile

Uno strumento di smolagents racchiude una funzione e ne specifica nome, descrizione, metadati degli input e tipo di output. Il decoratore @tool è adatto a funzioni semplici, con annotazioni di tipo e una docstring informativa. Per strumenti più articolati, si può creare una sottoclasse di Tool e inserire la logica di esecuzione in forward. Guida agli strumenti.

Per un assistente di inventario, è preferibile una capacità come «cercare record nel catalogo consentito» all'accesso illimitato al database. I controlli sul tenant, le restrizioni sulle query e i limiti delle risposte vanno implementati nello strumento. Un prompt convincente non può sostituirli.

Gli strumenti possono arrivare anche da Model Context Protocol, o MCP, un'interfaccia standard per esporre strumenti alle applicazioni basate su modelli, oppure da adattatori per gli strumenti LangChain e per Hugging Face Spaces. Riutilizzare uno strumento non significa averne accertato l'affidabilità. Hugging Face richiede esplicitamente trust_remote_code=True per caricare gli strumenti dell'Hub, perché eseguono codice personalizzato. Documentazione sull'integrazione e sul caricamento degli strumenti.

È quindi una decisione che richiede una revisione del codice. Prima di rendere lo strumento disponibile a un agente, occorre esaminarne l'implementazione e le dipendenze.

Il backend del modello non determina la sandbox

Il riferimento attuale dei modelli documenta diverse possibilità:

• InferenceClientModel si collega tramite Hugging Face Inference Providers.
• LiteLLMModel usa il livello di integrazione dei provider di LiteLLM.
• TransformersModel esegue un modello Transformers in locale.
• OpenAIModel si collega a un server di modelli compatibile con OpenAI.

La visita guidata tratta anche Ollama per l'inferenza locale. Sono alternative per il backend: non garantiscono che tutti i modelli siano altrettanto capaci di generare codice o scegliere gli strumenti.

Occorre distinguere due domande: dove viene eseguito il modello e dove viene eseguito il Python che genera? Un modello ospitato su un servizio remoto può pilotare un executor Docker. Un modello locale può comunque generare azioni non sicure. Portare l'inferenza sulla propria macchina non crea un confine di isolamento per l'esecuzione.

Per rendere il comportamento riproducibile, dopo la dimostrazione iniziale conviene configurare il modello in modo esplicito. Hugging Face segnala che il modello predefinito di InferenceClientModel può cambiare. Configurazione del modello.

Un piccolo esempio pratico dalla documentazione

Il calcolo proposto nella documentazione aiuta a capire il percorso di esecuzione prima di aggiungere strumenti. L'esempio introduttivo di Hugging Face chiede di sommare i numeri da 1 a 10, senza strumenti a disposizione. La versione seguente mantiene lo stesso compito e aggiunge l'uso del context manager Docker descritto nella guida alle sandbox. Esempio originale, configurazione dell'esecuzione in Docker.

1. 1

   Preparare l'ambiente

   La guida all'installazione richiede Python 3.10 o successivo e consiglia un ambiente virtuale. Per questo esempio, anche Docker deve essere installato e in esecuzione. Guida all'installazione.

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   Impostare la variabile d'ambiente HF_TOKEN con un token Hugging Face autorizzato a chiamare Inference Providers. InferenceClientModel può leggere automaticamente questa variabile. Il token non va inserito nello script. Gestione dell'autenticazione.

2. 2

   Eseguire il compito della documentazione in Docker

   Salvare questo codice come sum_agent.py:

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   Quindi eseguire:

   python sum_agent.py

   Il context manager si occupa della pulizia della sandbox all'uscita dal blocco. Si tratta di un adattamento della documentazione, non del risultato di un test eseguito per questo articolo.

3. 3

   Verificare il risultato e il confine di esecuzione

   Il risultato matematico atteso è 55, calcolato come 10 × 11 ÷ 2. È il modello a scegliere il codice Python da generare: non bisogna quindi aspettarsi una sequenza di esecuzione precisa o risposte formulate sempre allo stesso modo.

   tools=[] indica che non sono stati forniti strumenti personalizzati. Non significa che CodeAgent abbia perso la capacità di eseguire Python. È l'impostazione dell'executor a spostare in Docker l'esecuzione del codice generato.

Per un calcolo così definito, nel codice applicativo è sensato usare Python ordinario. L'esempio serve a mostrare il meccanismo dell'agente. Un agente va introdotto quando scegliere i passaggi intermedi è parte del problema, non soltanto perché il calcolo si può descrivere in linguaggio naturale.

Gli agenti che eseguono codice hanno bisogno di una sandbox

Il Python generato va trattato come codice non attendibile e collocato in una sandbox esplicita prima di esporlo a input non attendibili. L'executor locale predefinito è un interprete con restrizioni, non una garanzia di isolamento della macchina host. Hugging Face include tra i rischi gli errori del modello, la prompt injection e le richieste malevole. Esecuzione sicura del codice.

L'interprete locale valuta l'albero sintattico astratto di Python, cioè la struttura del programma ottenuta dal parsing, un'operazione alla volta. Limita le importazioni e i sottomoduli e impone un tetto alle operazioni. Questi controlli riducono l'esposizione, ma la guida alla sicurezza avverte che l'esecuzione locale comporta comunque dei rischi. Autorizzare un pacchetto aggiuntivo amplia ciò a cui il programma generato può accedere.

Le sandbox indicate da Hugging Face

L'attuale API degli executor supporta Blaxel, E2B, Modal e Docker, oltre all'executor locale. I nomi di configurazione riportati sotto corrispondono al riferimento di CodeAgent e al riferimento degli executor.

La scelta del provider e delle credenziali va gestita separatamente da queste impostazioni. La documentazione di installazione elenca le dipendenze facoltative; installare un extra, da solo, non configura un deployment.

Per un esperimento interno, Docker può offrire un confine di esecuzione concreto da esaminare. Per un servizio che gestisce richieste non attendibili, l'ambiente va scelto in base alle esigenze di isolamento, gestione del ciclo di vita e controllo operativo. Il confronto tra sandbox per il codice degli agenti AI approfondisce questa decisione infrastrutturale.

Isolare gli snippet non equivale a isolare l'intero agente

Prima di aggiungere altri agenti, occorre decidere che cosa debba stare dentro il confine di isolamento. Hugging Face distingue tra eseguire in una sandbox gli snippet generati ed eseguirvi l'intero sistema di agenti. La guida alla sicurezza avverte che il primo approccio non supporta i managed agents, cioè gli agenti che un altro agente chiama come collaboratori. Spostare l'intero sistema all'interno richiede più configurazione e può rendere necessario fornire delle credenziali. Approcci all'uso delle sandbox.

Le conseguenze riguardano l'architettura. Se in futuro un agente specialista dovesse chiamare un modello dall'interno dell'ambiente di esecuzione, lo schema iniziale «invia codice, ricevi risultato» potrebbe non bastare più. Quando cambia la struttura del deployment, vanno riesaminate la collocazione delle credenziali e le dipendenze degli strumenti.

Per un servizio rivolto ai clienti, occorre definire file consentiti, destinazioni di rete e operazioni richiamabili prima di avviare l'agente. Ogni esecuzione deve ricevere soltanto gli accessi necessari al proprio compito. Timeout, annullamento e pulizia vanno previsti come percorsi ordinari di esecuzione, anche quando il modello non riesce a terminare.

Quando conviene un framework essenziale e quando serve altro

La scelta del framework dovrebbe partire dall'aspetto dell'applicazione più difficile da tenere sotto controllo. Un'inizializzazione breve è comoda, ma conta di più il codice che occorre scriverle intorno.

smolagents o LangGraph: azioni dinamiche o controllo persistente?

LangGraph è il punto di partenza più solido quando un processo deve persistere, sospendersi e riprendere attraverso stati aziendali espliciti. È un runtime di orchestrazione a basso livello per workflow con stato, con supporto alla persistenza e all'intervento umano nel ciclo di esecuzione. Può combinare passaggi deterministici e passaggi guidati dal modello e non richiede LangChain. Panoramica di LangGraph.

Si consideri un workflow di acquisto che raccoglie informazioni, attende la decisione di un responsabile e riprende dopo l'approvazione. Il problema centrale è conservare lo stato del processo e far rispettare le transizioni consentite. Se sono questi i requisiti che definiscono il prodotto, conviene partire da LangGraph.

L'impegno richiesto è progettare il workflow: stati, transizioni, persistenza e significato della ripetizione di un passaggio. Nel processo di acquisto è uno sforzo giustificato. Per un assistente di ricerca circoscritto, che legge dati, calcola una risposta e si ferma, può essere una struttura superflua.

smolagents è adatto quando l'incertezza riguarda soprattutto quali operazioni Python risolvono il compito. LangGraph lo è quando riguarda soprattutto come far avanzare il processo in sicurezza attraverso stati persistenti. È un'indicazione progettuale, non l'affermazione che ciascun framework sappia svolgere un solo tipo di lavoro.

OpenAI Agents SDK: passaggi tra agenti, controlli e tracciamento

OpenAI Agents SDK è una scelta di partenza più adatta quando il fulcro dell'applicazione è il coordinamento tra specialisti e i controlli operativi. Gli handoff trasferiscono la gestione della conversazione a un altro agente; il modello agents-as-tools consente invece a un agente coordinatore di mantenere la responsabilità della risposta. Documentazione sull'orchestrazione.

Per un assistente di supporto clienti, uno specialista della fatturazione che prende in carico la conversazione può essere un'astrazione più chiara di un agente generico che risolve problemi in Python. Il tracciamento integrato registra chiamate ai modelli, chiamate agli strumenti, handoff e guardrail. I guardrail forniscono controlli automatici, mentre i meccanismi di revisione umana sospendono le azioni sensibili in attesa di una decisione. Tracciamento, guardrail e revisione.

Resta a carico di chi sviluppa la policy applicativa: decidere che cosa richieda un'approvazione, implementare correttamente lo strumento e gestire il lavoro interrotto. Queste primitive non definiscono la policy al suo posto. L'SDK documenta anche schemi per agenti in sandbox: l'esecuzione di codice non è quindi una prerogativa esclusiva di smolagents.

Tra i due, smolagents è preferibile quando serve comporre azioni Python e basta un ciclo essenziale. Agents SDK è più adatto quando le sue primitive di coordinamento e revisione corrispondono all'applicazione da costruire. La sola «leggerezza» non basta a decidere.

Per una selezione più ampia, si può consultare il confronto tra framework per agenti AI. Se invece si cerca un'applicazione con agenti da installare, anziché una libreria su cui sviluppare, il punto di partenza è la guida agli agenti AI open source.

Che cosa viene sopravvalutato negli agenti che usano codice?

Un framework piccolo non rende prevedibile un compito imprevedibile. L'espressività di Python è utile, ma non permette di stabilire se il modello abbia selezionato i record giusti, interpretato correttamente un'unità di misura o rispettato una regola aziendale.

La possibilità di combinare operazioni non va trasformata in una promessa universale di velocità. La composizione può cambiare il modo in cui si svolge un'esecuzione; il risultato continua a dipendere da modello, compito, comportamento degli strumenti e ambiente di esecuzione. Prima di scegliere in base alle prestazioni, occorre misurarle sul proprio caso d'uso.

C'è anche un limite concreto da conoscere: nell'attuale API degli agenti, max_steps ha come valore predefinito 20. Limita i passaggi dell'agente, non le risorse consumate da una singola azione Python. L'API espone anche callback, managed agents e controlli sulla risposta finale: essenzialità non significa assenza di controlli. Riferimento degli agenti.

Sul piano operativo, tempo di esecuzione e risorse vanno quindi limitati separatamente. Un tetto al numero di passaggi non sostituisce una policy per la sandbox, e una sandbox non garantisce un risultato corretto.

Da dove partire la prossima settimana

Il primo passo è un compito circoscritto, in sola lettura, la cui risposta sia verificabile in modo indipendente. Uno sviluppatore Python che valuta smolagents potrebbe usare un'esportazione dell'inventario depurata dai dati sensibili e uno strumento di consultazione con un ambito ristretto, confrontando poi le incongruenze individuate dall'agente con esempi già noti.

Occorre registrare se ha selezionato i record corretti, usato bene gli strumenti, recuperato dagli errori previsti e terminato entro i limiti impostati. Va mantenuta una soluzione deterministica di riferimento. Se il compito segue sempre lo stesso percorso, conviene scriverlo come codice ordinario: la stessa guida di Hugging Face raccomanda funzioni deterministiche ovunque sia possibile. Come costruire buoni agenti.

CodeAgent merita di essere adottato quando la composizione dinamica di Python giustifica la complessità che introduce. ToolCallingAgent è adatto quando basta un insieme definito di strumenti. Se il workflow esistente soddisfa già i requisiti, la migrazione può aspettare. La scelta del framework va riesaminata quando diventano centrali approvazioni persistenti o passaggi tra agenti specialisti.

Installazione e compatibilità

Come si installa smolagents con pip?

La libreria di base si installa con pip install smolagents. Vanno poi aggiunti gli extra necessari per strumenti, modelli o ambiente di esecuzione. L'esempio pratico usa smolagents[docker].

Come orientarsi tra HfApiModel e l'interfaccia attuale di smolagents?

Per il nuovo codice, seguire l'interfaccia InferenceClientModel della documentazione attuale. Prima di copiare le importazioni da vecchi esempi, confrontarle con il riferimento online dei modelli.

Come si usa smolagents con Docker?

Installare e avviare Docker, installare l'extra per Docker e selezionare executor_type="docker". Il confine di esecuzione va configurato in funzione del carico di lavoro: questa impostazione, da sola, non costituisce una policy di sicurezza completa.

Ricevi nella newsletter consigli pratici per sviluppare con l'AI.