Orchestrare team di agenti

Orchestrare team di agenti

Come coordinare istanze multiple di Claude Code per sviluppare software complesso in parallelo: architettura, configurazione, casi d’uso pratici e best practice per sviluppatori.

Indice dei contenuti – Orchestrare team di agenti

1. Che cos’è un team di agenti AI?
2. Architettura: Team Lead, Teammates e Task List
3. Agent Teams vs Subagents: quando usare cosa
4. Configurazione e primo avvio
5. Casi d’uso pratici con esempi di codice
6. Best practice, pro e contro
7. Il futuro dell’orchestrazione multi-agente
8. Conclusioni: formarsi per restare competitivi

1. Che cos’è un team di agenti AI? Orchestrare team di agenti

Negli ultimi anni il paradigma dello sviluppo software assistito dall’intelligenza artificiale è cambiato radicalmente. Non si tratta più di semplici suggerimenti di codice inline: strumenti come Claude Code di Anthropic permettono oggi di delegare interi flussi di lavoro a sessioni autonome che leggono e scrivono file, eseguono test, effettuano commit e si coordinano con altre sessioni. Il risultato è quello che viene chiamato un team di agenti.

Un team di agenti è un gruppo di istanze di Claude Code che lavorano in parallelo su uno stesso progetto. Ogni istanza ha il proprio context window — ovvero la propria “memoria di lavoro” — e riceve compiti specifici. Una sessione principale, chiamata team lead, si occupa di coordinare il lavoro, assegnare task e sintetizzare i risultati. Le sessioni subordinate, dette teammates, operano in modo indipendente ma possono comunicare tra loro e con il lead attraverso un sistema di messaggistica interno.

Il lancio ufficiale della funzionalità, avvenuto il 6 febbraio 2026 in concomitanza con il rilascio di Claude Opus 4.6, ha segnato un passo importante verso quello che molti esperti definiscono il passaggio dal modello “conductor” al modello “orchestrator”: non più un singolo agente AI guidato passo per passo, ma un vero ensemble di agenti specializzati che lavorano in modo asincrono mentre lo sviluppatore supervisiona e ridefinisce le priorità.

2. Architettura: Team Lead, Teammates e Task List

Per capire come funziona un team di agenti in Claude Code è utile esaminarne i componenti fondamentali:

Team Lead: è la sessione principale di Claude Code che crea il team, avvia i teammates e coordina l’intero flusso di lavoro. Il lead mantiene una visione d’insieme, gestisce le dipendenze tra task e sintetizza i risultati finali.

Teammates: sono istanze separate di Claude Code, ciascuna con il proprio context window indipendente. Ogni teammate riceve un task specifico, può richiedere strumenti aggiuntivi e comunicare direttamente con gli altri teammates senza passare obbligatoriamente per il lead.

Task List condivisa: è l’elenco dei lavori da svolgere, accessibile da tutti gli agenti del team. I task hanno tre stati: pending (in attesa), in progress (in lavorazione) e completed (completato). I task possono avere dipendenze reciproche: un task bloccato non può essere avviato fino al completamento di quelli da cui dipende.

Mailbox: è il sistema di messaggistica interno che consente la comunicazione peer-to-peer tra gli agenti. I messaggi vengono consegnati automaticamente senza polling manuale.

La configurazione del team viene salvata localmente nella directory ~/.claude/teams/{team-name}/config.json, mentre la task list è in ~/.claude/tasks/{team-name}/. Questi file vengono generati e aggiornati automaticamente da Claude Code: non è consigliato modificarli manualmente, poiché vengono sovrascritti a ogni aggiornamento di stato.

Dal punto di vista della visualizzazione, la funzionalità supporta due modalità:

• In-process: tutti i teammates girano nel terminale principale; con Shift+Down si scorre tra le sessioni attive.
• Split panes: ogni teammate ha il proprio pannello separato (richiede tmux oppure iTerm2 su macOS).

3. Agent Teams vs Subagents: quando usare cosa – Orchestrare team di agenti

Claude Code supporta anche i subagents, un meccanismo di parallelizzazione più leggero disponibile già da versioni precedenti. La distinzione tra le due modalità è fondamentale per scegliere l’approccio corretto:

Subagents

Vengono avviati all’interno di una singola sessione e possono solo restituire risultati al main agent. Non si parlano tra loro e non hanno una task list condivisa. Sono la scelta ideale per task focalizzati in cui conta solo il risultato finale, non il processo di coordinazione. Il costo in token è inferiore, perché i risultati vengono sintetizzati nel context del chiamante.

Agent Teams

Ogni teammate è una sessione completamente indipendente. Possono comunicare direttamente tra loro, condividere scoperte a metà lavoro e auto-coordinarsi tramite la task list. Richiedono significativamente più token (ogni teammate è una istanza separata di Claude), ma sono lo strumento giusto per lavori complessi che richiedono collaborazione, dibattito tra ipotesi alternative e coordinazione multi-livello (frontend, backend, test).

Regola pratica: usa i subagents per delegare task ripetitivi o paralleli indipendenti. Usa gli agent teams quando i tuoi “colleghi AI” devono confrontarsi, sfidarsi e convergere su una soluzione comune.

4. Configurazione e primo avvio – Orchestrare team di agenti

La funzionalità Agent Teams è disponibile a partire da Claude Code v2.1.32. Verifica la tua versione con:

claude --version

Essendo ancora sperimentale, è disabilitata di default. Per attivarla, aggiungi la variabile d’ambiente al file di configurazione ~/.claude/settings.json:

{

  "env": {

    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"

  }

}

In alternativa, puoi esportarla direttamente nella shell prima di avviare Claude Code:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Se preferisci la modalità split panes per avere ogni teammate in un pannello separato, assicurati di avere tmux installato (su macOS con Homebrew: brew install tmux). Poi specifica la modalità nel settings.json:

{

  "teammateMode": "tmux"

}

Per forzare la modalità in-process in una singola sessione senza modificare la configurazione:

claude --teammate-mode in-process

5. Casi d’uso pratici con esempi di codice

5.1 Code review parallela per specializzazione

Uno degli usi più immediati degli agent teams è distribuire una code review su più dimensioni contemporaneamente. Invece di affidarsi a un unico revisore che tende a concentrarsi su un tipo di problema per volta, si possono creare tre teammates con lens distinte:

Create an agent team to review PR #142. Spawn three reviewers:

- One focused on security implications (input validation, token handling, session mgmt)

- One checking performance impact (queries N+1, memory leaks, async patterns)

- One validating test coverage (unit tests, edge cases, integration tests)

Have them each review and report findings to a shared findings.md file.

Ogni reviewer lavora in parallelo sullo stesso PR con un filtro diverso. Il lead sintetizza i risultati al termine.

5.2 Debug con ipotesi competitive

Quando la causa di un bug è poco chiara, un singolo agente tende a trovare la prima spiegazione plausibile e fermarsi, un fenomeno noto come anchoring bias. Creare teammates che si sfidano attivamente tra loro rompe questo pattern:

Users report the app disconnects after one message.

Spawn 4 agent teammates to investigate competing hypotheses:

- Teammate 1: WebSocket timeout/heartbeat misconfiguration

- Teammate 2: Memory leak causing server-side crash

- Teammate 3: Reverse proxy (nginx) forcefully closing idle connections

- Teammate 4: Client-side event loop blocking

Have them debate and try to disprove each other's theories.

Update findings.md with the consensus root cause.

La struttura del dibattito è il meccanismo chiave: la teoria che sopravvive allo scrutinio degli altri agenti ha molte più probabilità di essere la causa reale.

5.3 Sviluppo di feature cross-layer

Per refactoring o nuove funzionalità che toccano più layer (API, database, test), si può assegnare ogni layer a un teammate dedicato, evitando conflitti sullo stesso file:

Create an agent team to refactor the payment module.

Spawn three teammates:

- API teammate: own src/api/payments/ — update endpoints and DTOs

- DB teammate: own src/db/migrations/ — update schema and queries

- Test teammate: own tests/payments/ — update and add integration tests

Use Claude Sonnet for each teammate.

Require plan approval before any teammate makes changes.

La direttiva “require plan approval” è particolarmente utile in contesti aziendali: ogni teammate pianifica prima di agire, il lead rivede i piani e li approva o respinge con feedback. Solo dopo l’approvazione i teammates entrano in modalità esecuzione.

6. Best practice, pro e contro

Best practice operative

La documentazione ufficiale di Anthropic e l’esperienza della community nel 2026 convergono su alcune indicazioni pratiche:

• Dimensione ottimale del team: 3-5 teammates per la maggior parte dei workflow. Oltre tale soglia il costo di coordinazione supera il beneficio della parallelizzazione.
• Granularità dei task: ogni task dovrebbe produrre un deliverable chiaro e autonomo — una funzione, un file di test, una sezione di documentazione. Task troppo piccoli aumentano l’overhead; task troppo grandi aumentano il rischio di lavoro sprecato.
• Contestualizzare i teammates: ogni teammate riceve il contesto del progetto da CLAUDE.md e MCP server, ma non eredita la cronologia della sessione principale. Includi dettagli specifici nel prompt di avvio.
• Evitare conflitti di file: due teammates non dovrebbero mai modificare lo stesso file simultaneamente. Struttura i task in modo che ogni agente possieda un insieme distinto di file.
• Monitorare e redirigere: non lasciare mai un team senza supervisione per troppo tempo. Controlla i progressi, ridefinisci gli approcci che non funzionano, sintetizza i risultati man mano che arrivano.
• Usare hooks per quality gate: i hook TeammateIdle, TaskCreated e TaskCompleted permettono di implementare controlli automatici di qualità (es. bloccare il completamento di un task se i test non passano).

Pro dell’approccio multi-agente

• Drastica riduzione dei tempi per lavori parallelizzabili: ricerche, review e sviluppo di moduli indipendenti.
• Esplorazione simultanea di approcci alternativi: il debug con ipotesi competitive produce soluzioni più robuste.
• Comunicazione peer-to-peer tra agenti: i teammates si segnalano dipendenze e scoperte senza intermediari.
• Integrazione nativa in Claude Code: nessuna dipendenza esterna o script fragili da mantenere.
• Approvazione dei piani prima dell’esecuzione: meccanismo di controllo qualità integrato.

Contro e limitazioni attuali

• Costo token elevato: ogni teammate è un’istanza separata con il proprio context window. Il costo scala linearmente con il numero di agenti attivi.
• Funzionalità sperimentale: al momento non è possibile riprendere sessioni in-process con /resume, i team nidificati (teammate che avviano propri team) non sono supportati, e lo shutdown può essere lento.
• Overhead di coordinazione: per task sequenziali, su singoli file o con molte dipendenze, una sessione singola o i subagents sono più efficienti.
• Ritardi nella sincronizzazione dei task: i teammates a volte non marcano correttamente i task come completati, richiedendo intervento manuale.
• Split panes non supportato su tutti i terminali: VS Code integrated terminal, Windows Terminal e Ghostty non supportano la modalità tmux.

7. Il futuro dell’orchestrazione multi-agente

Il 2026 ha consolidato un cambiamento di paradigma che era nell’aria da mesi: il mercato si sta muovendo rapidamente verso architetture in cui lo sviluppatore non è più il “pilota” di un singolo agente, ma l'”orchestratore” di un team di agenti specializzati.

Gli esperti del settore identificano tre livelli di utilizzo che si stanno affermando. Il primo livello riguarda le sessioni interattive da terminale, adatte per lavori veloci con pochi agenti. Il secondo livello include strumenti di orchestrazione locali con dashboard visive e controllo integrato sui diff, ideali per sprint paralleli su codebase consolidate. Il terzo livello, quello asincrono e cloud-based, permette di delegare task complessi e ritrovare pull request già pronte al termine della giornata.

La maggior parte degli sviluppatori nel 2026 utilizza tutti e tre i livelli in modo complementare, a seconda della complessità del task e del grado di supervisione richiesto. Anthropic non è l’unica a muoversi in questa direzione: GitHub Copilot integra già agenti Claude e Codex in un’unica interfaccia unificata, e altri attori come Google Jules e OpenAI Codex stanno sviluppando soluzioni analoghe.

Le competenze che distingueranno gli sviluppatori senior nel prossimo futuro non saranno solo la capacità di scrivere codice, ma l’abilità di decomporre problemi complessi in task autonomi, definire ruoli per gli agenti, gestire dipendenze e verificare i risultati. Chi costruisce oggi la propria “memoria muscolare” nell’orchestrazione di agent teams avrà un vantaggio competitivo significativo man mano che questi strumenti matureranno.

8. Conclusioni: formarsi per restare competitivi

Il mercato dello sviluppo software è in continua e rapida evoluzione. Nuovi strumenti, paradigmi e best practice emergono ogni settimana, e la distanza tra chi sa usare gli agent teams in modo efficace e chi si limita a una singola sessione AI si allargherà progressivamente. L’unico modo sostenibile per mantenere il proprio team aggiornato e competitivo è investire nella formazione continua degli sviluppatori.

Comprendere come orchestrare team di agenti non è solo una questione tecnica: richiede un cambio di mentalità, dalla guida passo-per-passo alla definizione di architetture, vincoli e criteri di qualità che gli agenti possono eseguire in modo autonomo. Questa competenza si costruisce con la pratica guidata, non con la sola lettura della documentazione.

Innovaformazione propone il Corso Claude Code per Sviluppatori, pensato specificamente per team aziendali che vogliono portare queste competenze all’interno della propria organizzazione, con percorsi formativi strutturati e orientati all’applicazione pratica immediata.

Il corso copre l’intero workflow di Claude Code, dalla configurazione avanzata all’utilizzo degli agent teams, dalla definizione di subagents personalizzati all’integrazione con i sistemi aziendali tramite MCP. I partecipanti impareranno a impostare task list efficaci, gestire permessi e hooks di qualità, monitorare e ottimizzare i costi token.

Grazie all’accesso a Fondimpresa, le aziende possono finanziare la formazione dei propri dipendenti attraverso i fondi interprofessionali, rendendo l’investimento formativo ancora più accessibile e pianificabile nel bilancio aziendale.

Per informazioni sul corso, sui moduli disponibili e per richiedere un preventivo personalizzato per la tua azienda, contatta direttamente:

Dario Carrassi — Innovaformazione

Email: info@innovaformazione.net

Tel: 347 101 2275

Scopri il catalogo Corsi AI Generativa.

Per altri articoli tecnici di settore consigliamo invece di navigare sul nostro blog QUI.

(fonte) (fonte) (fonte)