Affidarsi a una singola sessione di AI per workflow complessi e multidominio è per natura lento. I team di agenti Claude risolvono il problema eseguendo agent specializzati in parallelo e producendo risultati più approfonditi a velocità molto superiori. Questa guida spiega come funzionano i team di agenti Claude Code, come configurarli e le migliori pratiche per ricavarne il massimo valore.
Che cosa sono i team di agenti Claude
I team di agenti Claude Code sono un sistema di coordinamento multi-istanza in cui più sessioni Claude lavorano in parallelo sulla stessa codebase. Una sessione viene designata come lead agent, riceve il compito complessivo, lo scompone in sottoattività e sintetizza l’output finale. Gli altri sub-agent sono compagni: ciascuno opera nella propria finestra di contesto isolata, possiede una parte distinta del lavoro e comunica direttamente con gli altri compagni.
Vantaggi dei team di agenti
I team di agenti si differenziano dai tipici assistenti AI perché questi elaborano le attività in sequenza, una alla volta. I team di agenti superano questo vincolo: quando il lavoro può essere davvero parallelizzato, il tempo effettivo si riduce di conseguenza.
Al tempo stesso, i team di agenti sono più di semplici sessioni multiple, perché il livello di coordinamento aggiunge tre capacità che il lavoro manuale multi-sessione non ha:
Messaggistica peer-to-peer: i compagni possono inviarsi messaggi direttamente, senza passare da te o dal lead. Per esempio, in un team di agenti con un revisore della sicurezza, quest’ultimo può segnalare un risultato al revisore delle performance durante l’esecuzione senza bloccare l’intero team.
Blocco dei file: quando un compagno scrive su un file, acquisisce un lock che impedisce scritture concorrenti da parte di altri agent. Questo evita la classe di conflitti di merge dovuta a sovrascritture silenziose.
Tracciamento delle dipendenze: il lead codifica le dipendenze tra attività durante la scomposizione. Il livello di coordinamento le applica, così nessun agent parte prima che i prerequisiti siano soddisfatti, senza controlli manuali.
Come funzionano davvero i team di agenti
Un team di agenti è composto dai seguenti elementi, ciascuno con un ruolo specifico:
Il team lead è la sessione principale di Claude Code. Crea il team, avvia i compagni, coordina il lavoro tra loro e sintetizza il risultato finale. È la sessione con cui interagisci direttamente.
I compagni sono istanze Claude Code separate, ciascuna impegnata in modo indipendente sui compiti assegnati all’interno della propria finestra di contesto. Non condividono il contesto con il lead né tra loro; la comunicazione avviene esplicitamente, tramite l’elenco attività e la mailbox.
L’elenco attività condiviso e la mailbox abilitano il coordinamento**.** L’elenco attività condiviso è una coda live da cui il gruppo di agent legge e su cui scrive. Il lead la popola al momento della scomposizione, mentre i compagni prendono in carico le attività, le svolgono e le segnano come completate. Le dipendenze vengono applicate automaticamente: quando un compagno completa un’attività, quelle che erano bloccate da essa si sbloccano senza intervento manuale. La mailbox è il sistema di messaggistica per la comunicazione diretta da agent ad agent. I messaggi scorrono automaticamente tra compagni e lead.
Sia la configurazione del team sia l’elenco attività sono archiviati localmente (~/.claude/teams/ e ~/.claude/tasks/). Claude Code genera e mantiene automaticamente questi file. Non modificarli a mano: qualsiasi cambiamento verrà sovrascritto al successivo aggiornamento dello stato.
Come configurare i team di agenti Claude Code
I team di agenti Claude sono disattivati per impostazione predefinita in Claude Code. Sono etichettati come sperimentali e richiedono un opt-in esplicito. Ecco il percorso di configurazione completo. Prima di abilitarli, verifica che la tua versione di Claude Code sia la v2.1.32 o successiva**.** Puoi eseguire claude --version nel terminale per controllare.
Passaggio 1: abilita il feature flag
Imposta la variabile d’ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS su 1. Puoi farlo in tre modi:
Opzione A: ~/.claude/settings.json (consigliata)
Opzione B: profilo shell (~/.bashrc o ~/.zshrc)
Opzione C: inline, per una singola sessione
Se hai modificato settings.json o il profilo della shell, riavvia Claude Code perché il flag abbia effetto.
Passaggio 2: installa tmux (consigliato, non obbligatorio)
I team di agenti possono essere visualizzati in due modalità: in-process (tutti i compagni vengono eseguiti nel terminale principale) e pannelli affiancati (ogni compagno ha il proprio pannello, che richiede tmux o iTerm2). Eseguire ogni compagno nel proprio pannello del terminale rende molto più semplice monitorare il team in tempo reale.
Per restare sicuramente in modalità pannelli affiancati, imposta teammateMode in ~/.claude/settings.json:
Per sostituire l’impostazione predefinita "auto", imposta teammateMode in ~/.claude/settings.json su in-process. Per forzare la modalità in-process per una singola sessione, passala come flag: claude --teammate-mode in-process.
Passaggio 3: usa un prompt per avviare il tuo team di agenti
Dopo aver abilitato il team di agenti, indica semplicemente a Claude in linguaggio naturale quali attività, deliverable e struttura di team vuoi. Puoi specificare ciascun ruolo nel prompt e Claude creerà il team, avvierà i compagni e pianificherà le attività di conseguenza.
Prompt di esempio:
Puoi specificare quale modello useranno i tuoi team di agenti, ad esempio "Use Sonnet for every teammate". I compagni non ereditano il modello del lead agent. Gli utenti devono specificare il modello nel frontmatter del file di ruolo oppure impostare un modello predefinito per i compagni tramite /config.
Passaggio 4: richiedi l’approvazione del piano per attività complesse (facoltativo)
Per attività ad alto rischio e complesse, puoi richiedere al team di redigere un piano prima dell’esecuzione. I compagni nel gruppo di agent lavoreranno in modalità sola lettura, mentre il lead esaminerà, rivedrà e infine approverà il piano. Solo dopo l’approvazione del lead i compagni inizieranno l’implementazione.
Tieni presente che sarà il lead agent a prendere le decisioni, quindi puoi anche fornire criteri decisionali.
Prompt di esempio:
Passaggio 5: configura i worktree git per isolare i file (facoltativo, consigliato)
Se qualche compagno scrive file, i worktree Claude Code sono vivamente consigliati. Un git worktree è una directory di lavoro separata su un proprio branch, che condivide la stessa cronologia .git del checkout principale. Ogni agent ottiene accesso isolato ai file e le modifiche di un worktree non toccano mai il lavoro in corso di un altro agent.
Per abilitarlo per singolo agent, aggiungi semplicemente isolation: worktree al frontmatter YAML dell’agent. Claude Code prepara un worktree nuovo per ogni invocazione parallela di agent e lo ripulisce automaticamente al termine.
Per l’uso da CLI: claude --worktree o claude -w avvia una sessione nel proprio worktree. L’app desktop crea automaticamente un worktree Claude Code per ogni sessione.
Passaggio 6: monitora a intervalli regolari
I team di agenti non sono da impostare e dimenticare: quelli che restano in esecuzione a lungo possono deviare. Gli agent possono bloccarsi su prompt di autorizzazione, segnare attività come completate troppo presto o perdere di vista l’ambito. Puoi controllare ogni 10–15 minuti e rivedere l’elenco attività condiviso per individuare compiti bloccati o non presi in carico. Se un’attività non avanza da 20–30 minuti, potrebbe dipendere da un blocco di autorizzazioni o da un ruolo definito male che richiede intervento manuale.
Confronto affiancato: subagent e team di agenti
I subagent seguono un modello di delega. I team di agenti seguono un modello di collaborazione. La differenza incide su tutto, dalla gestione del contesto al costo di un’esecuzione.
| Subagent | Team di agenti | |
|---|---|---|
| Comunicazione | Unidirezionale: il lead assegna, i subagent riportano i risultati | Peer-to-peer + coordinamento del lead |
| Stato condiviso | Nessuno | Elenco attività condiviso con tracciamento delle dipendenze |
| Finestre di contesto | Finestra di contesto propria; i risultati tornano al lead | Ogni compagno ha la propria (fino a 1M token) |
| Prevenzione dei conflitti sui file | Non integrata | Blocco dei file incluso |
| Costo in token | Inferiore | Superiore (ogni compagno è una singola istanza) |
| Ripresa della sessione | Supportata | /resume and /rewind don't restore in-process teammates |
| Agent annidati | Supportati | Non supportati; solo il lead può avviare i compagni |
| Ideale per | Delega mirata, workflow ripetibili | Lavori parallelizzabili, interdipendenti e multidominio |
I subagent seguono un modello di delega unidirezionale: il lead invia un’attività, il subagent la esegue nella propria finestra di contesto e il risultato viene restituito. Non ci sono stato condiviso, comunicazione diretta tra agent fratelli né livello di coordinamento: solo un ciclo pulito di invio e ritorno.
I team di agenti lavorano su un elenco attività condiviso con applicazione automatica delle dipendenze e comunicano peer-to-peer tra compagni tramite la mailbox.
In breve, i team di agenti rendono davvero quando il lavoro è suddiviso in flussi paralleli realmente indipendenti, che devono condividere risultati e coordinarsi. Per risultati rapidi, attività sequenziali, modifiche a un solo file o situazioni in cui la prevedibilità dei costi conta più della velocità, i subagent sono la scelta migliore.
Quando scegliere i team di agenti e quando i subagent
Usa i team di agenti quando:
I compagni devono comunicare direttamente tra loro
Il lavoro richiede un elenco attività condiviso con tracciamento delle dipendenze tra flussi paralleli
L’attività è troppo ampia per una singola sessione e ogni worker ha bisogno di un contesto completamente indipendente
Usa i subagent quando:
Ti serve solo il riepilogo finale, non tutto l’output intermedio
Il lavoro è abbastanza circoscritto da restituire un risultato pulito
Vuoi limitare gli strumenti o instradare il lavoro verso un modello meno costoso
Hai bisogno di percorsi di ricerca paralleli che non dipendono l’uno dall’altro
Se non riesci a individuare almeno tre flussi di lavoro paralleli realmente indipendenti, una singola sessione o i subagent probabilmente supereranno un team di agenti, a costi inferiori.
Casi d’uso reali per i team di agenti
Quando il lavoro si divide naturalmente in flussi definiti e delimitati, questi possono procedere senza attendersi a vicenda (oppure le dipendenze possono essere codificate esplicitamente) e il costo di coordinamento è contenuto rispetto al tempo risparmiato dall’esecuzione in parallelo. Ecco cinque casi d’uso in cui i team di agenti superano una singola sessione.
Code review parallela
Assegna contemporaneamente tre revisori a una pull request, includendo un agent per la sicurezza, un agent per le prestazioni e un agent per la copertura dei test. Il lead sintetizza tre report paralleli in un unico elenco di azioni prioritarie. Questo schema funziona anche per revisioni architetturali (agent per scalabilità, sicurezza e manutenibilità) o controlli di conformità su diversi framework normativi.
Debug basato su ipotesi concorrenti
Avvia cinque agent, ciascuno con una singola ipotesi, per esaminare file o log specifici relativi a un bug in produzione. Il primo agent che conferma la propria ipotesi fa emergere la correzione e gli altri possono essere fermati. È un approccio più efficiente che analizzare ogni teoria in sequenza, passare ore a seguire una pista, tornare indietro e iniziare la successiva.
Refactor cross-layer
Un’attività di refactor cross-layer contiene passaggi sia sequenziali sia paralleli. Per esempio, una modifica API incompatibile richiede aggiornamenti agli endpoint backend, ai componenti frontend che li consumano e alla suite di test che copre entrambi. Il lavoro backend deve essere completato prima che il frontend possa iniziare. Una volta avviata l’attività backend, l’agent della suite di test può iniziare in parallelo a predisporre la nuova struttura dei test. In un team di agenti, il lead usa il tracciamento delle dipendenze dell’elenco attività condiviso per codificare quest’ordine.
Ricognizione di ricerca senza contaminazione del contesto
Una decisione tecnica può richiedere l’esame di più insiemi di evidenze indipendenti, per esempio scegliere un motore di database, valutare tre API di terze parti e analizzare gli strumenti di build. Assegna a ogni agent un dominio non sovrapposto, e ognuno pubblicherà un riepilogo strutturato. Il lead aggrega tutto in un documento comparativo. L’isolamento preserva prospettive indipendenti, migliorando la qualità dei risultati.
Migrazione di codebase di grandi dimensioni
L’aggiornamento di una dipendenza importante in una codebase ampia di solito comporta interventi su più moduli. Se quei moduli hanno confini netti e possono migrare contemporaneamente, i team di agenti aiutano. Assegna un agent a ciascun modulo indipendente: ogni agent migra il proprio modulo, esegue la propria suite di test e riporta un riepilogo della migrazione che include eventuali interfacce modificate. Il lead rivede le modifiche alle interfacce prima di dichiarare completata la migrazione e coordina la sequenza di merge.
Cosa fare e cosa evitare nella progettazione del tuo team di agenti
Costruire un sistema di agent parallelo con Claude Code è semplice da configurare, ma è facile sbagliare. Questi sono i principi di progettazione che determinano se il tuo team di agenti produce valore o fa perdere tempo.
Consigli pratici per costruire il tuo sistema di agent parallelo
Pre-approva le autorizzazioni: I compagni partono dalle impostazioni di autorizzazione del lead. Se il lead viene eseguito con --dangerously-skip-permissions, anche tutti i compagni lo ereditano. Puoi modificare le modalità dei singoli compagni dopo averli avviati, ma non è possibile configurarle al momento dello spawn. Definisci la postura delle autorizzazioni tramite il lead prima di lanciare il team.
Scrivi prompt di ruolo precisi: Ogni prompt di ruolo dovrebbe specificare quattro aspetti: cosa fare, su quali file o domini lavorare, su cosa concentrarsi e cosa escludere, e com’è fatto il deliverable. Quando avvii i compagni, puoi fare riferimento a tipi di subagent da qualsiasi ambito subagent: progetto, utente, plugin o definito da CLI. Questo ti permette di definire un ruolo una sola volta, ad esempio revisore della sicurezza o test runner, e riutilizzarlo sia come subagent delegato sia come compagno in un team di agenti.
Applica l’isolamento dei file: Per qualunque agent che scriva su disco, usa l’isolamento. Due agent che modificano simultaneamente lo stesso file sono uno dei modi più sicuri per produrre output corrotti.
Controlla a intervalli prestabiliti: Ogni 10–15 minuti per i team di agenti attivi. Guarda l’elenco attività condiviso per individuare attività ferme. Un’attività bloccata da più di 20–30 minuti può dipendere da un problema di autorizzazioni, da un ruolo definito male o da una dipendenza circolare, e potrebbe richiedere una risoluzione manuale.
Codifica esplicitamente le dipendenze: Se l’Attività B segue logicamente l’Attività A, scrivi quella dipendenza nell’elenco attività al momento della scomposizione, non come istruzione in un prompt di ruolo. Il livello di coordinamento applica automaticamente le dipendenze; le istruzioni nei prompt possono essere fraintese o ignorate.
Definisci i confini di ownership nel tuo file md: Per progetti multi-sessione, scrivi una regola secondo cui ogni modulo o directory ha esattamente un agent responsabile. Questo evita sovrapposizioni prima ancora che il team venga lanciato.
Fai sempre pulizia tramite il lead, non tramite un compagno: Il lead verifica la presenza di compagni attivi prima di liberare le risorse. I compagni non hanno il contesto completo del team per pulire in sicurezza; farlo rischia di lasciare la sessione in uno stato incoerente.
Errori comuni che puoi evitare nel tuo team di agenti
Non avviare un team per un’attività che una singola sessione gestisce senza problemi: Prima di scrivere anche un solo file di ruolo o inviare un solo prompt swarm, disegna il grafo dell’attività. Quali sottoattività sono davvero indipendenti? Quali hanno dipendenze? Il lavoro dipende da una sequenza? Se non riesci a descrivere tre tracce parallele con confini netti, una singola sessione supererà il team.
Non assegnare due agent allo stesso file. È la causa più comune di conflitti di merge e sovrascritture silenziose. Se la scomposizione dell’attività produce due agent che devono intervenire sullo stesso componente, il lavoro su quel componente deve essere sequenziale: assegnalo a un agent dopo che l’altro ha terminato.
Non saltare la pre-approvazione delle autorizzazioni in Claude Code. I prompt di autorizzazione che compaiono a metà esecuzione bloccano l’esecuzione parallela e richiedono intervento manuale. Questo overhead elimina gran parte del beneficio. Pre-approva le scritture su file e i comandi shell per la directory di lavoro prima del lancio.
Non aspettarti di ripristinare il tuo team Claude Code. Se una sessione viene ripulita, /resume e /rewind non ripristinano i compagni in-process. Salva gli output intermedi importanti prima delle esecuzioni lunghe.
Non spingere un team oltre cinque elementi senza una ragione chiara. I costi in token crescono linearmente, ma l’overhead di coordinamento aumenta più in fretta. Tre agent focalizzati con ruoli precisi superano con regolarità cinque agent dai ruoli vaghi. Aggiungi compagni solo quando c’è un flusso parallelo esplicito in attesa, non perché “di più” sembri automaticamente meglio.
Un altro paradigma: costruisci il tuo team multi-agent in Kimi Agent Swarm
I team di agenti Claude Code eccellono negli scenari nativi per sviluppatori, integrandosi a fondo con i workflow da terminale e l’ecosistema Git. Tuttavia, il paradigma della collaborazione multi-agent va ben oltre la riga di comando. Kimi Agent Swarm è il punto in cui questo paradigma diventa accessibile a tutti.
Kimi Agent Swarm è il sistema di collaborazione multi-agent di Kimi, progettato per attività complesse e su larga scala. Scompone un obiettivo ampio in sottoattività distinte e pianifica agent e competenze diverse per gestire simultaneamente ricerca, lettura, analisi, scrittura, coding, generazione di fogli di calcolo, creazione di slide e realizzazione di pagine web. Nessun flag env. Nessuna configurazione git richiesta.
Funzionalità principali di Kimi Agent Swarm
Collaborazione parallela fino a 300 sub-agent: Kimi Agent Swarm scompone un’attività complessa e pianifica più sub-agent per gestire sottoattività simultaneamente. Il sistema può coordinare fino a 300 sub-agent per eseguire oltre 4.000 chiamate a strumenti in una singola run.
Esecuzione composta multi-skill: Lo Swarm può combinare più competenze specialistiche in una singola run, tra cui Ricerca approfondita, pptx, scrittura di report, vibe-coding, creazione di siti web e scrittura di paper, superando un singolo agent per profondità dell’output e copertura dei formati.
Elaborazione documentale su larga scala: Agent Swarm può elaborare in batch file in oltre 20 formati (PDF, Word, Excel, PPT, immagini ecc.), leggendo, estraendo informazioni e riassumendo contenuti in parallelo sull’intero set di documenti, con la possibilità di fare riferimento a librerie, file di competitive intelligence o ingestion di dati multi-source.
Ricerca ampia e proattiva: Per attività che richiedono informazioni su superfici molto estese, Agent Swarm invia sub-agent a cercare sul web, individuare fonti, scaricare contenuti, classificare risultati e generare riepiloghi strutturati in parallelo.
Ragionamento multi-prospettiva: Agent Swarm può eseguire simultaneamente più punti di vista esperti sullo stesso problema. Ne deriva un’analisi più completa rispetto a un passaggio da un solo punto di vista, con l’emersione di punti ciechi che la revisione sequenziale non coglie.
Produzione di contenuti in profondità: L’architettura parallela di Agent Swarm è pensata per output di profondità sostenuta, come report di ricerca di centinaia di pagine, analisi di settore long-form, revisioni della letteratura accademica, guide di apprendimento strutturate e contenuti narrativi estesi.
Output multi-formato in una singola run: Agent Swarm può produrre simultaneamente più tipi di deliverable sulla stessa attività, ad esempio un report PDF, un deck PPT, una pagina web, un dataset Excel e un progetto di codice.
Come eseguire un team di agenti in Kimi Agent Swarm
Passaggio 1: apri Kimi Agent Swarm e inserisci il tuo prompt
Apri la pagina Agent Swarm e descrivi la tua attività nella casella di input. Per risultati migliori, sii specifico su ambito, deliverable attesi ed eventuali vincoli, come intervallo temporale, fonti o requisiti di formato.
Prompt di esempio:
Passaggio 2: lascia lavorare Kimi Agent Swarm
Dopo l’invio del prompt, Agent Swarm scomporrà l’attività in sottoattività e invierà subagent a lavorare in parallelo. Puoi seguire l’avanzamento in tempo reale, inclusi pianificazione delle attività, avvio dei sub-agent ed esecuzione parallela.
Passaggio 3: ricevi, visualizza in anteprima, scarica o condividi i risultati
Una volta completata la run, i tuoi deliverable sono pronti per l’anteprima direttamente nell’interfaccia. A seconda dell’attività, gli output possono includere report di ricerca, analisi dei dati, deck PPT, pagine web, progetti di codice o una combinazione di questi elementi. Puoi scaricare i file e condividerli direttamente.
Casi d’uso in cui Kimi Agent Swarm dà il meglio
Redazione di offerte e proposte: Assegna agent paralleli a specifiche tecniche, requisiti di conformità, modelli di prezzo e case study simultaneamente; l’orchestratore li integra in una proposta coerente.
Analisi finanziaria: Assegna agent paralleli a dati di mercato, documenti dei concorrenti, indicatori macro e modelli interni; l’orchestratore li sintetizza in un’analisi unificata.
Ricerca business: Assegna agent paralleli a panorami competitivi, interviste ai clienti, report di settore e contesto normativo da fonti diverse; l’orchestratore produce un output strutturato.
Test di sicurezza: Esegui agent paralleli per ricognizione, scansione delle vulnerabilità, audit delle dipendenze e controlli di escalation dei privilegi; l’orchestratore aggrega i risultati in un report finale.
Sviluppo full-stack: Crea agent paralleli per componenti frontend, endpoint backend, schema del database e suite di test; l’orchestratore coordina l’integrazione sull’intero stack.
Conclusione
I team di agenti Claude Code sono progettati appositamente per i workflow di engineering, portando l’esecuzione parallela su codebase complesse direttamente dal terminale. Se il tuo lavoro va oltre il codice, Kimi Agent Swarm porta lo stesso paradigma multi-agent a ricerca, analisi, contenuti e molto altro. Descrivi semplicemente la tua attività e lascia che lo swarm si occupi del resto.