Cosa sono i subagenti in Claude Code? Cosa devi sapere

Subagenti (spesso scritti subagenti or subagenti) rappresentano uno dei più chiari progressi pratici negli strumenti per sviluppatori agentici: consentono di comporre un piccolo team di assistenti AI specializzati all'interno Codice Claude, ognuno con il proprio ruolo, strumenti e finestra di contesto. L'idea è semplice ma potente: invece di chiedere a un modello generalista di fare tutto, si definiscono agenti compatti e monofunzionali a cui l'orchestratore principale delega il lavoro (automaticamente o su richiesta esplicita). Questo cambia il modo in cui si gestiscono il contesto, gli strumenti e i compromessi tra costi e latenza dei flussi di lavoro complessi.

Cosa sono i subagenti?

Definizione breve. Un subagente è una "personalità" di intelligenza artificiale preconfigurata e specializzata in un'attività a cui Claude Code può delegare un compito. Ogni subagente ha il proprio prompt di sistema, la propria finestra di contesto (isolata), strumenti esplicitamente assegnati e, facoltativamente, una selezione di modelli. I subagenti possono essere creati a livello di progetto o utente e richiamati automaticamente da Claude o esplicitamente dall'utente.

Proprietà chiave di un subagente

Scopo specializzato e prompt di sistema. Descrivi il ruolo, i vincoli e l'approccio del subagente nel prompt del sistema in modo che si comporti in modo prevedibile per il suo dominio ristretto (ad esempio, revisore del codice, debugger, scienziato dei dati).
Finestra di contesto isolata. Ogni subagente conserva la propria cronologia e il proprio contesto di conversazione, evitando che il contesto del thread principale venga contaminato da dettagli di basso livello. Questo è fondamentale per scalare i flussi di lavoro che altrimenti esaurirebbero il contesto di una singola conversazione.
Ambito e autorizzazioni dello strumento. È possibile concedere o limitare gli strumenti interni o gli strumenti esterni del Model Context Protocol (MCP) che un subagente può utilizzare. Questa è una funzionalità fondamentale per la sicurezza e la governance.
Configurazione come codice. I subagenti sono definiti come file Markdown con front matter YAML (nome, descrizione, strumenti, modello) e memorizzati a livello di progetto (.claude/agents/) o livello utente (~/.claude/agents/). Le definizioni del progetto hanno la precedenza.

Cosa sono la delega automatica e l'invocazione esplicita

Il codice Claude può automaticamente delegare attività ai subagenti quando il tuo prompt o il subagente description corrisponde al compito, oppure puoi espressamente richiedere un agente (ad esempio, > Use the code-reviewer subagent to check my recent changes). Rendere il description orientato all'azione ("Use PROACTIVELY", "MUST BE USED") per dare una spinta alla delega automatica, due modi complementari per utilizzare i subagenti in Claude Code:

Delega automatica — Claude esamina la richiesta e delega proattivamente il lavoro corrispondente a un subagente.
Invocazione esplicita — chiami un subagente per nome nel tuo prompt/comando (ad esempio, Use the code-reviewer subagent to check my changes).

Entrambi gli approcci presentano diversi compromessi in termini di UX e progettazione. Di seguito ne analizzo i risultati.

Delega automatica

Come appare agli utenti. Si emette un comando di alto livello (ad esempio, "Preparare un controllo di sicurezza per questa nuova libreria") e Claude rileva che uno o più subagenti sono adatti in base a description campo nelle loro configurazioni. Se configurato per l'uso proattivo, il subagente viene inviato automaticamente e restituisce i risultati come output strutturati.

Perché i team lo usano.

Riduce il carico cognitivo: non è necessario ricordare o digitare il nome di ogni subagente.
Crea un onboarding più fluido per flussi di lavoro condivisi in cui determinate attività devono essere sempre gestite dallo stesso specialista.

Avvertenze.

Devi progettare il description e il sistema richiede deliberatamente che Claude selezioni in modo affidabile il subagente corretto.
Una delega troppo zelante può aumentare l'utilizzo dei token e il rumore se molti subagenti si attivano per attività simili; progetta le tue descrizioni in modo conservativo.

Invocazione esplicita

Come appare agli utenti. Chiami esplicitamente un subagente: > Use the test-runner subagent to run the project testsL'orchestrazione è deterministica: Claude richiama il subagente denominato con i suoi permessi e prompt preconfigurati.

Perché i team lo usano.

Controllo completo: puoi decidere esattamente quale specialista eseguirà il lavoro, semplificando il debug e la riproducibilità.
È più facile ragionare sui costi e sull'accesso agli strumenti in CI o script automatizzati.

Avvertenze.

Maggiore digitazione e disciplina: gli sviluppatori o l'automazione devono conoscere i nomi corretti dei subagenti.
Meno opportunistico: si perde un po' di comodità laddove l'agente principale avrebbe rilevato automaticamente un buon subagente.

Come funzionano i subagenti: panoramica tecnica

Di seguito è riportato uno sguardo pratico e orientato all'implementazione su cosa accade quando si crea e si utilizza un subagente.

Definizione di un subagente (configurazione come codice)

Un subagente è un file Markdown con front matter YAML. I campi importanti includono:

name — un ID univoco in minuscolo (con trattino)
description — descrizione in linguaggio naturale utilizzata per la corrispondenza automatica delle deleghe
tools — elenco virgola facoltativo degli strumenti consentiti (o omesso per ereditare tutti gli strumenti)
model — alias facoltativo (sonnet, opus, haiku) o puoi inherit per utilizzare il modello della conversazione principale

Un piccolo esempio (concettuale, non letterale tratto dalla documentazione):

---
name: code-reviewer
description: Expert code reviewer. Proactively reviews code for quality, security, and maintainability.
tools: Read, Grep, Bash
model: inherit
---
You are a senior code reviewer. Focus on security, correctness, and maintainability.

Questi file risiedono in entrambi .claude/agents/ (ambito del progetto) o ~/.claude/agents/ (ambito utente). I file di progetto hanno la precedenza, il che semplifica la condivisione e il controllo delle versioni dei subagenti.

Selezione del modello e strumenti

Campo modello: È possibile scegliere un alias di modello specifico per il subagente o lasciargli ereditare il modello della conversazione principale. Questo consente di trovare compromessi tra costi e qualità (ad esempio, utilizzare un modello più economico per i subagenti che analizzano grandi quantità di dati e un modello di qualità superiore per la sintesi finale).
Ambito dello strumento: Fornire a ciascun subagente un set minimo di strumenti riduce il raggio di esplosione e semplifica il ragionamento sulla sicurezza. Gli strumenti includono le primitive standard del codice Claude (Read, Grep, Bash, Edit, ecc.) e le integrazioni fornite da MCP.

Comportamento in fase di esecuzione e gestione del contesto

Quando Claude delega a un subagente, quest'ultimo riceve:

Il suo prompt di sistema (il contenuto YAML/Markdown).
Solo il contesto di cui ha bisogno (la sua finestra di contesto).
Accesso allo strumento come consentito nella sua configurazione.

Poiché ogni subagente mantiene un contesto isolato, le indagini lunghe o le analisi di file di grandi dimensioni possono essere scomposte in molti piccoli contesti anziché forzare un singolo contesto a contenere tutto: un vantaggio importante sia per l'affidabilità che per l'interpretabilità.

Modelli architettonici per subagente

L'architettura più comune è un orchestratore (agente principale) che scompone un'attività di alto livello, attiva più sottoagenti e quindi sintetizza o verifica i loro output. Due modelli canonici sono presenti in natura:

1) Orchestratore + Specialisti

Un agente (il orchestratore) coordina più subagenti in parallelo o in serie. L'orchestratore decide quale specialista chiamare, aggrega gli output, verifica la coerenza ed esegue l'integrazione finale. Questo è il comune approccio "il manager delega ai membri del team" e corrisponde a molti esempi e progetti consigliati nei materiali di Claude Code. I vantaggi includono parallelismo, una più chiara separazione delle problematiche e un più facile contenimento degli errori (un subagente difettoso ne compromette solo l'ambito).

Quando usarlo: attività complesse con sottoproblemi indipendenti (ad esempio, "generare test", "eseguire analisi statica", "riscrivere un modulo", quindi "integrare ed eseguire test end-to-end").

Compromessi: la logica di orchestrazione può diventare complessa; i round trip aggiuntivi possono aumentare leggermente la latenza.

2) Specialisti in pipeline/catenati

Qui i subagenti sono disposti in una sequenza in cui l'output di uno diventa l'input del successivo (ad esempio, spec → scaffold → implement → test → optimize). Si tratta essenzialmente di una composizione di funzioni espressa come agenti, utile quando sono necessarie trasformazioni graduali e garanzie rigorose sul flusso di dati tra le fasi. È concettualmente più semplice per i flussi di lavoro lineari e talvolta più facile da debuggare.

Quando usarlo: trasformazioni deterministiche in più fasi (ad esempio, la traduzione di un documento di progettazione in codice strutturato, quindi test, quindi ottimizzazioni).

Compromessi: meno naturale per attività che richiedono un'ampia esplorazione (ricerca, brainstorming) e un singolo collegamento interrotto può bloccare l'intera pipeline.

Cosa differenzia un subagente da un semplice prompt basato sul ruolo?

1) Finestre di contesto separate

Ogni subagente dispone di un proprio buffer di contesto che memorizza scambi, file e metadati rilevanti per il suo ruolo. Ciò impedisce che il contesto della sessione principale venga contaminato da messaggi intermedi rumorosi e consente inoltre di preservare, o limitare, la cronologia per ciascuna funzionalità. In questo modo, Claude Code consente di mantenere contesti di lunga durata e ad alto segnale per attività specializzate, senza dover sostenere il costo in token o l'overhead cognitivo di dover concentrare tutto in un unico prompt.

2) Prompt di sistema e personaggi

I subagenti vengono creati con istruzioni a livello di sistema che ne definiscono ruolo, tono e vincoli (ad esempio, "Agisci solo come specialista di refactoring; non eseguire comandi shell" o "Genera test unitari in stile pytest; usa solo interfacce pubbliche"). Questi prompt fungono da descrizioni di lavoro per il subagente e vengono applicati in fase di esecuzione dal runtime di Claude Code.

3) Associazioni di strumenti e ambito di autorizzazione

Una differenza pratica fondamentale: ai subagenti può essere concesso o negato l'accesso a strumenti specifici: file system, esecuzione di processi, API esterne o set di dati privilegiati. Ciò rende i subagenti potenti per privilegio minimo Progetti: un generatore di documentazione può essere bloccato dall'esecuzione di comandi arbitrari, mentre a un subagente CI viene concesso un sandbox isolato. Molti post della community promuovono l'abbinamento di subagenti con il Model Context Protocol (MCP) o un server MCP basato su hook per gestire l'accesso sicuro a segreti e I/O.

4) Scelta del modello e compromessi tra costi e prestazioni

Poiché i subagenti sono modulari, è possibile assegnare diversi modelli sottostanti a seconda della complessità dell'attività. Utilizzare un modello Sonnet ad alta capacità per il ragionamento approfondito o un modello Haiku leggero per attività rapide e ripetitive. Questa distribuzione eterogenea aiuta a bilanciare latenza, costo dei token e capacità. Gli aggiornamenti di prodotto e gli articoli della community di Anthropic enfatizzano la distribuzione parallela di modelli più piccoli per una scalabilità conveniente.

5) Modelli di comunicazione

I subagenti comunicano con l'orchestratore (o tra loro) tramite messaggi o file strutturati. I modelli tipici includono:

restituendo un payload JSON strutturato (preferito per l'orchestrazione programmatica),
scrivere su un file con ambito in uno spazio di lavoro condiviso,
oppure inviando un messaggio formattato finale all'orchestratore che include un punteggio di affidabilità e una motivazione.
Gli esperimenti della comunità dimostrano che i team preferiscono passaggi di consegne espliciti e leggibili dalle macchine per evitare ambiguità.

Vantaggi in termini di prestazioni

I sub-agenti non sono solo un dettaglio di design: se utilizzati correttamente, offrono prestazioni pratiche e vantaggi qualitativi.

1) Riduzione del tempo di clock tramite parallelismo

Distribuendo più worker contemporaneamente (ad esempio, un worker per cartella del repository, per microservizio o per blocco di dati), l'orchestratore riduce il tempo necessario per completare attività composite di grandi dimensioni. Casi d'uso come il triage delle segnalazioni di bug, la generazione di documentazione per molti moduli o l'audit di più servizi sono ideali. Significativi miglioramenti nei flussi di lavoro degli sviluppatori quando i carichi di lavoro sono realmente parallelizzabili.

Assegnando a ogni ruolo un contesto specifico, si evita il sovraccarico di prompt e si riduce il rischio di allucinazioni causato da rumore storico irrilevante. Ciò significa meno errori correlati al contesto e output più coerenti per attività specializzate. Gli articoli della community e le ricerche di Anthropic dimostrano che le configurazioni multi-agente spesso superano le prestazioni degli agenti monolitici nelle attività in ampiezza. Una valutazione interna di Anthropic ha segnalato notevoli miglioramenti per le attività di ricerca utilizzando un'architettura agente principale + subagenti.

Attenzione: il parallelismo produce i migliori risultati quando le sottoattività sono indipendenti. Se i lavoratori devono costantemente attendere l'uno all'altro o condividere lo stato pesante, si otterranno rendimenti decrescenti.

2) Migliore utilizzo del contesto e minore spreco di token

Invece di concentrare ogni risultato di ricerca intermedio in un unico contesto globale, i worker mantengono solo ciò che è rilevante all'interno della propria finestra e restituiscono output distillati. Ciò riduce il consumo di token per l'orchestratore e riduce il rischio di raggiungere i limiti di contesto: un vantaggio pratico quando si lavora con basi di codice di grandi dimensioni, log lunghi o repository di documenti di grandi dimensioni. La compattazione/riepilogazione dell'SDK estende ulteriormente la memoria effettiva degli agenti a lunga esecuzione.

3) Maggiore precisione dai prompt specialistici

Un sub-agente concepito come specialista con un ambito di azione ristretto può essere ottimizzato (tramite il suo prompt di sistema e il suo set di strumenti) per ottimizzare la precisione nel suo ambito: controlli di sicurezza, stile del codice o estrazione della conformità. I prompt con un ambito di azione ristretto tendono a ridurre le allucinazioni perché lo spazio di azione consentito all'agente e i risultati attesi sono limitati. Le organizzazioni segnalano risultati di qualità superiore per attività come la revisione automatica del codice quando utilizzano sub-agenti specifici per un dominio anziché chiedere a un generalista di fare tutto.

Come i team utilizzano effettivamente i subagenti: esempi di flussi di lavoro

Di seguito sono riportati alcuni esempi concreti per rendere tutto ciò meno astratto.

Esempio A — Pipeline di refactoring (Orchestratore + Specialisti)

L'orchestratore riceve una richiesta di "refactoring del componente X".
Chiamate dell'orchestratore analysis-subagent (nessun permesso di scrittura) per identificare i punti critici di complessità e le dipendenze rischiose.
Chiamate dell'orchestratore refactor-subagent (scrivere permessi in una sandbox simile a un ramo) per produrre file rielaborati.
Chiamate dell'orchestratore test-gen-subagent (di sola lettura sul codice) per produrre test unitari.
Orchestrator esegue CI con ci-runner-subagent (esecuzione sandbox) e aggrega i risultati per una revisione umana.
Questo schema isola ogni fase, contiene i rischi e mantiene ordinati i percorsi di controllo.

Esempio B — Ricerca + prototipo (Pipeline)

literature-subagent estrae e riassume i riferimenti (nessuna scrittura di file, accesso web regolamentato).
prototype-subagent costruisce un PoC minimo dal riepilogo.
benchmark-subagent esegue microbenchmark in una sandbox e riporta i risultati.
Questa catena rafforza la natura sequenziale delle attività di ricerca, mantenendo chiare le responsabilità.

Migliori pratiche e modelli

Progettazione e configurazione

Inizia con ruoli piccoli e ristretti. Rendi ogni subagente responsabile di un compito ben definito. Responsabilità più precise semplificano notevolmente il debug.
Controlla la versione del tuo .claude/agents/ cartella. Tratta le definizioni dei subagenti come codice: revisiona, testa e blocca le versioni. Questo riduce la deriva e semplifica gli audit.
Fissare intenzionalmente strumenti e modelli. Usa il model: inherit Se si desidera un comportamento coerente con la conversazione principale, specificare un alias di modello a basso costo per le scansioni in background. Bloccare gli strumenti per ridurre al minimo la superficie di attacco.

Modelli operativi

Utilizzare l'invocazione esplicita per l'automazione deterministica. Se si eseguono processi o hook CI, chiamare subagenti specifici per garantire risultati prevedibili.
Utilizzare la delega automatica nelle sessioni interattive. Per il lavoro esplorativo, lascia che Claude scelga dei subagenti per ridurre l'attrito, ma assicurati description i campi sono deliberati in modo che l'automazione non si attivi inaspettatamente.
Progettare output strutturati per la sintesi. Forzare i subagenti a scrivere su file o a produrre JSON che l'orchestratore possa leggere; ciò semplifica la fase di riduzione e l'audit.

Test, monitoraggio e governance

Creare valutazioni rappresentative. Monitora i punti in cui i subagenti falliscono e crea test che eseguano tali modalità di errore. Anthropic raccomanda set di test rappresentativi e miglioramenti iterativi.
Monitorare l'utilizzo di token e strumenti. Monitorare l'utilizzo di ciascun subagente e aggiungere avvisi per rilevare costi incontrollati o condizioni di limite di velocità.

Quando NON usare i subagenti

I subagenti sono potenti, ma non sempre rappresentano lo strumento giusto.

Compiti semplici: Per richieste brevi e una tantum o trasformazioni banali, i subagenti aggiungono complessità non necessarie.
Rigidi vincoli di latenza: I round-trip di orchestrazione aggiungono sovraccarico; se hai bisogno di risposte a un solo turno e con latenza estremamente bassa, un approccio monolitico potrebbe essere più semplice.
Piccoli team con poche infrastrutture: Senza strumenti per segreti, osservabilità e sandbox, i subagenti possono aumentare il rischio operativo. Gli articoli della community sottolineano l'importanza di iniziare in piccolo e di aggiungere subagenti quando è necessaria la modularità.

Dove utilizzare il codice Claude CLI è il più consigliato

È stato un grande piacere annunciare che CometAPI ora supporta pienamente la potente interfaccia CLI di Claude Code. Per utilizzare il modello API Comet su Claude Code, è sufficiente installare Claude Code ed eseguire l'autenticazione con la chiave API Comet ottenuta e l'indirizzo di base.

Perché utilizzare il codice Claude tramite CometAPI?

Principali funzionalità dell'intelligenza artificiale: genera, esegui il debug e ottimizza facilmente il codice utilizzando modelli creati appositamente per gli sviluppatori.

Selezione flessibile dei modelli: la nostra ampia gamma di modelli ti consente di svilupparti in modo più fluido.
Integrazione perfetta: le API sono sempre disponibili. Integra Claude Code direttamente nel tuo flusso di lavoro esistente in pochi minuti.
Utilizzando Claude Code tramite CometAPI si risparmieranno più costiL'API Claude fornita da CometAPI ha uno sconto del 20% sul prezzo ufficiale ed è aggiornata con l'ultimo modello ufficiale.

Pronto per usare Claude Code cli? consulta il Guida API per le istruzioni dettagliate.

Se vuoi conoscere altri suggerimenti, guide e novità sull'IA seguici su VK, X e al Discordia!

Vedere anche Come installare ed eseguire Claude Code tramite CometAPI?

Conclusione: perché i subagenti sono importanti oggi

I subagenti rendono pratica la promessa di flussi di lavoro agentici per i team: consentono di ragionare su ruoli, permessi, contesto, costi e parallelizzazione in modo esplicito e come oggetti di prima classe. Se utilizzati con giudizio, i subagenti consentono una maggiore velocità di sviluppo, una migliore qualità nelle attività multi-step e una governance più prevedibile. Il rovescio della medaglia è che è necessario progettare, testare e monitorare questi subagenti proprio come il software di produzione, ma questo investimento trasforma un'ingegneria tempestiva in una pratica ingegneristica affidabile.