I subagenti nell’SDK di Claude Code sono IA specializzate che vengono orchestrate dall’agente principale. Usa i subagenti per la gestione del contesto e la parallelizzazione. Questa guida spiega come le applicazioni SDK interagiscono con e utilizzano i subagenti che vengono creati tramite file markdown.

​
Panoramica

I subagenti vengono creati esclusivamente attraverso l’approccio basato sul filesystem posizionando file markdown con frontmatter YAML in directory designate. L’SDK può quindi invocare questi subagenti predefiniti durante l’esecuzione.

​
Vantaggi dell’Utilizzo dei Subagenti

​
Gestione del Contesto

I subagenti mantengono un contesto separato dall’agente principale, prevenendo il sovraccarico di informazioni e mantenendo le interazioni focalizzate. Questo isolamento assicura che i compiti specializzati non inquinino il contesto della conversazione principale con dettagli irrilevanti. Esempio: Un subagente research-assistant può esplorare dozzine di file e pagine di documentazione senza ingombrare la conversazione principale con tutti i risultati di ricerca intermedi - restituendo solo i risultati rilevanti.

​
Parallelizzazione

Più subagenti possono funzionare contemporaneamente, accelerando drammaticamente i flussi di lavoro complessi. Esempio: Durante una revisione del codice, puoi eseguire i subagenti style-checker, security-scanner e test-coverage simultaneamente, riducendo il tempo di revisione da minuti a secondi.

​
Istruzioni e Conoscenze Specializzate

Ogni subagente può avere prompt di sistema personalizzati con competenze specifiche, migliori pratiche e vincoli. Esempio: Un subagente database-migration può avere conoscenze dettagliate sulle migliori pratiche SQL, strategie di rollback e controlli di integrità dei dati che sarebbero rumore inutile nelle istruzioni dell’agente principale.

​
Restrizioni degli Strumenti

I subagenti possono essere limitati a strumenti specifici, riducendo il rischio di azioni non intenzionali. Esempio: Un subagente doc-reviewer potrebbe avere accesso solo agli strumenti Read e Grep, assicurando che possa analizzare ma mai modificare accidentalmente i tuoi file di documentazione.

​
Creazione dei Subagenti

I subagenti sono definiti come file markdown in directory specifiche:
  • Livello progetto: .claude/agents/*.md - Disponibili solo nel progetto corrente
  • Livello utente: ~/.claude/agents/*.md - Disponibili in tutti i progetti

​
Formato del File

Ogni subagente è un file markdown con frontmatter YAML: 
---
name: code-reviewer
description: Specialista esperto nella revisione del codice. Usa per revisioni di qualità, sicurezza e manutenibilità.
tools: Read, Grep, Glob, Bash  # Opzionale - eredita tutti gli strumenti se omesso
---

Il prompt di sistema del tuo subagente va qui. Questo definisce il ruolo,
le capacità e l'approccio del subagente per risolvere i problemi.

Includi istruzioni specifiche, migliori pratiche e qualsiasi vincolo
che il subagente dovrebbe seguire.

​
Campi di Configurazione

CampoRichiestoDescrizione
nameSìIdentificatore unico usando lettere minuscole e trattini
descriptionSìDescrizione in linguaggio naturale di quando usare questo subagente
toolsNoLista separata da virgole degli strumenti consentiti. Se omesso, eredita tutti gli strumenti

​
Come l’SDK Usa i Subagenti

Quando si usa l’SDK di Claude Code, i subagenti definiti nel filesystem sono automaticamente disponibili. Claude Code:
  1. Rileva automaticamente i subagenti dalle directory .claude/agents/
  2. Li invoca automaticamente basandosi sulla corrispondenza dei compiti
  3. Usa i loro prompt specializzati e le restrizioni degli strumenti
  4. Mantiene contesti separati per ogni invocazione di subagente
L’SDK rispetta la configurazione del filesystem - non c’è modo programmatico di creare subagenti a runtime. Tutti i subagenti devono essere definiti come file prima dell’esecuzione dell’SDK.

​
Esempi di Subagenti

Per esempi completi di subagenti inclusi revisori di codice, esecutori di test, debugger e auditor di sicurezza, vedi la guida principale sui Subagenti. La guida include configurazioni dettagliate e migliori pratiche per creare subagenti efficaci.

​
Modelli di Integrazione SDK

​
Invocazione Automatica

L’SDK invocherà automaticamente i subagenti appropriati basandosi sul contesto del compito. Assicurati che il campo description del tuo subagente indichi chiaramente quando dovrebbe essere usato: 
---
name: performance-optimizer
description: Usa PROATTIVAMENTE quando le modifiche al codice potrebbero impattare le prestazioni. DEVE ESSERE USATO per compiti di ottimizzazione.
tools: Read, Edit, Bash, Grep
---

​
Invocazione Esplicita

Gli utenti possono richiedere subagenti specifici nei loro prompt: 
// Quando si usa l'SDK, gli utenti possono richiedere esplicitamente i subagenti:
const result = await query({
  prompt: "Usa il subagente code-reviewer per controllare il modulo di autenticazione"
});

​
Restrizioni degli Strumenti

I subagenti possono avere accesso limitato agli strumenti tramite il campo tools:
  • Ometti il campo - Il subagente eredita tutti gli strumenti disponibili (predefinito)
  • Specifica gli strumenti - Il subagente può usare solo gli strumenti elencati
Esempio di un subagente di analisi in sola lettura: 
---
name: code-analyzer
description: Analisi statica del codice e revisione dell'architettura
tools: Read, Grep, Glob  # Nessun permesso di scrittura o esecuzione
---

Sei un analista dell'architettura del codice. Analizza la struttura del codice,
identifica i modelli e suggerisci miglioramenti senza apportare modifiche.

​
Documentazione Correlata