Cos’è un subagent e come si usa negli agenti di programmazione?

Il subagente lavora in un contesto separato e ti restituisce il risultato

Quando dai un compito grande a un agente di programmazione, le strade sono due: la conversazione principale fa tutto da sé, oppure affida una parte del lavoro a un subagente (subagent). Il subagente svolge quella parte nel proprio contesto; i file che legge e i test che lancia non riempiono la conversazione principale.

La documentazione di Cursor lo dice in due frasi: «Intermediate output stays in the subagent. The parent only sees the final summary.» Al 18 ottobre 2026 i subagenti ci sono in cinque strumenti: Claude Code, Codex di OpenAI, Cursor, Gemini CLI di Google e GitHub Copilot. Claude Code, Cursor e Copilot parlano di una finestra di contesto propria del subagente; Gemini CLI parla di un ciclo di contesto separato, mentre Codex avvia gli agenti in parallelo e ne raccoglie i risultati in un’unica risposta.

Per questo conviene in due casi: i lavori che producono molto output (lanciare i test, scorrere i log, leggere decine di file) e le ricerche indipendenti l’una dall’altra. Gli esempi vengono dal repository in cui sviluppiamo diffox e che usiamo ogni giorno; lì gira Claude Code.

Il subagente non vede la tua conversazione, quindi il compito va spiegato per intero

L’errore più comune con un subagente è dare per scontato che sappia ciò che si è detto nella conversazione principale. Secondo la documentazione di Claude Code il subagente parte con una finestra di contesto nuova: non vede la cronologia della conversazione, le skill già chiamate né i file che Claude ha letto. All’inizio ha in mano questo:

Per questo il testo del compito deve dire da solo l’obiettivo, quali file il subagente può toccare e che cosa deve riportare. Ciò che nella conversazione principale chiami «quell’errore», per il subagente non esiste: scrivi il percorso del file, il messaggio di errore e l’output che ti aspetti. Anche la documentazione di Cursor dice la stessa cosa: i subagenti partono con un contesto pulito e non hanno accesso alla cronologia della conversazione. La documentazione di Codex, Gemini CLI e Copilot non lo scrive; con qualunque strumento, la strada sicura è scrivere un compito che si capisca da solo. La documentazione di Codex consiglia inoltre di chiedere al subagente un riassunto invece dell’output intermedio.

Come si definisce un subagente nei cinque strumenti

In tutti e cinque un subagente si definisce con un file, a livello di progetto o di utente. La vera differenza tra gli strumenti è se l’agente principale delega il lavoro di sua iniziativa:

Fonte: la documentazione sui subagenti di ogni strumento, 18 ottobre 2026. In Codex la definizione è un file TOML, negli altri un file Markdown con un’intestazione YAML. L’agente browser di Gemini CLI è disattivato per impostazione predefinita. L’elenco degli agenti inclusi in Copilot cambia da una pagina all’altra: la pagina di riferimento ne conta sette, la guida pratica quattro.

Le differenze stanno nella terza colonna. In Codex dipende dal livello di effort: la pagina dei modelli scrive che il livello più alto, Ultra, porta avanti il lavoro dividendolo tra subagenti; la pagina sui subagenti dice invece che Codex in locale avvia un subagente su richiesta diretta, come «avvia due agenti», o su indicazione di AGENTS.md o di una skill. Negli altri quattro l’agente principale può delegare anche di sua iniziativa; la documentazione di Copilot aggiunge che il modello può anche non delegare e fare il lavoro da sé.

Le definizioni passano da uno strumento all’altro: Cursor legge anche le cartelle .claude/agents/ e .codex/agents/ (a parità di nome vince .cursor/), e anche Copilot CLI legge .claude/agents/. Quindi un file che scrivi in .claude/agents/ lo leggono Claude Code, Cursor e Copilot CLI; che i campi del frontmatter funzionino allo stesso modo in tutti e tre, la documentazione non lo garantisce.

Il 18 giugno 2026 Google ha smesso di servire Gemini CLI agli utenti gratuiti e agli abbonati Google AI Pro e Ultra, indirizzandoli ad Antigravity CLI; con una chiave API a pagamento o una licenza aziendale puoi continuare a usare Gemini CLI. Il 28 ottobre 2026 abbiamo letto la documentazione di Antigravity sui subagenti. I subagenti si definiscono in .agents/agents/ per un progetto e in ~/.gemini/config/agents/ per l’utente. L’agente principale affida un compito in base alla descrizione del subagente; tre agenti sono inclusi: research, browser e self. Un subagente non riceve la cronologia della conversazione dell’agente principale e parte da un contesto pulito; se la sua definizione non indica un modello, usa quello dell’agente principale. Si possono annidare fino a 10 livelli.

Un buon subagente ha un compito circoscritto, pochi tool e un report breve

Il file di definizione stabilisce tre cose: quando chiamare il subagente (la descrizione), a che cosa può accedere (i tool) e che cosa restituisce (il prompt). In Claude Code è fatto così; i campi obbligatori sono name e description:

---
name: test-runner
description: Esegue i test, riporta solo quelli falliti
tools: Read, Grep, Glob, Bash
model: haiku
---

Esegui la suite di test. Riporta solo i test falliti, ciascuno con il
suo messaggio di errore. Non modificare nessun file.

• La descrizione è un trigger. Claude Code e Gemini CLI delegano il lavoro in base alla descrizione. Nella descrizione non scrivere che cos’è l’agente, ma quando va chiamato.
• Restringi i tool. In Claude Code il campo tools limita i tool che il subagente può usare; se non lo indichi, eredita tutti i tool disponibili per i subagenti. A un agente che deve solo leggere non dare un tool di scrittura.
• I permessi vengono dall’agente principale. In Codex il subagente eredita i permessi, il provider e i server MCP dell’agente principale; il file di definizione non può cambiarli. Anche la sandbox e l’impostazione delle approvazioni sono quelle dell’agente principale.
• Chiedi un report breve. L’ultima frase del prompt deve dire che cosa restituire: i test falliti, i file trovati, una decisione. Se un lungo output intermedio torna nella conversazione principale, il vantaggio del subagente si perde.
• Puoi disattivare l’uso automatico. Nell’agente cloud di Copilot, un agente con disable-model-invocation: true gira solo quando lo scegli a mano. In Copilot il prompt di un agente personalizzato può avere al massimo 30.000 caratteri.

Modello, parallelismo e annidamento cambiano da uno strumento all’altro

Se nella definizione non indichi un modello, secondo la documentazione in Claude Code, Codex, Cursor e Copilot il subagente usa il modello dell’agente principale. La pagina sui subagenti di Gemini CLI scrive lo stesso, ma la pagina sui modelli della stessa documentazione dice che il comando /model e il flag --model non cambiano il modello dei subagenti; le due pagine non coincidono del tutto. Quanti subagenti possono girare in contemporanea, e se un subagente può avviarne un altro, cambia invece da strumento a strumento:

Fonte: la documentazione sui subagenti di ogni strumento, 18 ottobre 2026. «La documentazione non lo dice»: nelle pagine che abbiamo letto quel giorno non abbiamo trovato una frase che dia questa informazione. La pagina di riferimento di Copilot CLI dà una profondità di 4 nella sezione sulle variabili d’ambiente e di 6 nella tabella dei limiti. Gemini CLI limita ogni subagente, per impostazione predefinita, a 30 turni e 10 minuti.

Claude Code cerca il modello in quattro posti, in quest’ordine: il parametro model di quella chiamata, il campo model della definizione, la variabile d’ambiente CLAUDE_CODE_SUBAGENT_MODEL e infine il modello della conversazione principale. È scritto anche che cosa succede quando si arriva al limite: con 20 subagenti in esecuzione non se ne può avviare un altro, e l’errore dice a Claude di non riprovare. Gemini CLI blocca le chiamate annidate per evitare cicli infiniti e un consumo eccessivo di token.

Alzare l’effort di solito non aumenta i subagenti

Tutti e cinque gli strumenti hanno un’impostazione che decide quanto il modello ragiona prima di rispondere: l’effort, o livello di ragionamento. Il legame con i subagenti si riduce a due domande: il subagente eredita il livello dell’agente principale? E può sceglierne uno suo?

Fonte: la documentazione di ogni strumento su modelli e subagenti, 18 ottobre 2026. In Cursor i nomi dei livelli cambiano a seconda del modello.

La documentazione di Claude Code, Cursor, Gemini CLI e Copilot non lega l’effort al numero di subagenti. La documentazione di Claude Code descrive così la differenza vista ai livelli alti: «tested more edge cases and verified more of its work before answering. It also made more choices on its own.» Del numero di subagenti non parla. In Copilot i subagenti in parallelo non dipendono dall’effort ma da una modalità a parte: con il comando /fleet è l’agente principale a decidere se il lavoro si può dividere in parti.

L’eccezione è il livello più alto di Codex, ultra. La pagina dei modelli usa la stessa frase per la CLI, l’app e l’IDE: «Ultra mode goes beyond a single-agent run. It uses subagents to accelerate complex work.» Anche in ChatGPT Work, Ultra permette di affidare ai subagenti di propria iniziativa il lavoro adatto. Agli altri livelli, secondo la pagina sui subagenti, Codex in locale avvia un subagente quando glielo chiedi o quando lo dicono AGENTS.md o una skill.

Con ultracode Claude Code divide il lavoro tra decine di subagenti

Nello slider /effort di Claude Code, accanto ai livelli di effort, c’è anche un interruttore ultracode. La documentazione non lo definisce un livello, ma un’impostazione a parte: «a Claude Code setting rather than a model effort level». Quando è attivo, per ogni compito sostanziale Claude pianifica un workflow dinamico senza che tu lo chieda: scrive uno script che divide il lavoro e gestisce i subagenti, e un runtime lo esegue in background; intanto la tua sessione continua a rispondere.

Si attiva in quattro modi:

• Per un solo compito: scrivi la parola ultracode nel prompt; il livello di effort della sessione non cambia. La parola conta solo nei prompt che scrivi tu.
• Per tutta la sessione: /effort ultracode o l’interruttore nello slider.
• All’avvio: claude --effort ultracode; così anche il livello di effort passa a xhigh.
• In ogni sessione: "ultracode": true nel file di impostazioni.

Il costo la documentazione lo scrive chiaramente: ogni richiesta usa più token e dura di più; con un abbonamento arrivi prima al limite di sessione o a quello settimanale. Con ultracode attivo il limite di 20 subagenti non si applica; il workflow ha limiti suoi: per impostazione predefinita 16 agenti in contemporanea e al massimo 1.000 agenti per esecuzione. Con ultracode spento, più di 25 agenti o una stima di 1,5 milioni di token fanno comparire l’avviso «Large workflow»; con ultracode attivo non compare nemmeno questo avviso.

I workflow dinamici sono arrivati a fine maggio 2026 e nel riepilogo settimanale sono stati annunciati come «research preview»; il 18 ottobre 2026 la pagina dei workflow non riportava nessuna etichetta di stato. Non confonderli con due cose dal nome simile: ultrathink chiede un ragionamento più profondo solo per quel turno e non cambia il livello di effort; /code-review ultra è invece un comando a parte che fa girare agenti di review nel cloud, e Claude non lo avvia di sua iniziativa.

I subagenti possono parlarsi tra loro?

Il risultato del subagente torna a chi lo ha chiamato: questo vale per tutti e cinque. Gli strumenti si dividono su tre domande: i subagenti possono scriversi tra loro? L’agente principale può scrivere più tardi a un subagente in esecuzione o già finito? Esiste una funzione per lavorare in team?

Fonte: la documentazione di ogni strumento, 18 ottobre 2026. In Copilot, per scrivere agli agenti fratelli deve essere attiva la comunicazione condivisa tra fratelli; la documentazione non dice come si attiva.

La funzione agent teams di Claude Code è la forma più avanzata di tutto questo: una sessione fa da leader del team, i membri sono sessioni separate, ognuno lavora nella propria finestra di contesto e scrive agli altri per nome. Non si può scrivere a tutti insieme: a ogni destinatario va un messaggio a parte. Il criterio della documentazione stessa: «Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.» Agent teams è sperimentale, è disattivato per impostazione predefinita e consuma più token, perché ogni membro è un’istanza separata di Claude.

Poter scriversi non vuol dire doverci contare. La struttura più solida resta dividere il lavoro in parti indipendenti e mettere insieme i risultati nell’agente principale. Lo dice anche la documentazione di Copilot su fleet: il coordinamento passa da uno stato esplicito e non da una memoria condivisa implicita, e i subagenti non conservano lo stato tra una chiamata e l’altra; dai a ciascuno un contesto completo.

Per lavorare in parallelo, ogni agente ha bisogno del suo worktree e dei suoi file

I subagenti che si limitano a leggere possono lavorare fianco a fianco nella stessa directory. Il problema nasce quando più agenti modificano file e fanno commit: condividono la stessa directory, lo stesso branch e lo stesso index di git. È un problema di git, che non dipende dallo strumento che usi. Nel nostro repository abbiamo quattro regole per questo.

Un worktree a parte. In Claude Code, se nella definizione scrivi isolation: worktree, per il subagente si apre un worktree temporaneo, cioè una directory di lavoro separata del repository; se il subagente finisce senza modifiche, il worktree viene rimosso da solo. Secondo la documentazione, per impostazione predefinita questo worktree non parte dal branch su cui stai lavorando, ma dal branch predefinito del repository.

File separati. Per gli agenti che condividono la stessa directory la nostra regola è: ognuno fa commit solo dei propri percorsi (git commit --only <percorsi>), perché un semplice git commit prende tutto l’index, compreso il lavoro preparato da un altro agente. Quando dividi il lavoro, dai a ogni agente un insieme di file suo.

Un compito che si capisce da solo. In Claude Code e in Cursor il subagente non vede la tua conversazione; il testo del compito deve dire da solo l’obiettivo, quali file può toccare e che cosa deve riportare. Gli hook del file di impostazioni, invece, arrivano da soli: in Claude Code un hook PreToolUse scatta anche prima delle chiamate ai tool del subagente.

Pulizia. Un worktree con delle modifiche resta sul disco. Il 27 agosto 2026 nel nostro repository si erano accumulati 41 worktree, 37 dei quali da un solo giro di review. Visto che il disordine lo producevano i flussi di lavoro automatici e non le persone, la soluzione è stata messa lì: ogni sessione si apre con uno script che rimuove i branch delle pull request già unite e i worktree che hanno finito il loro lavoro.

Non tutti i compiti hanno bisogno di un subagente

Un subagente protegge il contesto, ma il proprio lo costruisce da zero; anche scrivere il compito e leggere il risultato hanno un costo. La documentazione di Claude Code consiglia la conversazione principale in questi casi:

• Serve un continuo botta e risposta. Il lavoro va rifinito insieme, un passo alla volta.
• Le fasi condividono lo stesso contesto. Pianificazione, implementazione e test si basano sulle stesse informazioni.
• La modifica è piccola e mirata. Poche righe in un file.
• Conta la velocità. Il subagente parte da zero, e raccogliere il contesto richiede tempo.

Il posto del subagente sono i compiti che rispondono da soli a una sola domanda: «lancia i test e riportami quelli falliti», «chi chiama questo modulo», «confronta queste tre librerie». Anche la review di diffox si basa su questa idea: divide la code review con IA tra agenti specializzati, e ognuno guarda la modifica con la propria domanda. Come vengono scelti lo spieghiamo nel nostro articolo sull’architettura.