Per gli ultimi pochi anni, "un agent usa uno strumento" ha significato un meccanismo specifico: il modello emette un blob strutturato — solitamente JSON — nominando una funzione e i suoi argomenti, un runtime lo parsa, chiama la funzione, e alimenta il risultato back nel contesto del modello. Questo pattern tool-calling ha alimentato la prima generazione di framework di agent ed funziona. Ma ha una inefficienza silenzioso che diventa ovvia una volta che la cerchi: ogni azione è un round-trip separato attraverso il modello. Vuoi chiamare tre tool e combinare i loro risultati? Questo è almeno tre model call, ciascuno ri-leggendo il contesto accumulato, perché il modello può solo emettere una JSON tool call alla volta e deve aspettare di vedere ogni risultato prima di decidere il prossimo. Una scuola di pensiero crescente nel 2026 sostiene c''è un modo migliore, ed è nascosto in vista: lascia che l''agent scriva codice.
Questo è il paradigma code-first agent, ed sta reshapando come i framework più efficienti di agent funzionano. Invece di emettere JSON, l''agent scrive uno snippet di Python — che può chiamare molteplici tool, loopare, usare variabili, e combinare risultati — e il runtime l''esegue. Questa guida spiega perché quello shift importa, come cambia la performance e il costo degli agent, e come i framework leader l''implementano, attraverso smolagents (l''approccio code-first nella sua forma più pura) e Pydantic AI (type-safe agent dal team di Pydantic). Inoltre copre il flip side essenziale: eseguire codice model-generated in sicurezza.
Il problema con le JSON tool call
Per vedere perché code-first importa, guarda da vicino quello che le JSON tool call costano. Considera un task che richiede fetchare dati da una API, filtrarli, e computare un sommario. Con tool call, il modello emette una chiamata al fetch tool, aspetta il risultato, emette una chiamata al filter tool, aspetta, poi emette una chiamata al compute tool, aspetta, e finalmente compone una risposta. Questo è quattro invocazioni di modello, e ciascuna ri-processa il contesto intero crescente — il task originale, più ogni risultato intermedio accumulato così lontano. Il costo token e la latenza scalano con il numero di step, e i task complessi hanno molti step.
C''è un problema più sottile anche: le JSON tool call vincolano come l''agent può comporre le azioni. Ogni step è una singola function call con argomenti letterali. Il modello non può facilmente esprimere "chiama questo tool per ogni item in quella lista," o "se il risultato è vuoto, prova una query diversa," o "combina questi due risultati con un calcolo," senza rompere ciascuno di quelli in round-trip separati e ragionamento sullo stato intermedio across model call. L''espressività della programmazione ordinaria — loop, condizionali, variabili, composizione — è esattamente quello che manca, e quelle sono le costruzioni che rendono la logica multi-step naturale. Le tool call chiedono al modello di essere un program counter emettendo una istruzione alla volta, quando quello che il task ha bisogno è un programma.
L''intuizione code-first
L''approccio code-first risolve entrambi i problemi una volta. Invece di emettere una singola JSON tool call, l''agent scrive un blocco di codice Python che può chiamare parecchi tool, usare control flow, mantenere valori intermedi in variabili, e ritornare un risultato. Il runtime esegue quel codice, e i tool che l''agent può chiamare sono semplicemente funzioni Python disponibili nel suo ambiente di esecuzione. L''API fetch, il filter, e il compute dall''esempio precedente diventano un blocco di codice con tre function call e un po'' di logica tra loro — eseguito in un singolo step, da una singola invocazione di modello.
Il guadagno di efficienza è reale e misurabile. Perché un blocco di codice può realizzare quello che precedentemente ha preso parecchi round-trip di tool-call, gli agent code-first fanno LLM call significativamente meno — riduzioni riportate intorno al 30% — che taglia sia il costo che la latenza. E perché l''agent esprime le azioni in un linguaggio di programmazione reale, maneggia i task composizionali (iterando su risultati, branchando su condizioni, combinando computazioni) molto più naturalmente di quanto una sequenza di JSON call isolate potrebbe. C''è anche un argomento di training-data: i modelli hanno visto enormi quantità di codice e sono genuinamente bravi a scriverlo, forse migliore di come sono a produrre perfettamente-formattate JSON tool-call per schemi novel. Chiedere a un modello di esprimere il suo intento come codice gioca a una forza.
smolagents: il paradigma nella sua forma più pura
smolagents, da Hugging Face, è l''espressione più chiara dell''idea code-first. È una libreria deliberatamente minimalista costruita intorno al CodeAgent: un agent le cui azioni sono codice Python. Dai a esso un set di tool (funzioni Python ordinarie) e un modello, daigli un task, e funziona scrivendo e eseguendo codice che chiama quei tool, loopa, e computa finché non ha una risposta. La libreria rimane piccola e hackable di proposito — la sua filosofia è che il loop dell''agent dovrebbe essere semplice abbastanza da leggere e modificare, con l''intelligenza che viene dal modello e dall''approccio code-execution piuttosto che da un framework pesante.
Quello che rende smolagents compelling oltre l''efficienza è come naturalmente maneggia task reali. Perché l''agent scrive codice, un task di ricerca può cercare, parsare risultati, filtrarli, e computare su di loro in un singolo step coerente; un task di dati può caricare, trasformare, e analizzare senza un JSON round-trip per operazione. È model-agnostic — funzionando con modelli Hugging Face, modelli locali, o qualsiasi provider attraverso LiteLLM — così non sei locked a un backend, e supporta l''esecuzione sandboxata che code-first fondamentalmente richiede (più su quello sotto). Per team che vogliono l''efficienza code-first in un package piccolo, comprensibile, smolagents è la reference implementation, e il smolagents cheatsheet copre i suoi agent, tool, e sandboxing.
Il tradeoff della minimalità di smolagents è che fornisce meno scaffolding di un framework heavyweight — meno built-in astrazione per orchestrazione complessa multi-agent, stato durevole, o elaborate control flow. Per singoli agent code loop è una feature, non una limitazione; per sprawling sistemi statefull potresti raggiungere per qualcosa di più pesante. Ma come l''espressione più pura, più minimale del code-first agent, è difficile da battere.
Pydantic AI: type safety incontra gli agent
Pydantic AI, dal team dietro Pydantic (la libreria di validazione che supporta FastAPI e molto dell''ecosistema Python AI), approccio i agent da un angolo diverso: type safety e developer experience. La sua scommessa è che la stessa rigore che Pydantic ha portato alla validazione di dati — dichiarando la forma dei tuoi dati con Python type hint e ottenendo validazione automatica — dovrebbe applicarsi agli agent. Ogni agent input, output, e tool call è typizzato, il framework valida che gli output del modello matchano la struttura attesa, e può automaticamente chiedere al modello di correggersi quando l''output non è conforme. Il risultato è una FastAPI-style developer experience per costruire agent: familiare, type-checked, e production-oriented.
La type safety importa per gli agent più di quanto potrebbe sembrare. Un dolore ricorrente delle applicazioni LLM è che l''output del modello è testo non-strutturato, e trasformarlo affidabilmente nei dati strutturati che il tuo programma ha bisogno — i campi giusti, i tipi giusti, valori validi — è fastidioso e error-prone. Pydantic AI rende il structured output una first-class guarantee: dichiari il tipo di output, e il framework lo enforza, riprova con il modello se necessario. Questo trasforma "parsa il testo del modello e speriamo che sia valido" in "ricevi un oggetto validato, typizzato," che è esattamente quello che il codice di produzione vuole. Il suo redesign V2 nel 2026 ha spinto oltre con un modello harness-first che bundla tool, istruzioni, e settings in capabilità composabili. Il Pydantic AI cheatsheet copre i suoi agent typizzati e tool.
Pydantic AI e smolagents non sono davvero competitor tanto quanto espressioni di priorità diverse. smolagents ottimizza per l''efficienza e l''espressività di code-as-action; Pydantic AI ottimizza per type safety, output strutturato validato, e production ergonomics. Un team che valuta meno LLM call e logica multi-step naturale leans smolagents; un team che valuta type-checked, validato, FastAPI-style agent code leans Pydantic AI. Entrambi rappresentano il movimento 2026 lontano da framework JSON-only della prima generazione verso qualcosa di più programmer-native.
Il problema della sicurezza: eseguire codice model-generated
Gli agent code-first hanno un''ovvia e seria sorpresa: eseguono codice scritto da un modello di linguaggio, e il codice model-generated è untrusted per definizione. Un agent che può scrivere ed eseguire Python arbitrario può, se compromesso da una prompt injection o semplicemente sbagliato, eliminare file, exfiltrate dati, fare network call, o consumare risorse senza bound. Questo non è una preoccupazione ipotetica — è il rischio operazionale centrale dell''intero paradigma, e prenderlo seriamente è non-negoziabile per qualsiasi deployement di produzione.
La risposta è sandboxing: eseguire il codice generato in un ambiente isolato con capacità ristrette. I framework supportano questo direttamente — smolagents può eseguire codice in remote sandbox come E2B, o in container Docker o Modal, piuttosto che nel processo host, e puoi limitare quali moduli il codice generato è perfino permesso di importare. Il principio è least privilege: la sandbox dovrebbe avere solamente l''accesso che il task genuinamente richiede — nessun accesso filesystem che non ha bisogno, nessun network egress oltre quello che è necessario, nessuna abilità di affetto l''host. Eseguire il codice generato dall''agent direttamente nel tuo processo di applicazione, con i permessi della tua applicazione, è l''errore che trasforma uno strumento agent utile in una vulnerabilità di remote code execution che indossa un''interfaccia amichevole.
La guida pratica è semplice ma deve essere seguita. Nello sviluppo, l''esecuzione locale è conveniente e accettabile per task trusted, non-sensibili. In qualsiasi cosa avvicinandosi alla produzione, o qualsiasi task toccando input untrusted o sistemi sensibili, esegui il codice in una sandbox con least-privilege access, limita gli import, e tratta l''output del codice dell''agent nel modo in cui tratteresti qualsiasi input untrusted — perché è quello che è. L''efficienza e la potenza degli agent code-first sono reali, ma vengono con una responsabilità che le JSON tool call (che sono più vincolate per design) non ha imposto così bruscamente. Accetta quella responsabilità e sandboxa propriamente, e il paradigma è sia potente che sicuro.
Quando le JSON tool call sono ancora la scelta giusta
Gli agent code-first sono più efficienti ed espressivi, ma sarebbe un errore concludere che le JSON tool call sono obsolete. Ci sono situazioni reali dove il modello vincolato, uno-call-at-a-time è il fit migliore, e capirle mantiene la scelta onesta. Il più chiaro è quando le azioni devono essere strettamente controllate e auditate. Una JSON tool call è un evento discreto, ispezionabile, facilmente-validabile: l''agent vuole chiamare questa funzione con questi argomenti, e puoi approvare, loggare, o rigettarla prima che qualcosa esegua. Quell''auditabilità è prezioso in domini high-stakes — azioni finanziarie, cambiamenti di infrastruttura, qualsiasi cosa con side effect irreversibili — dove vuoi un controllo umano o una policy check tra l''intento dell''agent e la sua esecuzione. Il codice che esegue come un blocco è più difficile da gate a quella granularità.
Il secondo caso è semplicità. Molti agent genuinamente solamente hanno bisogno di chiamare uno strumento alla volta in un loop semplice — rispondere una domanda chiamando uno strumento di ricerca, cercare qualcosa, eseguire un''azione. Per quelli, l''espressività di code-as-action è capacità inutilizzata, e il macchinario extra di un sandbox di codice è overhead senza payoff. Un simple tool-calling agent è più facile da ragionare e deployare quando il task non ha bisogno di composizione multi-step. Il terzo caso è postura di sicurezza: perché le JSON tool call permettono solo all''agent di invocare funzioni predefinite con argomenti strutturati, è intrinsecamente più vincolato che eseguire codice arbitrario, e per alcuni threat model quel raggio più piccolo è valso il costo di efficienza perfino quando un task potrebbe beneficiare dal codice.
La visione matura è che questi sono due strumenti per job diversi, non un vincitore e un perdente. Raggiungere per code-first quando i task coinvolgono composizione multi-step genuina, iterazione, o computazione su risultati intermedi, e puoi sandboxa propriamente. Raggiungere per le JSON tool call quando le azioni hanno bisogno di controllo fine-grained e auditing, quando il task è semplice abbastanza che code-as-action è overkill, o quando il vincolo più stretto di predefined-functions-only si adatta ai tuoi requisiti di sicurezza. Parecchi framework, incluso smolagents, supportano sia un CodeAgent che un agent tool-calling esattamente per questa ragione — il paradigma è una scelta che fai per use case, non una dottrina che adotti wholesale.
La linea di fondo
Il movimento da JSON tool call a agent code-first è uno dei shift significativi in come gli agent vengono costruiti nel 2026, ed è guidato da un''osservazione semplice: lasciare che un agent scriva codice, piuttosto che emettere una tool call alla volta, è più efficiente e più espressivo. Meno LLM call, logica multi-step naturale, e modelli che giocano alla loro forza di code-writing sono il payoff, visibile nel circa 30% di call reduction che i framework code-first riportano. smolagents esprime il paradigma nella sua forma più pura, minimalista; Pydantic AI porta type safety e structured output validato alla costruzione di agent. Entrambi puntano lontano dalla prima generazione di framework JSON-only verso qualcosa di più programmer-native. L''una regola che non puoi saltare: il codice model-generated è untrusted, quindi sandboxa con least privilege. Fai quello, e gli agent code-first sono il modo più veloce, più capace per costruire.
Riferimenti e Risorse
Framework
Background e analysis
- The best open source frameworks for building AI agents in 2026 — Firecrawl
- Python AI Agent Library Comparison 2026 — Pydantic AI vs Instructor vs Smolagents
- Best Python AI Agent Frameworks in 2026 — Uvik
Related 1337skills cheatsheets