C'è un momento in ogni progetto software in cui ti rendi conto che stavi costruendo la cosa sbagliata. Hai passato settimane a scrivere un router di messaggi, un motore di esecuzione degli strumenti, un gestore dello stato delle conversazioni e un sistema di retry — e poi scopri che il provider AI gestisce già tutto questo, meglio di quanto potresti fare tu, con una singola chiamata API.
Quel momento è ciò che ha portato all'architettura di NanoClaw. L'intero core — la parte che trasforma un messaggio WhatsApp in una risposta di un agente AI con uso di strumenti, navigazione web, accesso ai file e conversazione multi-turno — è di circa 500 righe di TypeScript. Non 500 righe di codice collante che importa 50.000 righe di framework. Cinquecento righe, in totale, costruite su Claude Agent SDK di Anthropic.
La reazione degli sviluppatori che leggono il codice sorgente per la prima volta è solitamente incredulità, seguita dalla domanda che conta: "Dov'è il resto?"
Cosa fa davvero Claude Agent SDK
La maggior parte dei framework per agenti AI esiste perché, storicamente, le API dei modelli linguistici erano stateless e semplici. Inviavi un prompt, ricevevi una risposta. Se volevi l'uso di strumenti, dovevi costruire tu il loop di esecuzione. Se volevi conversazioni multi-turno, dovevi gestire tu la cronologia dei messaggi. Se volevi che il modello scegliesse tra più strumenti, dovevi costruire tu la logica di routing.
Claude Agent SDK cambia radicalmente quell'equazione. L'SDK non si limita a chiamare l'API di Claude — esegue un loop di agente. Gli dai un system prompt, un set di strumenti e un messaggio utente. L'SDK gestisce tutto il resto: invia il messaggio a Claude, riceve la risposta, verifica se Claude vuole usare uno strumento, esegue lo strumento, rimanda il risultato a Claude e ripete finché Claude non produce una risposta finale. L'intero loop di uso degli strumenti — quello per cui la maggior parte dei framework spende migliaia di righe — è una singola chiamata di funzione.
Non si tratta di un wrapper sottile. L'SDK gestisce streaming, logica di retry, conteggio dei token e stato della conversazione. Gestisce lo scambio tra Claude e gli strumenti su più turni, gestendo casi limite come fallimenti nell'esecuzione degli strumenti e limiti della finestra di contesto. La complessità che NanoClaw non ha bisogno di implementare non manca — è stata spostata in un SDK ben testato e mantenuto dal team di ingegneria di Anthropic.
Cosa costruisce effettivamente NanoClaw
Se l'SDK gestisce il loop dell'agente, cosa fanno le 500 righe di NanoClaw? La risposta è tutto ciò che sta intorno al loop — le parti specifiche dell'esecuzione di un assistente AI personale piuttosto che della semplice chiamata a un'API.
La prima responsabilità è l'integrazione dei canali. NanoClaw si connette a WhatsApp tramite la libreria Baileys, riceve i messaggi e li instrada al container dell'agente giusto. È il collante tra "qualcuno ha inviato un messaggio su WhatsApp" e "un agente deve elaborare questo messaggio." Non è codice complicato, ma è codice essenziale — senza di esso, l'agente non ha modo di raggiungere gli utenti dove già si trovano.
La seconda responsabilità è l'orchestrazione dei container. Ogni conversazione con un agente gira all'interno del proprio container Linux — Apple Container su macOS, Docker su Linux. NanoClaw avvia i container, monta le directory giuste, passa i segreti tramite stdin e raccoglie le risposte. Questo è il confine di sicurezza che impedisce a un agente compromesso di accedere a qualsiasi cosa al di fuori della sua sandbox. La gestione del ciclo di vita dei container è forse 80 righe di codice, ma quelle 80 righe fanno la differenza tra un agente a cui si possono affidare credenziali reali e uno a cui no.
La terza responsabilità è la memoria persistente. NanoClaw mantiene un database SQLite di conversazioni, stato dei gruppi e attività pianificate. Ogni gruppo WhatsApp ottiene il proprio file CLAUDE.md che funge da memoria a lungo termine dell'agente per quel gruppo. Il sistema di memoria è semplice — intenzionalmente — perché la parte complessa della memoria (decidere cosa è rilevante, cosa richiamare, come usare il contesto) è gestita da Claude stesso.
La quarta responsabilità sono le attività pianificate. Gli utenti possono chiedere all'agente di fare cose a orari specifici — "ricordamelo alle 15" o "controlla questo sito ogni mattina." Lo scheduler cron-like di NanoClaw attiva i container degli agenti al momento giusto, una funzionalità piccola ma genuinamente utile che trasforma un chatbot reattivo in un assistente proattivo.
Perché 500 righe contano
Il conteggio delle righe non è una metrica di vanità. È una misura diretta della superficie di manutenzione, della superficie di bug e del carico cognitivo necessario per comprendere il sistema.
Quando appare un bug nel core di NanoClaw, ci sono 500 righe dove potrebbe trovarsi. Uno sviluppatore può leggere l'intero codebase in meno di un'ora e comprendere ogni decisione presa. Confrontalo con framework da 50.000 righe di codice core — trovare un bug significa navigare astrazioni, comprendere sistemi di plugin e tracciare l'esecuzione attraverso livelli di indirezione che esistono per supportare funzionalità che potresti nemmeno usare.
Le implicazioni per la sicurezza sono altrettanto concrete. Ogni riga di codice è una potenziale vulnerabilità. Il core da 500 righe di NanoClaw ha una superficie d'attacco più piccola dei parser di configurazione della maggior parte dei framework. L'isolamento tramite container, il passaggio dei segreti via stdin, le allowlist dei mount — queste funzionalità di sicurezza sono implementate in codice abbastanza piccolo da poter essere auditato completamente in un pomeriggio.
E la storia degli aggiornamenti è semplice. Quando Anthropic rilascia una nuova versione di Claude Agent SDK con un uso migliore degli strumenti, streaming più veloce o nuove funzionalità, NanoClaw ottiene quei miglioramenti aggiornando una singola dipendenza. Non c'è un livello di astrazione del framework da aggiornare per esporre le nuove funzionalità dell'SDK. L'SDK è il framework.
La filosofia del non costruire
La parte più difficile dell'architettura di NanoClaw non è stata costruirla — è stata decidere cosa non costruire. La tentazione di aggiungere un motore di esecuzione degli strumenti personalizzato, un sistema sofisticato di recupero della memoria, un livello di astrazione multi-provider, un marketplace di plugin — sono tutte cose che altri framework hanno costruito, e sono tutte cose che NanoClaw deliberatamente non ha.
Ognuna di quelle funzionalità aggiungerebbe migliaia di righe di codice, decine di potenziali bug e settimane di onere di manutenzione. E ognuna duplicherebbe funzionalità che Claude Agent SDK già fornisce o che Claude stesso gestisce meglio di qualsiasi codice scritto a mano.
Il risultato è un progetto dove le decisioni interessanti sono architetturali, non implementative. Come dovrebbero essere isolati i container? Come dovrebbero essere passati i segreti? Come dovrebbe essere organizzata la memoria per gruppo? Queste sono le domande che contano per un assistente AI personale, e sono le domande a cui le 500 righe di NanoClaw sono dedicate a rispondere.
La prossima volta che valuti un framework per agenti AI, non contare le funzionalità. Conta le righe. Il framework con meno righe non è il meno capace — potrebbe essere quello che ha compreso il problema abbastanza bene da lasciare che il provider AI faccia il lavoro pesante.