Costruire un agente AI con Claude: la differenza non è il modello, è il loop

"Quanto è diverso un agente da un prompt fatto bene?"

Me lo chiede quasi ogni cliente nella prima call, di solito dopo aver passato qualche mese a usare una chat e aver capito che il risparmio si ferma a pochi minuti al giorno. La risposta breve è che sono due categorie diverse di oggetto. Un prompt risponde. Un agente riceve un obiettivo, decide quali azioni compiere, le esegue, guarda cosa è successo e ricomincia finché non ha finito.

La risposta lunga è questo articolo. Architettura, strumenti, scelta del modello, sub agenti, memoria, costi e i guasti che ho collezionato mandando in produzione ventuno automazioni con zero dipendenti. Non è una panoramica: è quello che uso.

Chatbot e agente: quello che cambia è il loop

Un chatbot è reattivo. Riceve un input, produce un output, si ferma. Un solo passaggio.

Un agente è un ciclo. Ragiona su cosa serve, sceglie uno strumento, lo chiama, legge il risultato, ragiona di nuovo. Continua finché non decide di aver concluso. Questo schema si chiama ReAct (ragiona e agisci) ed è la struttura sotto quasi tutti gli agenti seri, Claude compreso.

La differenza si vede meglio con un esempio concreto.

Chatbot: "ecco il testo dell'email che potresti mandare a questo cliente".

Agente: legge la richiesta arrivata dal form, cerca il cliente nel CRM, verifica se ha già uno storico aperto, scrive la risposta con quel contesto, la manda, aggiorna il record, e ti scrive su Slack solo se ha trovato qualcosa che richiede una tua decisione.

Il secondo caso non è "lo stesso prompt ma più lungo". È codice che gestisce un ciclo, strumenti definiti con precisione, una gestione degli errori e un punto in cui il ciclo si ferma. Il modello è un pezzo del sistema, e non è il pezzo dove passi la maggior parte del tempo.

Su questo punto vale la pena leggere direttamente la fonte: la guida di Anthropic su come costruire agenti efficaci parte proprio dalla raccomandazione di non costruire un agente quando basta un workflow. La condivido. La domanda giusta prima di iniziare è: il compito è davvero aperto, o è una sequenza che posso scrivere io una volta e far girare?

I tre livelli di un agente Claude

Livello 1: il motore di ragionamento

È il modello che decide l'azione successiva. Nel 2026 le famiglie correnti sono Opus 5, Sonnet 5, Haiku 4.5 e Fable 5, oltre ai modelli della serie 4.x ancora attivi. La scelta non è "prendi il più potente", è una questione di dove si concentra la difficoltà del tuo compito.

Il criterio che uso, semplificato:

1. Opus 5 quando il compito è lungo, agentico, con molti passaggi e un costo dell'errore alto. Ragionamento profondo, coordinamento di più strumenti, lavoro che deve arrivare in fondo da solo.
2. Sonnet 5 quando serve un equilibrio tra qualità e volume. È il cavallo da lavoro della maggior parte delle pipeline: qualità vicina all'Opus su coding e compiti agentici, a un costo per token sensibilmente più basso.
3. Haiku 4.5 per i compiti semplici e ad alto volume: classificazione, estrazione, smistamento, filtri. Dove la risposta è corta e il criterio è netto.

Sul listino API, al momento in cui scrivo, Opus 5 sta a 5 dollari per milione di token in ingresso e 25 in uscita, Sonnet 5 a 3 e 15, Haiku 4.5 a 1 e 5. Sono numeri che cambiano: la fonte da controllare è sempre la pagina ufficiale dei modelli, non un articolo. Il ragionamento sulla scelta, con i casi d'uso in dettaglio, l'ho messo in quale modello Claude scegliere per le automazioni.

Due parametri contano più della scelta del modello, e quasi nessuno li tocca.

Il primo è il thinking adattivo. Sui modelli correnti non si imposta più un budget fisso di token di ragionamento: si attiva la modalità adattiva e il modello decide da solo quanto pensare in base alla difficoltà. Il vecchio approccio a budget fisso è stato rimosso sui modelli recenti e viene rifiutato.

Il secondo è l'effort, che regola la profondità del ragionamento e la spesa complessiva su una scala da bassa a massima. È la leva che sposta di più il rapporto tra qualità, latenza e costo. La mia regola pratica: parti alto sui compiti agentici e di coding, poi scendi di un gradino alla volta misurando la qualità sul tuo insieme di test. Un livello basso su un sotto agente che fa un lavoro semplice fa risparmiare molto e non toglie nulla.

Livello 2: gli strumenti

Un agente senza strumenti è una chat con più passaggi. Gli strumenti sono quello che gli permette di agire: leggere un file, chiamare un'API, scrivere in un database, mandare un messaggio.

Ogni strumento si dichiara con un nome, una descrizione e uno schema JSON degli input. La parte che fa la differenza tra un agente che funziona e uno che sbaglia in continuazione è la descrizione, e in particolare una cosa: la descrizione deve dire quando chiamare lo strumento, non solo cosa fa.

Male: "Cerca informazioni sul web." Meglio: "Chiamalo quando la risposta dipende da informazioni non presenti nella conversazione: eventi recenti, prezzi correnti, comportamenti legati a una versione specifica. Non usarlo per fatti stabili che conosci già."

Sui modelli recenti questa differenza è misurabile, perché tendono a essere più conservativi nel chiamare strumenti rispetto ai predecessori. Se un agente "non cerca mai", nove volte su dieci il problema è la descrizione dello strumento, non il modello.

Altre tre cose da sapere sugli strumenti, imparate rompendole:

Le chiamate parallele sono attive di default. Il modello può chiedere più strumenti in una sola risposta. Vanno eseguiti e i risultati vanno restituiti tutti insieme, in un unico messaggio. Se li spezzi su più messaggi, il modello smette gradualmente di fare chiamate parallele e la pipeline rallenta senza che tu capisca perché.

Gli errori vanno restituiti, non nascosti. Se uno strumento fallisce, la risposta è comunque un risultato, marcato come errore, con un messaggio che spiega cosa è andato storto. Un agente che riceve "errore: città 'xyz' non trovata, fornisci un nome valido" si corregge. Un agente che non riceve niente si blocca o inventa.

Il parsing degli input va fatto sul JSON, non sulla stringa. I modelli recenti possono cambiare il modo in cui codificano caratteri speciali e barre nell'input serializzato. Chi confronta stringhe grezze prima o poi si rompe senza motivo apparente.

Se gli strumenti da collegare sono servizi esterni con un protocollo standard, la strada è MCP: ne ho scritto in MCP con Claude, come collegare API esterne, e la specifica sta su modelcontextprotocol.io.

Livello 3: l'orchestrazione

È il codice che tiene insieme il ciclo. Chiama il modello, guarda perché si è fermato, esegue gli strumenti richiesti, rimanda i risultati, ripete.

Il punto su cui si sbaglia più spesso è la condizione di uscita. Non basta guardare se è arrivato del testo. Bisogna leggere il motivo dello stop, che può essere: ho finito il turno, voglio usare uno strumento, ho esaurito i token di output, ho superato la finestra di contesto, mi sono fermato per una pausa tecnica lato server, ho rifiutato la richiesta. Ognuno richiede una reazione diversa, e trattarli tutti allo stesso modo produce loop infiniti o risposte troncate spacciate per complete.

Due dettagli che risparmiano ore:

1. Metti sempre un tetto alle iterazioni. Un agente che non converge deve fermarsi da solo, non consumare budget finché qualcuno non se ne accorge.
2. Se l'output atteso è lungo, usa lo streaming. Sopra una certa soglia una richiesta non in streaming rischia di sbattere contro i timeout HTTP del client, e il fallimento arriva dopo aver già pagato la generazione.

Per il ciclo non serve scriverlo a mano: gli SDK ufficiali offrono un tool runner che lo gestisce, lasciandoti comunque i punti di aggancio per approvare, bloccare o modificare una chiamata prima che venga eseguita. Il ciclo manuale ha senso quando ti serve un controllo che quei punti di aggancio non coprono, non "per avere il controllo" in astratto.

Sub agenti: quando servono e quando sono uno spreco

I sub agenti sono agenti che l'agente principale può lanciare per pezzi di lavoro indipendenti. Nel mio sistema ne uso quattro, versionati come profili con un modello e dei permessi dichiarati: uno di verifica in sola lettura su modello economico, uno che costruisce e tocca file e deploy, uno di ricerca su fonti ufficiali, uno di revisione ostile che prova a rompere il lavoro prima che lo faccia la realtà.

Ha senso delegare quando il lavoro si apre a ventaglio: molti file da leggere in parallelo, molti candidati da controllare, tracce indipendenti che non si toccano. E ha senso quando vuoi separare i ruoli: chi scrive il codice non è un buon giudice del proprio codice, e un revisore con contesto fresco trova più cose di un'autocritica.

Non ha senso quando il lavoro lo finiresti in poche chiamate. Ogni sub agente ricostruisce il proprio contesto, riesplora, riferisce, e poi tu rileggi il suo rapporto. È un moltiplicatore di costo e latenza. La regola che ho scritto nel mio setup: se il compito si chiude con un sub agente, non usarne due; se si chiude senza, non usarne nessuno; e la verifica sta nel ciclo principale, non delegata.

Un dettaglio pratico che vale i suoi soldi: se lanci più sub agenti su lavori indipendenti, mandali in un unico messaggio con più chiamate, così girano insieme invece che in fila. L'implementazione lato Python, con i risultati aggregati, l'ho descritta in sub agenti con l'Agent SDK.

Memoria: tre livelli, ognuno con un mestiere diverso

Un agente che riparte da zero ogni volta ha un tetto basso. Uno che ricorda tutto diventa costoso e confuso. La soluzione che uso ha tre livelli distinti.

Il contesto della sessione è quello che il modello ha davanti adesso. Va curato, non riempito. Quando cresce troppo si comprime, riassumendo la parte vecchia lato server, oppure si pota, eliminando i risultati di strumenti ormai irrilevanti. Sono due meccanismi diversi: il primo riassume, il secondo cancella. Ne ho scritto in dettaglio in context engineering con Claude.

La memoria persistente su file è quella che sopravvive alle sessioni. Nel mio caso è una cartella di note atomiche nel repository, con un indice, un formato dichiarato e un controllo automatico che verifica che le relazioni tra le note siano coerenti e che le note di stato siano state riverificate di recente. Non è un archivio: è una fonte che gli agenti leggono prima di decidere. L'architettura completa sta in la memoria a tre layer di Claude.

Il canale tra automazioni è il pezzo che manca quasi sempre. Nel mio sistema una trentina di task condivide un file di segnali in sola aggiunta: chi gira prima scrive, chi gira dopo legge nello stesso ciclo. È quello che trasforma venti automazioni scollegate in un sistema che si accorge di sé stesso. Un guardiano deterministico controlla che il file non si corrompa, perché un canale condiviso senza un guardiano diventa entropia in due settimane.

La parte che nessuno mostra: cosa si rompe

Un agente in produzione non fallisce con un errore rosso. Fallisce in silenzio. Qui ci sono tre guasti reali del mio sistema, con la lezione attaccata.

Il monitor guardava la cosa sbagliata. Il mio health check verificava che i job cloud fossero stati lanciati, non che fossero riusciti, perché la riga di stato la scriveva chi accendeva il job. Tra il 3 e il 9 luglio 2026 tre esecuzioni sono fallite senza un alert, e un job di raccolta contenuti è rimasto morto circa tre settimane per un errore di validazione prima che me ne accorgessi. Il cruscotto era verde. L'ho riscritto l'11 luglio perché valuti le esecuzioni: verde significa "c'è stato un successo dentro la finestra prevista". Se il tuo monitor misura l'intenzione invece del risultato, ti sta facendo dormire.

Il gate misurava la lunghezza e non il contenuto. Avevo un controllo che imponeva una soglia minima di caratteri sui testi generati. Uno script ha superato quel controllo duplicando lo stesso paragrafo quindici volte. Il gate era verde, il contenuto era spazzatura. Ho aggiunto una misura di ripetizione interna che confronta passaggi di otto parole consecutive: sui file legittimi resta sotto l'uno per cento, sui tre file gonfiati stava tra il 50 e il 93 per cento. Lezione generale: ogni metrica che diventa un obiettivo verrà ottimizzata, anche da un sistema che non ha alcuna intenzione di barare.

La risorsa temporanea è rimasta accesa. Un trigger creato per una singola pubblicazione l'ho ritrovato ancora attivo alla scadenza. Da lì ho scritto una regola: una risorsa temporanea si spegne nella stessa sessione che ne verifica l'esito, oppure nasce auto terminante. Se deve restare aperta oltre la sessione, va in una lista di stato con una data, non in una nota che nessuno rilegge.

C'è un filo che unisce i tre. Nessuno era un problema del modello. Erano tutti problemi di sistema intorno al modello.

Il conto: come si tiene basso senza peggiorare i risultati

Quattro leve, in ordine di impatto.

La cache del prompt. Se una parte del prompt si ripete tra le richieste (istruzioni di sistema, definizioni degli strumenti, documenti di riferimento) si può marcare come cacheabile. Le letture dalla cache costano circa un decimo del prezzo pieno, le scritture costano un po' di più del pieno. Il meccanismo funziona per prefisso: qualunque byte cambi all'inizio invalida tutto quello che viene dopo. Il che significa una regola secca: niente date, niente identificativi di sessione, niente contenuti variabili dentro il prompt di sistema. Il contenuto che cambia va in fondo, dopo il punto di taglio. Se le letture dalla cache restano a zero tra richieste identiche, c'è un invalidatore nascosto: quasi sempre è un timestamp o una serializzazione JSON non ordinata.

La scelta del modello per pezzo di pipeline. Non serve il modello più capace per classificare un'email. Un agente ben progettato usa modelli diversi in punti diversi. Attenzione a un dettaglio: cambiare modello a metà conversazione invalida la cache, quindi il modo giusto è delegare il pezzo economico a un sotto agente, non alternare i modelli nel ciclo principale.

L'effort. Scendere di un gradino su un compito che non è sensibile all'intelligenza taglia token e latenza senza che si veda nella qualità. Va misurato sul proprio insieme di test, non deciso a intuito.

Il batch. Per il lavoro che non è sensibile alla latenza (arricchimento di anagrafiche, classificazione notturna, elaborazioni massive) l'API a lotti costa la metà. È la leva più semplice e la più ignorata.

Un caso reale, con i numeri

Il sistema che gestisco oggi è fatto di ventuno automazioni in produzione: alcune girano sul Mac quando è acceso, altre come job schedulati su Google Cloud Run che girano comunque. Producono contenuti, monitorano la Search Console, sorvegliano lo stato del sistema, consolidano la memoria, generano video e caroselli per Instagram.

Tre elementi lo tengono in piedi.

Il primo è il bus di segnali già descritto: un file condiviso in sola aggiunta che permette a un task di leggere cosa hanno fatto gli altri nello stesso ciclo, sincronizzato tre volte al giorno.

Il secondo è il loop di igiene notturno: un controllo che verifica un elenco di invarianti sul sistema, applica le correzioni meccaniche che sa fare da solo, e segnala il resto. Gira anche a Mac spento, perché parte dal cloud.

Il terzo sono i gate deterministici. Prima di toccare qualsiasi file che governa lo stile o i fatti dichiarabili nei contenuti, faccio girare una suite di valutazione. L'ultima esecuzione completa ha dato 97 test deterministici su 97 e 28 valutazioni con giudice su 28. Nessuno di questi controlli usa un modello per decidere se un altro modello ha sbagliato in modo soggettivo: dove è possibile la verifica è meccanica, perché una verifica meccanica non ha una brutta giornata.

Il quadro completo, con la mappa dei task e i costi mensili reali, è nel caso studio dell'ecosistema di 21 automazioni. Per il pezzo infrastrutturale, cioè come si porta un agente da script locale a job schedulato, ho scritto deploy di automazioni Claude su Google Cloud Run.

Da dove partire davvero

Se stai per costruire il tuo primo agente, l'ordine che consiglio è questo.

Prima scrivi cosa deve produrre e come farai a sapere che ha funzionato. Un output, un formato, un criterio di accettazione. Se non riesci a scriverlo in cinque righe, il problema non è ancora definito al punto da poter essere automatizzato.

Poi costruisci la versione senza agente. Uno script che fa i passaggi in sequenza, con una sola chiamata al modello nel punto dove serve davvero giudizio. Nella maggior parte dei casi ti fermi qui e hai risolto, con un decimo della complessità.

Se il compito è davvero aperto, aggiungi il ciclo. Due o tre strumenti, non dieci. Un tetto alle iterazioni. Gli errori restituiti al modello invece che ingoiati.

Poi, prima di considerarlo finito, aggiungi il pezzo che tutti rimandano: come te ne accorgi quando si rompe. Un alert su un canale che guardi davvero. Se non c'è, quello che hai costruito non è ancora in produzione. È in prova, e la prova finirà il giorno in cui smetterai di controllarlo a mano.

Se vuoi imparare a lavorare così senza passare i miei stessi mesi a sbagliare, ho raccolto il metodo in Claude Mastery, un manuale operativo da 19 euro. Se preferisci uscire con una cosa che gira nel tuo stack invece che con delle nozioni, l'AI Build Day è una giornata singola con rimborso pieno se a fine giornata non gira niente. E se hai già un processo preciso in testa e vuoi solo capire se ha senso, prendiamoci trenta minuti.