Orchestrare team di sessioni Claude Code

Coordinare più istanze di Claude Code che lavorano insieme come un team, con attività condivise, messaggistica tra agenti e gestione centralizzata.

[!WARNING]

I team di agenti sono sperimentali e disabilitati per impostazione predefinita. Abilitateli impostando CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 nel vostro settings.json o nell'ambiente. Senza quella variabile, nessun team viene configurato all'avvio della sessione, nessuna directory di team viene scritta, e Claude non genera o propone compagni di team. I team di agenti hanno limitazioni note relative alla ripresa della sessione, al coordinamento delle attività e al comportamento di arresto.

I team di agenti vi permettono di coordinare più istanze di Claude Code che lavorano insieme. Una sessione agisce come il team lead, coordinando il lavoro, assegnando attività e sintetizzando i risultati. I compagni di team lavorano indipendentemente, ognuno nel proprio context window, e comunicano direttamente tra loro. Potete anche parlare direttamente con qualsiasi compagno di team senza passare attraverso il lead.

Prima di configurare un team, verificate se un'opzione più leggera fa il lavoro. I Subagents lavorano all'interno di una singola sessione, e con la messaggistica tra sessioni Claude può passare i risultati tra le sessioni che eseguite voi stessi.

Quando utilizzare i team di agenti

I team di agenti sono più efficaci per attività in cui l'esplorazione parallela aggiunge valore reale. Consultate gli esempi di casi d'uso per scenari completi. I casi d'uso più forti sono:

• Ricerca e revisione: più compagni di team possono investigare diversi aspetti di un problema simultaneamente, quindi condividere e mettere in discussione i risultati reciproci
• Nuovi moduli o funzionalità: i compagni di team possono possedere ciascuno un pezzo separato senza interferire l'uno con l'altro
• Debug con ipotesi concorrenti: i compagni di team testano diverse teorie in parallelo e convergono sulla risposta più velocemente
• Coordinamento tra livelli: modifiche che si estendono su frontend, backend e test, ciascuno posseduto da un diverso compagno di team

I team di agenti aggiungono overhead di coordinamento e utilizzano significativamente più token di una singola sessione. Funzionano meglio quando i compagni di team possono operare indipendentemente. Per attività sequenziali, modifiche dello stesso file o lavoro con molte dipendenze, una singola sessione o i subagents sono più efficaci.

Confronto con i subagents

Sia i team di agenti che i subagents vi permettono di parallelizzare il lavoro, ma operano diversamente. Per sessioni separate che si passano messaggi l'una con l'altra senza un team, consultate la messaggistica tra sessioni.

I subagents riportano i risultati al main agent. Nei team di agenti, i compagni di team condividono un elenco di attività, rivendicano il lavoro e comunicano direttamente tra loro.

Utilizzate i subagents quando avete bisogno di worker veloci e focalizzati che riportino indietro. Utilizzate i team di agenti quando i compagni di team devono condividere i risultati, mettersi in discussione e coordinarsi autonomamente.

Abilitare i team di agenti

I team di agenti sono disabilitati per impostazione predefinita. Abilitateli impostando la variabile di ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS a 1, sia nell'ambiente della shell che tramite settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

L'abilitazione dei team di agenti modifica anche la delega ordinaria. Claude può denominare un subagente autonomamente, e mentre i team di agenti sono abilitati, un subagente che Claude denomina si avvia come un compagno di squadra, quindi i team possono formarsi anche quando non ne avete richiesto uno. Per ulteriori informazioni, consultate Come Claude avvia i team di agenti; per disattivare il comportamento, consultate Claude genera compagni di squadra invece di subagenti.

L'avvio di compagni di squadra richiede anche una sessione interattiva. In modalità non interattiva con il flag -p, incluse le sessioni di Agent SDK, Claude non genera compagni di squadra, e un subagente che Claude denomina viene eseguito come un ordinario subagente anche con i team di agenti abilitati.

Avviare il vostro primo team di agenti

Dopo aver abilitato i team di agenti, descrivete il compito e i compagni di team che desiderate in linguaggio naturale. Claude li genera e coordina il lavoro in base al vostro prompt.

Questo esempio funziona bene perché i tre ruoli sono indipendenti e possono esplorare il problema senza aspettarsi l'uno l'altro:

Sto progettando uno strumento CLI che aiuta gli sviluppatori a tracciare i commenti TODO
nel loro codebase. Genera tre compagni di team per esplorare questo da diversi angoli: uno
su UX, uno su architettura tecnica, uno che gioca l'avvocato del diavolo.

Da lì, Claude popola un elenco di attività condiviso in una sessione che dispone dei Task tools, genera compagni di team per ogni prospettiva, li fa esplorare il problema, e sintetizza i risultati al termine.

Claude a volte potrebbe utilizzare subagenti invece di creare un team. I subagenti appaiono nello stesso pannello dell'agente dei compagni di team, quindi il pannello da solo non conferma che un team si sia formato. Se Claude ha generato subagenti invece, chiedete di nuovo e richiedete esplicitamente un team di agenti.

Il terminale del lead elenca i compagni di team nel pannello dell'agente sotto l'input del prompt. Dal pannello:

• Frecce su e giù: selezionare un compagno di team
• Invio: aprire la trascrizione del compagno di team selezionato e messaggiargli direttamente
• Escape: cancellare la selezione. Mentre state visualizzando la trascrizione di un compagno di team, Escape interrompe il turno corrente di quel compagno di team

La riga di un compagno di team inattivo rimane nel pannello mentre qualsiasi compagno di team o subagent è ancora al lavoro, quindi puoi selezionarla per rivedere la sua trascrizione o assegnargli altro lavoro. Una volta che ogni agente nel pannello è inattivo, le righe inattive si nascondono dopo 30 secondi e riappaiono al turno successivo del compagno di team; il compagno di team rimane in esecuzione e raggiungibile mentre è nascosto.

Quando più di tre compagni di team sono inattivi contemporaneamente, le righe oltre le prime tre si comprimono in una singola riga che conta i compagni di team compressi, come 2 idle agents quando cinque sono inattivi. Selezionatela e premete Invio per espandere le righe compresse, oppure premete Esc per comprimerle di nuovo. I compagni di team al lavoro, i compagni di team non riusciti, e il compagno di team che state visualizzando mantengono sempre le loro righe proprie.

Se desiderate che ogni compagno di team sia in un riquadro diviso proprio, consultate Scegliere una modalità di visualizzazione.

Controllare il vostro team di agenti

Dite al lead cosa desiderate in linguaggio naturale. Gestisce il coordinamento del team, l'assegnazione delle attività e la delega in base alle vostre istruzioni.

Scegliere una modalità di visualizzazione

I team di agenti supportano due modalità di visualizzazione:

• In-process: tutti i compagni di team vengono eseguiti all'interno del vostro terminale principale. Utilizzate i tasti freccia su e giù nel pannello dell'agente per selezionare un compagno di team, quindi premete Invio per visualizzarlo e digitate per messaggiarlo direttamente. Funziona in qualsiasi terminale, nessuna configurazione extra richiesta.
• Split panes: ogni compagno di team ottiene il proprio riquadro. Potete vedere l'output di tutti contemporaneamente e fare clic su un riquadro per interagire direttamente. Richiede tmux o iTerm2.

[!NOTE]

tmux ha limitazioni note su certi sistemi operativi e tradizionalmente funziona meglio su macOS. Utilizzare tmux -CC in iTerm2 è il punto di ingresso suggerito in tmux.

L'impostazione predefinita è "in-process". Impostate "auto" per abilitare split panes quando state già eseguendo all'interno di una sessione tmux, o quando il vostro terminale è iTerm2 con la CLI it2 installata, altrimenti ricadete in in-process. L'impostazione "tmux" abilita la modalità split-pane e rileva automaticamente se utilizzare tmux o iTerm2 in base al vostro terminale.

Impostate "iterm2" per utilizzare esplicitamente i split panes nativi di iTerm2. Questa modalità richiede la CLI it2 e mostra un errore con il comando di installazione se it2 è mancante. Il prompt di configurazione che offre di installare it2 o passare a tmux appare sotto "auto" o "tmux" quando il vostro terminale è iTerm2 e tmux è disponibile come fallback.

Per sovrascrivere l'impostazione predefinita, impostate teammateMode in ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

Per impostare la modalità per una singola sessione, passatela come flag:

claude --teammate-mode auto

La modalità --teammate-mode è sperimentale e non appare in claude --help.

La modalità split-pane richiede tmux o iTerm2 con la CLI it2. Per installare manualmente:

• tmux: installate tramite il gestore di pacchetti del vostro sistema. Consultate il wiki di tmux per istruzioni specifiche della piattaforma.
• iTerm2: installate la CLI it2, quindi abilitate l'API Python in iTerm2 → Settings → General → Magic → Enable Python API.

Specificare compagni di team e modelli

Claude decide il numero di compagni di team da generare in base al vostro compito, oppure potete specificare esattamente quello che desiderate:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Claude Code sceglie il modello di ogni compagno di team dal primo di questi che si applica:

1. Il modello che il vostro prompt di spawn nomina per quel compagno di team.
2. Per un compagno di team generato da una definizione di subagent, il model della definizione, dove inherit seleziona il modello del lead.
3. CLAUDE_CODE_SUBAGENT_MODEL, quando è impostato su qualsiasi cosa diversa da inherit.
4. Il modello attuale del lead.

Se un mod installato imposta un modello nel suo hook agent.spawn, Claude Code utilizza quel modello al posto della prima fonte.

Se impostate CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, le prime due fonti non si applicano. Claude Code sceglie il modello di ogni compagno di team da CLAUDE_CODE_SUBAGENT_MODEL quando è impostato su qualsiasi cosa diversa da inherit, e dal modello attuale del lead altrimenti. Richiede Claude Code versione 2.1.257 o successiva.

Prima della versione 2.1.251, CLAUDE_CODE_SUBAGENT_MODEL veniva per primo in questo ordine.

[!NOTE]

teammateDefaultModel è stato rimosso nella versione 2.1.234; Claude Code ignora un valore rimasto. Nominate il modello nel vostro prompt invece.

Claude Code controlla il modello che seleziona per un compagno di team rispetto alla lista di autorizzazione availableModels della vostra organizzazione. Quando la lista di autorizzazione blocca un valore, Claude Code sostituisce un altro modello:

• Alias di famiglia come opus: Sull'API Anthropic e Claude Platform su AWS, Claude Code esegue il compagno di team sulla versione più recente di quella famiglia che la lista di autorizzazione consente. Su provider con ID modello specifici del provider, dove la sostituzione non funziona, un alias bloccato ricade come qualsiasi altro valore bloccato secondo il punto successivo
• Qualsiasi altro valore bloccato, incluso un alias di famiglia su provider dove la sostituzione non funziona, o uno la cui famiglia non ha versione consentita: Claude Code esegue il compagno di team sul modello del lead invece. Se impostate CLAUDE_CODE_SUBAGENT_MODEL, Claude Code prova prima quel modello, secondo le stesse regole

Per impostazione predefinita, i compagni di team ereditano il livello di sforzo del lead. In modalità split-pane questo si applica dalla v2.1.186; le versioni precedenti non passavano lo sforzo della sessione del lead ai compagni di team in split-pane.

Richiedere ai compagni di team di pianificare prima di implementare

Per compiti complessi o rischiosi, potete richiedere ai compagni di team di pianificare prima di implementare. Un compagno di team che Claude genera mentre il lead è in plan mode lavora in modalità piano di sola lettura fino a quando il suo piano non è pronto. Passate il lead in plan mode per primo, quindi chiedete il compagno di team:

Spawn an architect teammate to refactor the authentication module.

Quando quel compagno di team finisce di pianificare, invia una richiesta di approvazione del piano al lead. Se non hai cambiato la modalità di permesso di quel compagno di team da quando è stato generato, Claude Code approva il piano non appena arriva la richiesta, senza che il lead lo esamini. Le modifiche e i comandi del compagno di team passano comunque attraverso le richieste di permesso descritte in Permessi. Una volta approvato il piano, il compagno di team esce dal plan mode e inizia l'implementazione.

Se metti in plan mode un compagno di team in-process in esecuzione premendo Shift+Tab mentre visualizzi la sua sessione, è il lead a esaminare il piano di quell'esecuzione invece di Claude Code che lo approva. Non ti viene chiesto di approvarlo; il lead lo approva o lo rimanda indietro per una revisione.

Parlare direttamente con i compagni di team

Ogni compagno di team è una sessione Claude Code completa e indipendente. Potete messaggiare qualsiasi compagno di team direttamente per fornire istruzioni aggiuntive, fare domande di follow-up o reindirizzare il loro approccio.

• Modalità in-process: utilizzate i tasti freccia su e giù nel pannello dell'agente per selezionare un compagno di team, quindi premete Invio per visualizzare la sua sessione e digitate per inviargli un messaggio. Premete x su un compagno di team selezionato per fermarlo. Premete Ctrl+T per attivare/disattivare l'elenco delle attività.
• Modalità split-pane: fate clic nel riquadro di un compagno di team per interagire direttamente con la sua sessione. Ogni compagno di team ha una visualizzazione completa del proprio terminale.

Mentre stai visualizzando un compagno di team in-process, il testo semplice e le skill vanno a quel compagno di team, mentre i comandi integrati vanno alla sessione del lead, con queste protezioni:

• /compact, /clear e /rewind agiscono sulla conversazione del lead, quindi Claude Code ti chiede di confermare prima di eseguirne uno da questa vista.
• /model e /fast impostano il modello e la modalità veloce del lead, non quelli del compagno di team, quindi non vengono eseguiti da questa vista. Un avviso ti spiega il motivo.

Il modello e la modalità veloce di un compagno di team sono fissati quando viene generato.

Assegnare e rivendicare attività

L'elenco di attività condiviso coordina il lavoro nel team. Il lead crea attività e i compagni di team le elaborano. Le attività hanno tre stati: in sospeso, in corso e completate. Un'attività può anche dipendere da altre attività e appare come bloccata nell'elenco delle attività fino a quando queste non sono completate. I compagni di team non rivendicano autonomamente un'attività bloccata, ma tu o il lead potete comunque assegnarla.

Gli agenti senza i Task tools coordinano attraverso messaggi invece della lista di attività condivisa.

Il lead può assegnare attività esplicitamente, oppure i compagni di team possono auto-rivendicare:

• Il lead assegna: dite al lead quale attività assegnare a quale compagno di team
• Auto-rivendicazione: dopo aver completato un'attività, un compagno di team raccoglie la prossima attività non assegnata e non bloccata da solo

La rivendicazione delle attività utilizza il file locking per prevenire race condition quando più compagni di team tentano di rivendicare la stessa attività simultaneamente.

Spegnere i compagni di team

Per terminare gracefully la sessione di un compagno di team, fate riferimento ad esso per nome. Ad esempio, con un compagno di team denominato ricercatore:

Ask the researcher teammate to shut down

Il lead invia una richiesta di arresto. Il compagno di team può approvare, uscendo gracefully, o rifiutare con una spiegazione.

Le directory condivise del team vengono pulite automaticamente quando la sessione termina, quindi non c'è un passaggio di pulizia separato. Consulta Architecture per sapere quali directory vengono rimosse e quali restano su disco.

Applicare quality gate con hooks

Utilizzate hooks per applicare regole quando i compagni di team finiscono il lavoro o le attività vengono create o completate:

• TeammateIdle: viene eseguito quando un compagno di team sta per andare inattivo. Uscite con codice 2 per inviare feedback e mantenere il compagno di team al lavoro.
• TaskCreated: viene eseguito quando un'attività sta per essere creata. Uscite con codice 2 per prevenire la creazione e inviare feedback.
• TaskCompleted: viene eseguito quando un'attività sta per essere contrassegnata come completata. Uscite con codice 2 per prevenire il completamento e inviare feedback.

Come funzionano i team di agenti

Questa sezione descrive l'architettura e i meccanismi alla base dei team di agenti. Se vuoi iniziare a usarli, consulta Controlla il tuo team di agenti più sopra.

Come Claude avvia i team di agenti

Per avviare un team, chiedi a Claude dei compagni di squadra. Claude avvia un compagno di squadra quando chiama lo strumento Agent con un name mentre i team di agenti sono abilitati, a meno che la chiamata non sia un fork o non passi isolation nella chiamata stessa. Claude Code non ti chiede di confermare l'avvio.

Claude assegna anche un nome ai subagent ordinari di propria iniziativa, in modo da poter inviare loro messaggi in seguito. Queste chiamate seguono la stessa regola, quindi i team possono formarsi anche quando non ne hai richiesto uno. Se invece vuoi dei subagent, disattiva i team di agenti.

Architettura

Un team di agenti è composto da:

La casella di posta di ciascun agente è un file JSON in ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Claude Code convalida ogni voce quando legge un file di casella di posta. Le voci che non corrispondono al formato dei messaggi vengono segnalate come errori e rimosse dal file; i messaggi validi vengono comunque recapitati.

Claude Code segnala un messaggio come inviato solo quando la scrittura nel file della casella di posta del destinatario va a buon fine, sia che il messaggio sia testo semplice sia che si tratti di un messaggio di protocollo strutturato come un'approvazione del piano o una richiesta di arresto. Quando la scrittura non riesce, ad esempio perché il disco è pieno o la directory della casella di posta non è scrivibile, l'agente mittente riceve un errore e non viene inviato nulla. Consulta Failed to write to a teammate's inbox per i messaggi di errore e i passaggi di ripristino.

Claude Code gestisce automaticamente le dipendenze tra le attività: quando un compagno di squadra completa un'attività da cui dipendono altre attività, sblocca le attività dipendenti senza alcun intervento da parte tua.

I team e le attività vengono archiviati localmente con un nome derivato dalla sessione. Il nome è session- seguito dai primi otto caratteri dell'ID della sessione:

• Configurazione del team: ~/.claude/teams/{team-name}/config.json. Claude Code rimuove la directory di configurazione del team al termine della sessione.
• Elenco delle attività: ~/.claude/tasks/{team-name}/. Questa directory rimane sul disco dopo la fine della sessione. Per modificare per quanto tempo Claude Code la conserva, imposta cleanupPeriodDays.

Claude Code genera entrambi automaticamente all'avvio della sessione e li aggiorna man mano che i compagni di squadra si uniscono, diventano inattivi o se ne vanno.

La configurazione del team contiene lo stato di runtime, come gli ID delle sessioni e gli ID dei pannelli tmux, quindi non modificarla a mano e non crearla in anticipo: le tue modifiche vengono sovrascritte al successivo aggiornamento dello stato.

Per definire ruoli riutilizzabili per i compagni di squadra, usa invece le definizioni dei subagent.

La configurazione del team contiene un array members con il nome e l'ID agente di ciascun membro. La voce del lead ha sempre il tipo di agente team-lead. La voce di un compagno di squadra riporta il tipo di agente indicato dal lead al momento della creazione, che si tratti di un tipo integrato o di una definizione di subagent, e omette il campo quando il lead non ne ha indicato nessuno. I compagni di squadra possono leggere questo file per scoprire gli altri membri del team.

Non esiste un equivalente a livello di progetto della configurazione del team. Un file come .claude/teams/teams.json nella directory del tuo progetto non viene riconosciuto come configurazione; Claude lo tratta come un file ordinario.

Usa le definizioni dei subagent per i compagni di squadra

Quando crei un compagno di squadra in una qualsiasi delle due modalità di visualizzazione, puoi fare riferimento a un tipo di subagent dall'ambito dei subagent di progetto, utente, gestito o di plugin. In questo modo puoi definire un ruolo una sola volta, ad esempio un security-reviewer o un test-runner, e riutilizzarlo sia come subagent delegato sia come compagno di squadra in un team di agenti.

Per usare una definizione di subagent, indicala per nome quando chiedi a Claude di creare il compagno di squadra:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

Claude Code legge la definizione di subagent che hai indicato e ne applica al compagno di squadra le parti seguenti. Quando una parte dipende dalla modalità di visualizzazione del compagno di squadra, la voce lo specifica:

• tools: Claude Code limita il compagno di squadra agli strumenti presenti nell'elenco tools della definizione. Per un compagno di squadra in-process, Claude Code aggiunge SendMessage a tale elenco e, in una sessione che dispone degli strumenti Task, aggiunge anche TaskCreate, TaskGet, TaskList e TaskUpdate.
• model: Claude Code usa il model della definizione in entrambe le modalità di visualizzazione quando il tuo prompt di creazione non ne indica uno. Consulta come Claude Code sceglie il modello di un compagno di squadra.
• disallowedTools: per un compagno di squadra in-process, Claude Code rimuove dall'insieme del compagno di squadra gli strumenti indicati in disallowedTools della definizione. SendMessage e gli strumenti Task che aggiunge restano disponibili anche quando l'elenco li indica.
• effort: per un compagno di squadra in-process, Claude Code applica l'effort della definizione secondo le regole dell'effort nel frontmatter.
• autoCompactWindow: per un compagno di squadra in-process, Claude Code applica l'autoCompactWindow della definizione secondo le regole di quel campo. Un compagno di squadra a pannelli divisi ignora il campo. Richiede Claude Code v2.1.296 o versioni successive.
• Corpo: per un compagno di squadra in-process, Claude Code aggiunge il corpo della definizione al proprio prompt di sistema predefinito come istruzioni aggiuntive. Per un compagno di squadra a pannelli divisi, Claude Code usa il corpo al posto del proprio prompt di sistema predefinito.
• skills: Claude Code non applica le skills della definizione a un compagno di squadra in nessuna delle due modalità di visualizzazione. Il compagno di squadra carica le skill dalle impostazioni del tuo progetto e utente.
• mcpServers: per un compagno di squadra a pannelli divisi, Claude Code applica i mcpServers della definizione secondo le regole di quel campo, che riguardano anche una sessione avviata con --agent. Un compagno di squadra in-process ignora il campo e carica i server MCP dalle impostazioni del tuo progetto e utente.

Quando Claude invia un messaggio a un compagno di squadra in-process che non è più in esecuzione, Claude Code lo riattiva nella stessa sessione, ripristina l'eventuale conversazione salvata per esso e gli fornisce il messaggio come prompt successivo. Dopo aver ripreso una sessione, i compagni di squadra non vengono riattivati in questo modo, secondo la limitazione sulla ripresa.

Per un compagno di squadra che riattiva, Claude Code riapplica una definizione proveniente dalla directory .claude/agents/ di un progetto o da una directory --add-dir solo se hai considerato attendibile la cartella in cui si trova il file dell'agente. Considerare attendibile una cartella padre non conta. Fino ad allora, il compagno di squadra torna senza nessuno degli strumenti o delle istruzioni della definizione, mantenendo solo gli strumenti che Claude Code aggiunge a ogni compagno di squadra in-process. Consulta the teammate's agent definition was not restored per il testo dell'avviso.

Permessi

I compagni di squadra partono con la modalità di permesso del lead, ad eccezione della modalità dontAsk, che non ereditano. Se il lead viene eseguito con --dangerously-skip-permissions, lo sono anche tutti i compagni di squadra. Dopo la creazione, puoi modificare la modalità di permesso di un singolo compagno di squadra, ma non puoi impostare modalità di permesso specifiche per ciascun compagno di squadra al momento della creazione.

Un compagno di squadra in-process viene eseguito con le regole allow e deny attive del lead, quindi --disallowedTools, --tools e --allowedTools si applicano tutti a esso. Per un compagno di squadra a pannelli divisi, verifica ciascun flag:

• --disallowedTools e --tools: il compagno di squadra parte con le regole deny e l'elenco degli strumenti impostati dal lead nella riga di comando. Richiede Claude Code v2.1.309 o versioni successive.
• --allowedTools: Claude Code non passa questo flag a un compagno di squadra a pannelli divisi, quindi un'azione che hai consentito solo con esso non è preapprovata in quel compagno di squadra. Per approvare queste azioni in anticipo, inserisci le regole in permissions.allow in --settings quando avvii il lead. Ad esempio, esegui claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}' nella tua shell. Le regole si applicano al lead e a ciascun compagno di squadra a pannelli divisi per quella sessione.

Le richieste di permesso dei compagni di squadra compaiono nella sessione del lead, quindi approvale lì personalmente. Non è necessario approvare il piano di un compagno di squadra.

Messaggi tra agenti

Quando un agente invia un messaggio a un altro tramite SendMessage, Claude Code comunica all'agente destinatario che il messaggio proviene da un'altra sessione di Claude, non da te. Un compagno di squadra non può approvare una richiesta di permesso né fornire il consenso per tuo conto, e un compagno di squadra a cui è stata negata un'azione non può inoltrarla a un altro compagno di squadra per aggirare il controllo. Le stesse regole si applicano a un messaggio che arriva da una delle tue altre sessioni di Claude Code, del tutto esterna al team.

In modalità auto, il classificatore applica due controlli ai messaggi tra agenti:

• Tratta un'affermazione di approvazione inoltrata da un altro agente come input non attendibile anziché come una tua conferma.
• Esamina ogni messaggio prima che Claude Code lo recapiti, che si tratti di un messaggio semplice o di un messaggio di protocollo strutturato come una richiesta di arresto o una risposta di approvazione del piano. Un messaggio che blocca non raggiunge mai il destinatario.

Contesto e comunicazione

Ogni compagno di squadra ha la propria finestra di contesto. Al momento della creazione, un compagno di squadra carica lo stesso contesto di progetto di una sessione normale: CLAUDE.md, server MCP e skill. Se avvii il lead con --setting-sources, i compagni di squadra caricano dallo stesso elenco ristretto di origini. Prima della v2.1.281, i compagni di squadra a pannelli divisi caricavano tutte le origini delle impostazioni.

Un compagno di squadra riceve anche il prompt di creazione dal lead. La cronologia della conversazione del lead non viene trasferita.

Come i compagni di squadra condividono le informazioni:

• Recapito automatico dei messaggi: quando i compagni di squadra inviano messaggi, questi vengono recapitati automaticamente ai destinatari. Il lead non deve controllare periodicamente la presenza di aggiornamenti.
• Notifiche di inattività: quando un compagno di squadra termina e si ferma, avvisa automaticamente il lead e include la propria risposta finale nella notifica. Un compagno di squadra il cui turno termina con un errore API avvisa il lead di non essere riuscito e include il testo dell'errore.
• Elenco delle attività condiviso: gli agenti che dispongono degli strumenti Task possono vedere lo stato delle attività e prendere in carico il lavoro disponibile.
• Messaggistica tra compagni di squadra: invia un messaggio a uno specifico compagno di squadra indicandone il nome. Per raggiungere tutti, invia un messaggio per ciascun destinatario.

Il lead assegna un nome a ogni compagno di squadra al momento della creazione, e qualsiasi compagno di squadra può inviare messaggi a qualsiasi altro usando quel nome. Per ottenere nomi prevedibili a cui fare riferimento nei prompt successivi, indica al lead come chiamare ciascun compagno di squadra nella tua istruzione di creazione.

Utilizzo dei token

I team di agenti usano molti più token di una singola sessione. Ogni compagno di squadra ha la propria finestra di contesto e l'utilizzo dei token cresce con il numero di compagni di squadra attivi. Per ricerca, revisione e sviluppo di nuove funzionalità, i token aggiuntivi di solito valgono la spesa. Per le attività abituali, una singola sessione è più conveniente. Consulta costi in token dei team di agenti per indicazioni sull'utilizzo.

Le richieste di un compagno di squadra in-process non rientrano nel bucket TTL della cache della conversazione principale, quindi la sua cache dura cinque minuti per impostazione predefinita, anche con un abbonamento Claude. Per mantenerla per un'ora, imposta subagentPromptCacheTtl su 1h. L'API addebita le scritture nella cache di 1 ora a una tariffa più elevata.

Esempi di casi d'uso

Questi esempi mostrano come i team di agenti gestiscono compiti in cui l'esplorazione parallela aggiunge valore.

Eseguire una revisione del codice parallela

Un singolo revisore tende a gravitare verso un tipo di problema alla volta. Dividere i criteri di revisione in domini indipendenti significa che la sicurezza, le prestazioni e la copertura dei test ricevono tutti un'attenzione approfondita simultaneamente. Il prompt assegna a ogni compagno di team una lente distinta in modo che non si sovrappongano:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Ogni revisore lavora dalla stessa PR ma applica un filtro diverso. Il lead sintetizza i risultati tra tutti e tre dopo che finiscono.

Investigare con ipotesi concorrenti

Quando la causa principale è poco chiara, un singolo agente tende a trovare una spiegazione plausibile e smettere di cercare. Il prompt combatte questo rendendo i compagni di team esplicitamente avversari: il lavoro di ognuno non è solo investigare la propria teoria ma sfidare le altre.

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

La struttura del dibattito è il meccanismo chiave qui. L'investigazione sequenziale soffre di ancoraggio: una volta che una teoria è stata esplorata, l'investigazione successiva è distorta verso di essa.

Con più investigatori indipendenti che attivamente cercano di confutarsi a vicenda, la teoria che sopravvive è molto più probabile che sia la causa principale effettiva.

Best practices

Fornire ai compagni di team contesto sufficiente

I compagni di team caricano il contesto del progetto automaticamente, inclusi CLAUDE.md, MCP servers e skills, ma non ereditano la cronologia della conversazione del lead. Consultate Context e comunicazione per i dettagli. Includete i dettagli specifici dell'attività nel prompt di generazione:

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

Scegliere una dimensione del team appropriata

Non c'è un limite rigido al numero di compagni di team, ma si applicano vincoli pratici:

• I costi dei token si scalano linearmente: ogni compagno di team ha il proprio context window e consuma token indipendentemente. Consultate i costi dei token dei team di agenti per i dettagli.
• L'overhead di coordinamento aumenta: più compagni di team significa più comunicazione, coordinamento delle attività e potenziale per conflitti
• Rendimenti decrescenti: oltre un certo punto, i compagni di team aggiuntivi non accelerano il lavoro proporzionalmente

Iniziate con 3-5 compagni di team per la maggior parte dei flussi di lavoro. Questo bilancia il lavoro parallelo con il coordinamento gestibile. Se avete 15 attività indipendenti, 3 compagni di team è un buon punto di partenza.

Scalate solo quando il lavoro beneficia genuinamente dall'avere compagni di team che lavorano simultaneamente. Tre compagni di team focalizzati spesso superano cinque dispersi.

Dimensionare le attività appropriatamente

• Troppo piccole: l'overhead di coordinamento supera il beneficio
• Troppo grandi: i compagni di team lavorano troppo a lungo senza check-in, aumentando il rischio di sforzo sprecato
• Giuste: unità auto-contenute che producono un deliverable chiaro, come una funzione, un file di test o una revisione

[!TIP]

Il lead suddivide il lavoro in attività e le assegna ai compagni di team automaticamente. Se non sta creando abbastanza attività, chiedetegli di dividere il lavoro in pezzi più piccoli. Avere 5-6 attività per compagno di team mantiene tutti produttivi e permette al lead di riassegnare il lavoro se qualcuno rimane bloccato.

Aspettare che i compagni di team finiscano

A volte il lead inizia a implementare le attività stesso invece di aspettare i compagni di team. Se notate questo:

Wait for your teammates to complete their tasks before proceeding

Iniziare con ricerca e revisione

Se siete nuovi ai team di agenti, iniziate con compiti che hanno confini chiari e non richiedono di scrivere codice: revisionare una PR, ricercare una libreria o investigare un bug. Questi compiti mostrano il valore dell'esplorazione parallela senza le sfide di coordinamento che vengono con l'implementazione parallela.

Evitare conflitti di file

Due compagni di team che modificano lo stesso file porta a sovrascritture. Suddividete il lavoro in modo che ogni compagno di team possieda un set diverso di file.

Monitorare e sterzare

Controllate il progresso dei compagni di team, reindirizzate gli approcci che non funzionano e sintetizzate i risultati man mano che arrivano. Lasciare un team senza supervisione per troppo tempo aumenta il rischio di sforzo sprecato.

Troubleshooting

I compagni di team non appaiono

Se i compagni di team non appaiono dopo aver chiesto a Claude di crearli:

• In modalità in-process, i compagni di team appaiono nel pannello agente sotto l'input del prompt. Utilizzate i tasti freccia su e giù per selezionarne uno, quindi premete Invio per visualizzarlo.
• Una riga di compagno di team che è scomparsa dopo essere rimasta inattiva è stata nascosta, non interrotta. Le righe inattive si nascondono 30 secondi dopo che l'intero pannello diventa inattivo e riappaiono al turno successivo del compagno di team. Quando più di tre compagni di team sono inattivi, le loro righe in eccesso si comprimono in una singola riga N idle agents che Invio espande. Inviate un messaggio al compagno di team per nome per riportare una riga nascosta.
• Controllate che il compito che avete dato a Claude fosse abbastanza complesso da giustificare un team. Claude decide se creare compagni di team in base al compito.
• Se avete esplicitamente richiesto split panes, assicuratevi che tmux sia installato e disponibile nel vostro PATH:

  which tmux
  

• Per iTerm2, verificate che la CLI it2 sia installata e che l'API Python sia abilitata nelle preferenze di iTerm2.

Claude crea compagni di team invece di subagent

Mentre i team di agenti sono abilitati, un subagent che Claude nomina nella sessione del lead viene avviato come compagno di team. Claude può nominare subagent autonomamente, quindi questo può accadere durante una delega che non hai mai inquadrato come lavoro di team.

Per fare in modo che i subagent denominati vengano avviati di nuovo come subagent, disattiva i team di agenti impostando CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS a 0:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

Non è necessario avviare una nuova sessione: Claude Code riapplica i valori env del file di impostazioni alla sessione in esecuzione quando salvi, e rilegge la variabile ogni volta che Claude genera un subagent, quindi il prossimo subagent che Claude nomina viene avviato come subagent.

L'impostazione della variabile a 0 nel vostro settings.json utente sostituisce un'esportazione shell. Altre fonti di impostazioni possono comunque abilitare i team di agenti:

• File di impostazioni con precedenza più alta: le impostazioni del progetto, le impostazioni locali e un payload --settings si applicano dopo le impostazioni utente, quindi una voce env che imposta la variabile a 1 in una qualsiasi di esse vince. Vedere Precedenza delle impostazioni.
• Impostazioni gestite: le impostazioni gestite si applicano dopo ogni altra fonte. Se la vostra organizzazione abilita i team di agenti lì, chiedete al vostro amministratore di modificare il valore gestito.

Dopo la modifica, Claude potrebbe comunque nominare subagent, e il nome continua a funzionare come indirizzo SendMessage. Claude riceve il risultato di ogni subagent quando si completa.

Troppi prompt di permesso

Le richieste di permesso dei compagni di team si propagano al lead, il che può creare attrito. Pre-approvate le operazioni comuni nelle vostre impostazioni di permesso prima di generare i compagni di team per ridurre le interruzioni.

I compagni di team si fermano anticipatamente

I compagni di team possono fermarsi dopo aver incontrato errori invece di recuperare. Controllate il loro output selezionando il compagno di team nel pannello agente e premendo Invio in modalità in-process, o facendo clic sul riquadro in modalità split, quindi:

• Date loro istruzioni aggiuntive direttamente
• Generate un compagno di team sostitutivo per continuare il lavoro

Un messaggio dal lead o da un altro compagno di team riattiva un compagno di team in-process che è in attesa di riprovare una richiesta API non riuscita, quindi riprova immediatamente invece di aspettare il ritardo di ripetizione completo.

Sessioni tmux orfane

Se una sessione tmux persiste dopo che la sessione Claude Code termina, potrebbe non essere stata completamente pulita. Elencate le sessioni e uccidete quella creata dal team:

tmux ls
tmux kill-session -t <session-name>

Limitazioni

I team di agenti sono sperimentali. Le limitazioni attuali di cui essere consapevoli:

• Nessuna ripresa della sessione con compagni di team in-process: /resume e /rewind non ripristinano i compagni di team in-process. Dopo aver ripreso una sessione, il lead potrebbe tentare di messaggiare compagni di team che non esistono più. Se questo accade, dite al lead di generare nuovi compagni di team.
• Lo stato dell'attività può ritardare: i compagni di team a volte non riescono a contrassegnare le attività come completate, il che blocca le attività dipendenti. Se un'attività sembra bloccata, controllate se il lavoro è effettivamente fatto e aggiornate lo stato dell'attività manualmente o dite al lead di spingere il compagno di team.
• L'arresto può essere lento: i compagni di team finiscono la loro richiesta attuale o la chiamata dello strumento prima di spegnersi, il che può richiedere tempo.
• Un team per sessione: una sessione ha esattamente un team, limitato a quella sessione. Non potete creare team denominati aggiuntivi o condividere un team tra sessioni.
• Nessun team annidato: i compagni di team non possono generare i loro propri compagni di team. Solo il lead può gestire il team.
• Nessun subagent in background da compagni di team in-process: i subagent di un compagno di team in-process vengono eseguiti in primo piano, perché il lavoro in background di un compagno di team non può sopravvivere al processo del lead. Claude Code restituisce un errore quando un compagno di team genera un subagent la cui definizione imposta background: true. Anche una richiesta run_in_background: true di un compagno di team fallisce, con un errore o eseguendosi silenziosamente in primo piano. I subagent lanciati dalla conversazione principale seguono il default in background.
• Il lead è fisso: la sessione principale è il lead per tutta la sua durata. Non potete promuovere un compagno di team a lead o trasferire la leadership.
• Permessi impostati al momento della generazione: i compagni di team iniziano con la modalità di permesso descritta in Permessi. Potete cambiare la modalità di permesso di un singolo compagno di team dopo la generazione, ma non potete impostare modalità di permesso per compagno di team al momento della generazione.
• Split panes richiedono tmux o iTerm2: la modalità in-process predefinita funziona in qualsiasi terminale. La modalità split-pane non è supportata nel terminale integrato di VS Code, Windows Terminal o Ghostty.

Prossimi passi

Esplorate approcci correlati per il lavoro parallelo e la delega:

• Delega leggera: i subagents generano agenti helper per ricerca o verifica all'interno della vostra sessione, migliore per compiti che non hanno bisogno di coordinamento tra agenti
• Messaggistica tra le vostre sessioni: la messaggistica tra sessioni consente a Claude di passare i risultati tra le sessioni che eseguite voi stessi
• Sessioni parallele manuali: i Git worktrees vi permettono di eseguire più sessioni Claude Code voi stessi senza coordinamento automatico del team