I subagenti sono una delle aggiunte più utili all'ecosistema Claude Code/Claude Agent: consentono di suddividere flussi di lavoro complessi in "compagni di squadra" di intelligenza artificiale più piccoli e specializzati, preservare il contesto del thread principale e limitare in modo sicuro l'accesso agli strumenti. Questo articolo spiega cosa sono i subagenti, come crearli e invocarli (CLI, file system e SDK), il Principi di progettazione dovresti seguire quando li costruisci, e codice campione concreto puoi copiare e adattare.
Cosa sono i subagenti?
A subagente è un assistente AI preconfigurato e con un ambito di applicazione ristretto a cui Claude Code (o Claude Agent SDK) può delegare il lavoro. Ogni subagente:
- Ha un nome univoco e una chiara descrizione dello scopo.
- Corre nel suo finestra di contesto personale separato dalla conversazione principale (in modo che lunghe catene di dettagli non inquinino il contesto dell'orchestratore).
- Può essere configurato con un set limitato di strumenti (lettura/scrittura di file, bash, grep, strumenti MCP, ecc.) e con una scelta di modello specifica.
- Contiene un prompt di sistema (personalità e istruzioni del subagente) che guida il comportamento e i vincoli.
Queste proprietà rendono i subagenti ideali per attività che richiedono molti token (ricerca, ricerca di log di grandi dimensioni), che richiedono sicurezza (scansione o strumenti potenzialmente distruttivi) o che sono ripetitive e ben specificate (controllo dello stile, esecuzione di test).
Anthropic è stato in rapida evoluzione: la CLI di Claude Code e l'Agent SDK sono stati ristrutturati ed estesi in SDK dell'agente Claude, è stato introdotto il supporto dei plugin per il raggruppamento di agenti e personalizzazioni correlate (comandi slash, server MCP, hook) e Abilità fornire un modo per impacchettare i flussi di lavoro di dominio per il riutilizzo su Claude.ai, Claude Code e Agent SDK. Questi aggiornamenti semplificano condividere, installare e versione subagenti tra team e progetti. Se si prevede di creare flussi di lavoro di produzione, è opportuno valutare il packaging di plugin/competenze e i modelli di distribuzione basati su SDK.
Perché i subagenti sono importanti
Tre motivi per cui sono immediatamente utili:
- Conservazione del contesto — ricerche lunghe o rumorose, test o scansioni risiedono all'interno di un subagente invece di sovraccaricare il contesto primario. Ciò riduce lo spreco di token e rende i risultati più facili da analizzare.
- Competenza specializzata — è possibile codificare la conoscenza del dominio e il comportamento in un prompt di sistema su misura per l'attività (ad esempio, un
security-auditorche si concentra su segreti, problemi di dipendenza e utilizzo non sicuro della shell). - Permessi più sicuri — la limitazione degli strumenti per subagente riduce il raggio di esplosione (un revisore di documenti potrebbe avere strumenti di sola lettura; un test-runner ha
Bashma noEdit). - Parallelizzazione: È possibile avviare più subagenti da eseguire contemporaneamente (ad esempio:
style-checker,security-scanner,test-runner) e poi raccogliere i loro brevi risultati: una grande vittoria per i costosi controlli indipendenti.
Prerequisiti per l'utilizzo dei subagenti nel codice Claude
Prima di iniziare a creare i subagenti, assicurati di avere a disposizione quanto segue:
1) Codice Claude installato e autenticato
Installa Claude Code CLI o usa le integrazioni web/IDE. Documentazione di avvio rapido e configurazione di CometAPI elenca i metodi di installazione supportati (pacchetto globale npm o installatori nativi) e mostra come verificare l'installazione con claude --version / claude doctor. Avrai anche bisogno di un CometaAPI account (utilizzare la chiave CometAPI per accedere al codice Claude è più economico e comodo rispetto al modello ufficiale), come indicato nella Guida introduttiva.
2) Nodo/ambiente (per alcuni percorsi di installazione) e strumenti di shell di base
Se si installa tramite il pacchetto npm, si dovrebbe avere Node.js (Node 18+ è comune negli esempi). Se si intende utilizzare l'Agent SDK (JavaScript/TypeScript o Python), sarà necessario un progetto con la dipendenza SDK installata. Molti tutorial presuppongono l'utilizzo di strumenti di sviluppo standard (git, bash, opzionale). gh CLI per flussi di lavoro GitHub).
3) Layout del progetto e CLAUDE.md
La migliore pratica è quella di mantenere la documentazione di supporto a livello di repository (CLAUDE.md) e per inserire agenti con ambito di progetto in .claude/agents/ quindi i compagni di squadra li ereditano. I file CLAUDE.md vengono automaticamente inseriti nel contesto di Claude e aiutano a guidare il comportamento in modo coerente tra le sessioni; ogni subagente è un file Markdown con frontmatter YAML. Esempio minimo:
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.
Return results in JSON with fields: summary, issues.
nameè un identificatore in minuscolo.descriptionguida l'invocazione e l'abbinamento automatici.toolslimita l'accesso agli strumenti (omette di ereditare tutto).modelpuò esseresonnet,opus,haiku, oinherit.
4) Permessi e server MCP (facoltativi ma comuni)
Se i tuoi flussi di lavoro utilizzano server Model Context Protocol (MCP) o strumenti esterni (Puppeteer, Sentry, strumenti REST personalizzati), assicurati che i server MCP siano configurati e raggiungibili. Per operazioni sensibili (scrittura, bash, git commit), sii consapevole della allowlist e del per-agent. tools definizione dell'ambito.
Come creare subagenti in Claude Code
È possibile creare subagenti in tre modi principali: tramite la CLI interattiva (/agents), come file markdown del file system, oppure programmaticamente tramite l'Agent SDK. Di seguito sono riportate le opzioni dettagliate:
Claude Code supporta tre modi pratici per creare subagenti:
- CLI interattivo
/agentsUI — il più veloce per la creazione iterativa all'interno di una sessione. - Basato su file system — crea file Markdown con frontmatter YAML in
.claude/agents/(a livello di progetto) o~/.claude/agents/(livello utente). Gli agenti di progetto hanno una priorità più alta. - Programmatico (Agent SDK) — definire i subagenti nel codice tramite
agentsparametro quando si chiamaquery(); consigliato per app basate su SDK. Questo approccio è ideale quando i subagenti devono essere creati dinamicamente o incorporati in un'applicazione.
Flusso interattivo rapido (primo passaggio consigliato)
- Avvia Claude Code nel tuo terminale o apri la palette dei comandi in VS Code.
- Eseguire l'interfaccia dei subagenti con il comando slash:
/agents
- Scegli Crea nuovo agente, seleziona l'ambito a livello di progetto o a livello di utente, compila nome/descrizione/strumenti/prompt di sistema e salva. Puoi generare una bozza con Claude e poi perfezionarla. Una volta salvata, l'agente è disponibile in
/agentse può essere invocato in modo esplicito o automatico.
Subagenti basati sul file system (Markdown + frontmatter YAML)
I subagenti sono archiviati come file Markdown con frontmatter YAML. Inseriteli in:
- Ambito del progetto
.claude/agents/*.md(massima priorità) - Ambito utente:
~/.claude/agents/*.md
Struttura di base del file:
---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash # optional; omit to inherit
model: sonnet # optional; or 'inherit'
---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet
Alcune note di implementazione:
namedeve essere in minuscolo con trattini.- omettendo
toolsconsentirà al subagente di ereditare tutti gli strumenti del thread principale; elencare esplicitamente gli strumenti impone un modello di privilegi minimi. - Usa il
model: 'inherit'per un comportamento coerente con il thread principale, oppure specificare un alias del modello (ad esempio,sonnet,opus,haiku).
Definizione JSON CLI (utilizzo ad hoc/sessione)
È possibile definire subagenti temporanei in linea quando si avvia una sessione:
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer.",
"prompt": "You are a senior code reviewer. Focus on security and best practices.",
"tools": ,
"model": "sonnet"
}
}'
Gli agenti definiti dalla CLI sono utili per esecuzioni o esperimenti con script; hanno una priorità inferiore rispetto agli agenti di progetto ma superiore rispetto agli agenti utente.
Definizione programmatica (Agent SDK, consigliato per le app)
Se stai creando un'applicazione o un'automazione, definisci i subagenti a livello di programmazione tramite l'Agent SDK agents parametro (questa è l'opzione più integrata). Esempio (TypeScript):
import { query } from '@anthropic-ai/claude-agent-sdk';
async function runReview() {
const result = await query({
prompt: "Assess the authentication module for security issues",
options: {
agents: {
"code-reviewer": {
description: "Expert code review specialist",
prompt: `You are a code review specialist...`,
tools: ,
model: "sonnet"
},
"test-runner": {
description: "Runs the test suite and analyzes failures",
prompt: `You run tests and summarize failures...`,
tools: ,
model: "sonnet"
}
}
}
});
console.log(result);
}
L'SDK accetta anche agenti basati sul file system (caricherà .claude/agents/ file) se preferisci questo schema. Gli agenti programmatici sono potenti per flussi di lavoro dinamici e integrazione CI.
Per Python, il claude-agent-sdk il pacchetto supporta modelli simili: puoi usare query() or ClaudeSDKClient e configurare opzioni, strumenti e server MCP a livello di codice. Consultare il repository Python SDK per esempi di avvio rapido.
Come richiamare i subagenti
Delega automatica
Il codice Claude può automaticamente Scegli un subagente quando un prompt utente corrisponde allo scopo del subagente. Questo è utile per l'orchestrazione in background, in cui l'agente principale indirizza automaticamente le attività allo specialista corretto. Affidati a descrizioni chiare dei subagenti e a prompt di sistema mirati per migliorare la precisione della selezione automatica.
Invocazione esplicita (consigliata per chiarezza)
È possibile richiamare esplicitamente un agente in una conversazione:
> Use the code-reviewer subagent to check my recent changes
L'invocazione esplicita è deterministica e consigliata per i flussi di produzione in cui si desidera evitare deleghe impreviste.
Modelli di orchestrazione SDK
Modelli comuni nelle app SDK:
- Forchetta + raccogli: Avvia più subagenti in parallelo, raccogli la risposta concisa di ciascun agente, quindi riepiloga/unisci i risultati nell'agente principale.
- Ciclo di supervisione: L'orchestratore assegna compiti ai subagenti, esamina i risultati e li accetta oppure richiede un ricalcolo/un chiarimento.
- Esecuzione in modalità sandbox: Assegnare capacità potenzialmente pericolose (distribuzione, esecuzione di script) a un agente con vincoli rigidi e richiedere esplicitamente l'approvazione umana prima dell'esecuzione.
Questi modelli sono mappati su implementazioni pratiche utilizzando la gestione delle sessioni, gli hook e gli strumenti MCP dell'Agent SDK.
Come realizzare subagenti utili, sicuri e componibili
1) Responsabilità unica e richieste chiare
Ogni subagente dovrebbe avere uno scopo chiaro e un prompt di sistema che specifichi limiti, criteri di successo e formato di output. Se l'output desiderato è strutturato (JSON, elenco puntato, patch di codice), impartire istruzioni precise al subagente per ridurre gli errori di analisi.
2) Minimo privilegio per gli strumenti
Concedi solo gli strumenti di cui un subagente ha bisogno. Ad esempio, un revisore di documenti non ha bisogno Write or Bash. Imposta come predefinita la modalità di sola lettura ove possibile e aumenta esplicitamente le autorizzazioni degli strumenti quando necessario. Questo riduce i rischi e semplifica l'audit.
3) Restituire output compatti e strutturati
I subagenti dovrebbero tornare risposte concise e definitive piuttosto che tracce di pensiero di lunga durata. Uno schema comune è: eseguire un lavoro pesante nel contesto del subagente, quindi restituire un breve riepilogo con allegati (patch, riferimenti a file, JSON). Questo massimizza l'efficienza del contesto per l'orchestratore.
4) Testabilità e controllo delle versioni
Memorizzare i file dei subagenti nel controllo di versione, creare test di integrazione continua (CI) che eseguano esecuzioni reali su input di piccole dimensioni e bloccare modelli/set di strumenti. Se si fa affidamento su competenze e plugin, adottare i modelli di marketplace/versioning dei plugin per gestire aggiornamenti e rollback.
5) Ganci di controllo e punti di controllo con intervento umano
Utilizzare gli hook dell'SDK per intercettare le chiamate degli strumenti (hook PreToolUse) e richiedere l'approvazione umana per le azioni distruttive. Registrare tutte le chiamate degli strumenti per audit riproducibili. L'SDK fornisce meccanismi di hook e autorizzazioni per supportare questo schema.
Esempio di applicazione: una piccola pipeline di tipo produttivo
Di seguito è riportato un esempio compatto che mostra i componenti tipici: un agente del file system, un'invocazione SDK che utilizza due agenti (uno per la revisione, uno per i test) e una semplice orchestrazione.
1) Agente del file system: .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
"summary": "one-line summary",
"issues": ,
"recommended_changes":
}
2) Orchestrazione programmatica (Node.js)
import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';
async function runPipeline() {
const result = query({
prompt: 'Run PR checks: security review then unit tests.',
options: {
agents: {
'code-reviewer': {
description: 'Use PROACTIVELY after code changes; output JSON with issues.',
prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
tools: ,
model: 'sonnet'
},
'test-runner': {
description: 'Run test suite and summarize failing tests.',
prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
tools:
}
}
}
});
for await (const message of result) {
// Implement streaming logic: messages may include subagent outputs
console.log(message);
}
}
runPipeline().catch(console.error);
Note: , il code-reviewer è memorizzato nel repository per il riutilizzo da parte del team; la chiamata SDK dimostra che gli agenti programmatici hanno la precedenza e tools la definizione dell'ambito impedisce scritture accidentali.
Argomenti e modelli avanzati
Configurazione dinamica dell'agente
Creare fabbriche di agenti parametrizzati che scelgono modelli e set di strumenti in base all'ambiente (sviluppo vs. produzione) o ai livelli di gravità (ad esempio, strict vs balanced modalità di sicurezza). Gli esempi SDK mostrano come generare definizioni di agenti in fase di esecuzione.
Parallelizzazione
È possibile eseguire lo spin-off di più agenti di analisi di sola lettura in parallelo (stile, sicurezza, copertura dei test) e aggregare i loro output JSON nel thread principale. Questo riduce notevolmente i tempi di elaborazione per i repository di grandi dimensioni.
Agenti forniti dal plugin
I plugin possono fornire subagenti confezionati con il manifesto del plugin; appaiono in /agents insieme ad agenti personalizzati e può essere invocato esplicitamente. Utilizzalo per distribuire agenti standardizzati tra i team.
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?
Conclusioni
Trattare i subagenti come micro-personaggi riutilizzabili e con più versioniInizia in piccolo: crea un doc-reviewer e test-runner per un repository, controllali .claude/agents/e automatizzarli in CI utilizzando headless claude -pRipeti i tuoi prompt, aggiungi output strutturati e rafforza le autorizzazioni degli strumenti.
Il modello mentale più utile: immagina Claude come project manager e i subagenti come specialisti del team. Il manager delega compiti formulati in modo chiaro, aggrega i risultati degli specialisti e scrive il report finale. Col tempo, noterai miglioramenti in termini di affidabilità, testabilità e capacità di automatizzare ampie porzioni dei flussi di lavoro degli sviluppatori.