Claude Agent SDK: Report B2B Automatici con Sub-Agenti Python
Tre Ore di Report Ogni Settimana: il Dato che Nessuno Misura
Tre ore. È il tempo medio che un consulente B2B dedica ogni settimana alla produzione manuale dei report clienti. Non è consulenza. Non è analisi strategica. È raccolta dati dal CRM, copia su Excel, riformattazione, invio. Attività con attrito alto e valore generato basso.
Moltiplica per quattro clienti: dodici ore a settimana. Quasi due giorni lavorativi bruciati su un'attività che un sistema automatizzato esegue in 18 minuti.
Il problema non è l'assenza di tool. È l'assenza di architettura.
Dal Prompt Singolo all'Orchestratore: il Salto di Paradigma
La prima generazione di automazioni AI funzionava così: un prompt, un agente, un output. Utile per task semplici. Insufficiente per pipeline complessi.
Il collo di bottiglia è la context window. Un agente che raccoglie dati da tre fonti, li analizza e li formatta in un report strutturato esaurisce il contesto prima di arrivare alla qualità attesa. L'output degrada. Il risultato diventa generico.
L'architettura multi-agente risolve il problema separando le responsabilità: un orchestratore coordina sub-agenti specializzati, ciascuno focalizzato su un layer preciso con contesto ridotto e strumenti limitati. Il tempo totale dipende dal sub-agente più lento, non dalla somma di tutti.
Claude Agent SDK: il Layer Python per l'Orchestrazione in Produzione
Claude Agent SDK (ex Claude Code SDK, rinominato a fine 2025) è il runtime Python ufficiale di Anthropic per costruire questo pattern in produzione. Il package è disponibile su PyPI alla versione 0.1.48 a marzo 2026.
Il ciclo agentico si costruisce con il metodo stream di client.messages: restituisce un iteratore asincrono su eventi di tipo tool_use (il sub-agente richiede un'azione) e message_delta (output testuale). Il loop gestisce entrambi in modo esplicito, senza astrazione nascosta.
Per l'orchestrazione multi-agente, ogni sub-agente viene definito con il suo system_prompt specifico, l'elenco dei tool accessibili e un budget di token separato. L'orchestratore lancia i sub-agenti, riceve i risultati e assembla l'output finale. Se un sub-agente fallisce, il fallback viene gestito a livello di orchestratore senza perdere il contesto degli altri.
Tre sub-agenti, tre context window separate, tre esecuzioni parallele dove possibile.
Architettura Pratica: Pipeline Report B2B in Tre Layer
Un pipeline concreto per report settimanali B2B si struttura in tre layer distinti, con responsabilità non sovrapponibili.
Layer 1, Data Collector: system prompt focalizzato esclusivamente sulla raccolta. Tool concessi: accesso API al CRM, Google Analytics, Airtable. Nessun tool di scrittura. Output atteso: un oggetto JSON con le metriche del periodo, strutturato e validato.
Layer 2, Analyst: prende in input il JSON del Data Collector. Tool concessi: esecuzione Python per calcoli, percentuali e rilevazione anomalie. Nessun accesso a fonti dati esterne. Output: narrativa analitica in italiano con variazioni percentuali e segnalazioni puntuali.
Layer 3, Formatter: prende in input la narrativa dell'Analyst. Tool concessi: generazione PDF o DOCX, invio email via Resend. Output: report formattato e inviato al cliente in automatico.
Layer 1 e Layer 2 sono indipendenti e girano in parallelo. Layer 3 riceve i risultati di entrambi e produce il documento finale. L'orchestratore gestisce la sincronizzazione e il fallback in caso di errore su qualsiasi layer.
Benchmark: da 2 Ore e 45 Minuti a 18 Minuti
Dati reali su un ciclo settimanale di report per quattro clienti B2B.
Processo manuale precedente: raccolta dati 70 minuti, analisi 55 minuti, formattazione 40 minuti. Totale: 2 ore e 45 minuti di attività supervisionata, ogni settimana, per quattro clienti.
Pipeline multi-agente attuale: 18 minuti di esecuzione non supervisionata, 12 minuti di review finale. Totale operativo: 30 minuti, di cui solo 12 richiedono attenzione umana diretta.
Risparmio netto: 135 minuti a settimana. Su base mensile: circa 9 ore recuperate. Costo API per un ciclo completo con Claude Sonnet 4.6: 0,38 euro per quattro report completi.
Le 9 ore mensili recuperate si reindirizzano verso attività con moltiplicatore di valore: acquisizione clienti, analisi strategica, sviluppo prodotto. Il ROI del sistema si chiude nella prima settimana di utilizzo.
Tre Errori Critici da Evitare in Produzione
Il pattern multi-agente funziona bene quando è configurato correttamente. I fallimenti tipici sono prevedibili e prevenibili.
Primo errore: sub-agenti senza timeout. Un sub-agente che entra in loop o perde il contesto consuma token senza produrre output utile. Impostare sempre max_tokens conservativi e un timeout di esecuzione a livello di orchestratore.
Secondo errore: tool condivisi tra sub-agenti paralleli. Se due sub-agenti scrivono sullo stesso endpoint o file in contemporanea, i conflitti sono certi. Ogni sub-agente deve operare su scope isolati, con l'orchestratore che gestisce il merge dei risultati.
Terzo errore: logging insufficiente. In produzione, ogni chiamata deve loggare timestamp, tool_use richiesti, token consumati e output ricevuto. Senza questo layer di osservabilità, il debug richiede ore. Con questo, è una query sul log.
Da Dove Partire
L'architettura multi-agente non è complessità gratuita. È il modo corretto di scalare un sistema AI quando la context window è il vincolo e la qualità costante è il requisito.
Claude Agent SDK fornisce la struttura. Python fornisce la flessibilità. Il pattern orchestratore con sub-agenti specializzati fornisce i risultati misurabili.
Se stai ancora costruendo automazioni su agente singolo con prompt lunghi, il limite lo stai già toccando. Il passo successivo è la separazione delle responsabilità tra layer specializzati, ognuno ottimizzato per il suo compito.
Per approfondire i fondamentali prima di costruire pipeline complessi, la guida Claude Mastery copre dieci moduli essenziali: dall'architettura degli agenti alla gestione della context window in produzione.