Come creare un team di agenti AI con regista e verifica

Come creare un team di agenti AI: il lavoro che passa di mano e torna controllato

Per creare un team di agenti AI ti servono tre cose: un regista che passa il lavoro, specialisti con un compito solo, e un controllo fatto da un agente che può leggere ma non modificare. Il lavoro passa con file in una cartella e arriva a te solo per l'ultima parola, con scritto chi ha fatto cosa.

Si fa con gli agenti normali di Claude Code, quelli della guida su come creare agenti con Claude Code. Non serve la funzione sperimentale agent teams, che la documentazione italiana chiama «team di agenti»: è spenta di norma e questa guida non la usa (pagina ufficiale, verificato a novembre 2026). Da qui in poi quello che costruiamo si chiama squadra.

Claude Code non è nel piano gratuito (pagina dei piani, verificato a novembre 2026), e prima di una squadra serve saper fare un agente.

L'avvio vero col modello vero di regista e specialisti non è provato. Un'attività programmata vera non è provata. Un'attività programmata è un lavoro che parte da solo a un orario.

Il caso. Il bar «Da Rosa» di Catania non esiste: l'abbiamo inventato noi. Ogni lunedì Rosa ha un foglio di appunti scritti di corsa e vuole tre post pronti da leggere. Un agente raccoglie, uno scrive, uno controlla orari, chiusure e piatti contro i fatti del bar e gli appunti, il registro segna cosa è successo. Rosa legge e pubblica a mano. I tre post arrivano dal suo piano editoriale social: la squadra lo esegue, non lo decide.

Il riquadro è un testo prodotto da un modello piccolo a cui abbiamo dato le istruzioni del controllo: Haiku di Claude, tre post inventati con 9 errori piantati, soluzioni scritte prima. Non è l'agente del kit caricato in Claude Code. I tagli sono indicati, le righe rimaste sono tali e quali.

I numeri interi. Stessi dati, stesso manuale: con i criteri scritti 9, 9 e 9 in tre prove; senza criteri 9, 9 e 9. Gli stessi errori. Senza criteri, però, il vanto sul caffè è contato come errore tutte e tre le volte, con i criteri mai, e con i criteri c'è un esito netto. Poche prove, nessuna statistica.

E un modello solo, con la stessa richiesta, ha scritto post giusti quanto la squadra, due volte su due, con una chiamata invece di cinque. Altre due prove le abbiamo annullate per un nostro errore, e il confronto è col testo degli agenti di prima delle ultime correzioni. Su questi dati la squadra non scrive meglio. Ti dà altro: chi controlla non ha scritto il testo e non può modificarlo, con un limite vero sugli strumenti; un file per ogni passaggio; le domande in un posto solo; un registro con chi ha fatto cosa. Costa di più e spesso non serve.

Io lavoro con più di 30 agenti, divisi in squadre con un coordinatore, e con 7 lavori programmati che partono da soli a orari fissi; cosa esce sui social lo approvo io.

Agent teams o agenti normali: cosa fa questa guida e cosa no

Una squadra è un gruppo di agenti con un regista, ruoli separati e un manuale comune. In giro la trovi anche come «sistema multi agente». Claude Code ha cinque modi di far lavorare più cose insieme, e si confondono facilmente (mappa ufficiale, verificato a novembre 2026). Una sessione è una conversazione aperta con Claude Code.

Perché qui agenti normali. Il lavoro del bar va in sequenza, e per lavori così la documentazione stessa indica come più adatti una sessione sola o i subagenti. La pagina di agent teams manda prima alle opzioni più leggere, e dice che consumano di più di una sessione (agent teams, costi, verificato a novembre 2026).

La trappola. Attivarli «per provare» non è innocuo: con CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS a 1, un subagente a cui Claude dà un nome può partire come sessione di agent teams, senza conferma, anche se non li hai chiesti (stessa pagina). Nella squadra gli agenti non si scrivono fra loro: si passano il lavoro con il regista e con i file.

Chi fa cosa: regista, specialisti, verifica e titolare

Il regista è quello che altrove chiamano orchestratore: passa il lavoro e non lo fa. Gli specialisti hanno un compito solo. Ognuno è un file come quelli della guida su come creare agenti con Claude Code: se non ne hai ancora scritto uno, comincia da lì. La riga tools del file è l'elenco degli strumenti, cioè delle azioni che l'agente può fare. Il terminale è la finestra in cui si scrivono i comandi.

Rosa scrive gli appunti e fa partire il giro
  regista-settimana
    raccogli-settimana: scrive giro/2026-11-09/1-scheda.md
    autore-post: scrive giro/2026-11-09/2-post.md
    controllo-post: legge post, fatti, appunti e scheda, non scrive,
                    risponde al regista, che salva 3-controllo.md
    se NON PASSA: autore-post una volta, controllo-post una volta,
                  poi decide Rosa
  regista-settimana: scrive 4-da-decidere.md e una riga in REGISTRO.md
Rosa legge, risponde, pubblica a mano e segna CHIUSO nel registro

Quando non serve una squadra. Per un botta e risposta, per un lavoro corto, per compiti che dipendono di continuo l'uno dall'altro. Ogni agente pesa sugli stessi limiti del tuo piano, può essere più lento e non è più intelligente: un agente nuovo ti dà occhi nuovi, non una risposta più intelligente (subagenti, buone pratiche, verificato a novembre 2026). Quanto pesa lo mostra /usage, che non abbiamo provato. Se decidi di farla, parti da due agenti più il regista.

Tutti i prompt li abbiamo provati con il modello Haiku, su casi inventati: dicono com'è il testo che danno, non che il file uscito funzioni, perché quei file non li abbiamo caricati. Questo sul bar ha dato la squadra solo ai post del lunedì. Sulla parrucchiera di Bari non l'ha data a nessun lavoro, ed è una risposta utile.

Passo 1 a mano: il manuale e il registro

Il manuale è il file CLAUDE.md, nella cartella del progetto, cioè la cartella da cui apri Claude Code. Lo leggono gli agenti, mentre la tua chat non la vede nessuno di loro. Le eccezioni: Explore, Plan e gli agenti con omitClaudeMd: true (subagenti, verificato a novembre 2026).

L'abbiamo controllato sul nostro banco di prova, cioè Claude Code vero collegato a un servizio finto, leggendo la richiesta che partiva: CLAUDE.md arriva a regista e specialista, la regola detta in chat arriva solo alla conversazione. Allo specialista arrivano solo il manuale, il suo file, qualche dato sull'ambiente e il compito che gli scrive il regista.

Cosa ci va: chi siamo, dove stanno le cose, le regole per tutti, chi decide cosa. Va tenuto corto, perché pesa su ogni agente a ogni lavoro: il kit sta sotto le 40 righe. Orari e piatti stanno nel file dei fatti. Attenzione: una regola scritta lì è una richiesta, non un blocco. Il manuale del bar dice di dare del tu, e nel testo prodotto da un modello piccolo a cui abbiamo dato le istruzioni è uscito «Venite a trovarci».

La cartella del giro. Un file per ogni passaggio, e il regista passa il percorso, non il testo. Col primo testo del regista, il modello piccolo ha letto gli appunti e ha scritto le sue conclusioni nel compito, contro il file dello specialista. Da allora il regista del kit dice: il compito contiene la settimana e i percorsi, nient'altro.

Il registro. Una riga per ogni giro: data, cartella, chi ha lavorato, esito, cosa aspetta il titolare. Claude Code tiene già i suoi registri, ma di norma li cancella dopo 30 giorni e sono scomodi da leggere (subagenti, verificato a novembre 2026). REGISTRO.md è testo, e lo leggi tu.

Il prompt qui sotto fa prima le domande, poi il file. Sul bar è rimasto sotto le 40 righe, con [DA CONTROLLARE] al posto dei percorsi che non aveva. Ha aggiunto però «la persona che gestisce i social», che nessuno aveva nominato, segnalandola fra le righe incerte: rileggi quelle per prime.

Passo 2 a mano: scrivi il regista e fai il primo giro

Il regista si può mettere in tre modi, e non sono uguali. La tabella viene dal banco, su Windows con Claude Code 2.1.309, lanciato senza schermata.

La lista. La documentazione dice che Agent(a, b) è una lista vera solo con --agent, e che in un agente normale le parentesi sono ignorate (subagenti, verificato a novembre 2026). Sul banco, come agente normale è partito anche chi non era in lista. Con --agent, Claude Code ha risposto Agent type 'spec-c' not found. Available agents: spec-a, spec-b. Il modo B del kit copre in parte il buco: settings.json vieta general-purpose e claude, che hanno tutti gli strumenti.

La variabile fa due cose opposte. Nel modo A, a 0, fa aspettare il regista. Nel modo B fa il contrario: gli specialisti partono in background, cioè mentre lui va avanti, e il risultato va alla conversazione invece che a lui. La documentazione lo dice in due punti diversi (stessa pagina). Sul banco, un regista che non aspetta manda l'autore a leggere una scheda che non c'è ancora: File does not exist. Se un modello vero, davanti alla notifica, aspetti da solo non è provato. Il modo B l'abbiamo provato da riga di comando: nell'app no.

I livelli. Sotto la conversazione ci stanno al massimo tre livelli di agenti (subagenti). Nelle versioni v2.1.217 e 218 il limite era più basso, quindi chi ha una di quelle aggiorni (variabili d'ambiente, verificato a novembre 2026). Sul banco, al terzo lo strumento manca: No such tool available: Agent. Un agente senza Agent in tools non lancia nessuno, ma se manca tutta la riga ha tutti gli strumenti. La squadra del bar ne usa al massimo due: regista e specialista.

Il file del regista è intero più sotto, nell'assaggio. Queste sono le righe nuove rispetto a un agente qualsiasi:

• tools: Agent(…), Read, Write, Edit: è la riga che gli permette di lanciare gli altri.
• «La squadra»: i nomi stanno nel corpo perché, come agente normale, al primo messaggio il regista non riceve l'elenco degli agenti.
• «Il compito deve dirti la settimana e il percorso degli appunti»: se ne manca uno scrive FERMO, senza indovinare.
• Passo 3, «gli appunti»: il regista non li legge, ne passa il percorso a chi controlla.
• run_in_background: false: «Finché non è arrivato non fare il passo dopo».
• «Dopo ogni specialista controlla che il suo file esista»: se manca, FERMO.
• «Le domande vanno in 4-da-decidere.md»: un agente normale non può fartene, e il file vale in tutti i modi.

Il primo giro. Metti i quattro file in .claude/agents del progetto prima di aprire Claude Code, poi apri il terminale nel progetto.

# Windows PowerShell
cd "percorso\del\progetto"
$env:CLAUDE_CODE_FORK_SUBAGENT = "0"
claude --agent regista-settimana

# Mac e Linux: provati solo in Git Bash su Windows, mai su un Mac
cd "percorso/del/progetto"
CLAUDE_CODE_FORK_SUBAGENT=0 claude --agent regista-settimana

Sul banco abbiamo lanciato così, ma senza finestra e con la variabile già impostata dal nostro ambiente: la schermata vera, con la domanda di fiducia, non l'abbiamo vista. Se ti chiede se ti fidi della cartella, rispondi sì solo se è tua: senza quel sì le regole che ammettono le scritture vengono ignorate, come abbiamo visto sul banco. Poi scrivi:

Fai il giro della settimana dal 9 al 15 novembre 2026. Gli appunti sono in dati-di-prova/novita-settimana.md.

Sul banco nascono giro/2026-11-09/ con quattro file e una riga in REGISTRO.md: guarda se succede anche a te. Le richieste di permesso compaiono nella sessione con il nome dell'agente, Esc nega quella sola azione, e una risposta che vale oltre quell'azione vale per tutta la sessione. Per controllare c'è /tasks, e nel terminale gli agenti compaiono ad albero (documentazione, verificato a novembre 2026: sullo schermo non li abbiamo visti). Il controllo che non inganna è il registro: se la riga non c'è, il giro non è andato.

Provato col manuale e gli specialisti del kit, dopo una correzione il regista uscito ha tutte le regole. Ha scelto però un file in più, 5-per-rosa.md. Leggilo prima di usarlo.

La verifica separata: perché non basta scrivere «rileggi»

La riga tools è il limite, il testo è una richiesta. Con tools: Read, Grep, Glob il limite lo impone Claude Code (buone pratiche, verificato a novembre 2026). Sul banco abbiamo fatto tentare a controllo-post di scrivere, modificare e usare il terminale. Claude Code ha risposto così, e nessun file è cambiato o nato:

No such tool available: Write. Write is not among the tools available here.

Provalo anche tu su un post finto: apri con claude --agent controllo-post, chiedigli di correggere un errore, poi guarda se il file è cambiato. Quel comando noi l'abbiamo lanciato solo sul banco, senza finestra.

• Niente Bash né PowerShell a chi controlla: con il terminale un programma può scrivere file (permessi), anche se un esempio ufficiale dice che un agente con Bash non può scriverne (subagenti).
• Niente memory: aggiunge da solo Write ed Edit.
• Write non si limita a un file col campo tools, e nelle regole Write(percorso) non scatta mai, senza errore. Si scrive Edit(percorso), che vale anche per Write (stessa pagina, confermato sul banco).

I criteri scritti. Un revisore a cui chiedi di trovare problemi ne trova sempre qualcuno, e se correggi tutto peggiori (buone pratiche). Quindi scrivi cosa conta, cosa ignorare e l'esito: passa o non passa. Sui 9 errori non ne hanno fatti trovare di più: hanno tolto il falso allarme. E il giro di correzione si ferma: una volta indietro, poi decidi tu.

Farlo partire da solo: app, cloud o /loop

Si chiamano attività programmate: è il nome nuovo delle routine. Nell'app puoi trovare ancora Routines (pagina ufficiale, verificato a novembre 2026). I tipi sono tre.

Fonti: app desktop, cloud, /loop, verificato a novembre 2026. Solo documentazione: non le abbiamo provate.

La frase che conta: o i tuoi file con il computer acceso, o il cloud senza i tuoi file. Per una squadra che lavora in una cartella del PC serve quella dell'app. /loop no.

Senza nessuno davanti, secondo la documentazione. In modalità Manual, quella che chiede prima di agire, senza un permesso l'esecuzione resta ferma finché qualcuno risponde (app desktop). Con dontAsk viene negato tutto ciò che chiederebbe conferma. Con la modalità auto decide un classificatore, un modello che giudica al posto tuo, e la pagina stessa avverte che non garantisce la sicurezza (modalità dei permessi).

Cosa abbiamo provato e cosa no

L'avvio vero col modello vero di regista e specialisti non è provato. Un'attività programmata vera non è provata. Da terminale il nostro Claude Code non ha l'accesso e non abbiamo cercato credenziali. Quindi due prove.

Dove e con cosa. 04/11/2026, Windows 11, Claude Code 2.1.309, PowerShell 5.1 e Git Bash. La documentazione aperta quel giorno cita versioni più recenti.

Resta non provato, oltre ai due punti sopra: se un modello vero aspetta ogni specialista; se scrive i file o li scambia per rapporti, perché Claude Code dà a ogni subagente una nota contro i file .md di rapporto, mentre qui il metodo è un file per ogni passaggio; la schermata del terminale, con /tasks, l'albero, la domanda di permesso e la fiducia; l'app desktop; attività nel cloud e /loop; Mac e Linux veri. Agent teams non li abbiamo attivati.

Quindi prova tu, sui dati finti, prima di fidarti.

L'assaggio del kit: il regista del bar, intero

Questo è il file vero del kit. Va in .claude/agents/regista-settimana.md, nel progetto, prima di aprire Claude Code. Da solo non parte: mancano i tre specialisti che nomina.

A mano devi ancora farti specialisti, manuale, permessi e registro. Nel kit c'è la squadra intera, con gli appunti finti, i post con 9 errori, le soluzioni scritte prima e i modelli di attività programmata. Il riquadro qui sotto elenca il contenuto: si scarica dopo la donazione libera.

Domande frequenti sulle squadre di agenti

Come si crea un team di agenti AI?

Servono un regista che passa il lavoro, specialisti con un compito solo, un controllo che può solo leggere, un manuale comune e un registro, tutti in una cartella. Con Claude Code si usano gli agenti normali, cioè file di testo con nome, descrizione, strumenti e istruzioni. Se il lavoro non si ripete, basta un agente solo.

Che differenza c'è tra agent teams e subagenti?

Un subagente lavora a parte e riferisce a chi lo ha lanciato. Agent teams sono più sessioni di Claude Code che si scrivono fra loro: la funzione è sperimentale, spenta di norma e consuma di più. Per lavori in sequenza la documentazione di Claude Code, verificata a novembre 2026, indica come più adatti una sessione sola o i subagenti.

Come si attivano gli agent teams di Claude Code?

Con la variabile CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS impostata a 1, secondo la documentazione verificata a novembre 2026. Sono sperimentali, e attivarli cambia anche la delega normale: un agente a cui Claude dà un nome può partire come sessione di agent teams, senza conferma. Per una squadra con regista e verifica non servono, e noi non li abbiamo attivati.

Cos'è un agente orchestratore?

È il regista: divide il lavoro e lo passa agli altri, senza farlo. In Claude Code è una conversazione o un agente con Agent fra i suoi strumenti. La lista di chi può chiamare, scritta Agent(a, b), vale solo se lo lanci con claude --agent: come agente normale le parentesi vengono ignorate. Lo dice la documentazione, verificata a novembre 2026.

Routine, attività programmate o /loop: quale scegliere?

Routine è il vecchio nome delle attività programmate. Se la squadra lavora su file del tuo computer serve l'attività dell'app, con computer acceso e app aperta. Quella nel cloud gira a computer spento ma non vede i tuoi file. /loop vive nella sessione aperta e le ripetizioni scadono dopo 7 giorni: va bene per controlli brevi. Verificato a novembre 2026.

Claude Code può lavorare da solo a orari fissi?

Sì, con un'attività programmata, secondo la documentazione verificata a novembre 2026. Senza nessuno davanti però può restare ferma su un permesso, e quello che esce va riletto. Noi un'attività programmata vera non l'abbiamo provata. La prima volta conviene farla partire a mano e guardare cosa chiede.

Da fare oggi: scrivi l'ultimo lavoro che hai rifatto uguale tre settimane di fila, e da quante mani è passato. Se è una sola, la squadra non ti serve. Se sono di più, mettilo nel prompt «merita una squadra?». Se ti blocchi, scrivi a Fabio.