Subagent

I subagent permettono all’agente principale di avviare worker indipendenti per gestire sottoattività. Un subagent condivide strumenti e contesto della codebase con l’agente principale, ma opera nella propria catena di conversazione — non eredita la cronologia delle conversazioni dell’agente principale. Questo è utile per attività che beneficiano di un lavoro mirato e indipendente — come esplorare una codebase, eseguire test o implementare una funzionalità in parallelo. Puoi chiedere esplicitamente all’agente di usare i subagent (ad es. “analizza come funziona l’auth in un subagent”), oppure l’agente può decidere autonomamente di delegare quando ritiene che un’attività trarrebbe vantaggio da un lavoro indipendente. Secondo le nostre misurazioni, i subagent sia migliorano le prestazioni complessive di sviluppo sia riducono i costi.

Come funzionano i subagent

Quando l’agente genera un subagent, seleziona uno dei profili di subagent disponibili e sceglie se il subagent deve essere eseguito in foreground o in background. I subagent possono essere eseguiti in due modalità:

Foreground

Viene eseguito inline nella tua sessione. L’agente principale si mette in pausa e aspetta che il subagent termini prima di continuare. Puoi approvare o rifiutare le richieste di utilizzo degli strumenti man mano che vengono presentate.

Background

Viene eseguito in parallelo mentre l’agente principale continua a lavorare. L’agente principale riceve automaticamente una notifica quando il subagent termina. Gli strumenti non approvati vengono rifiutati automaticamente.

Non vedi direttamente l’output grezzo del subagent. Quando un subagent termina, l’agente principale legge il risultato e ne riepiloga per te i risultati principali e le azioni.

Costo dei subagenti

I subagenti vengono eseguiti come sessioni di agent separate, ciascuna con la propria finestra di contesto e le proprie chiamate di inferenza, quindi generano costi indipendentemente dall’agente principale. La spesa dell’agente principale copre solo il proprio lavoro; ogni subagente che avvia aggiunge inoltre il proprio utilizzo.

Nei piani basati sui prompt, ogni subagent consuma crediti aggiuntivi, proprio come un messaggio dell’utente. Il numero di crediti dipende dal modello usato dal subagent, quindi le attività che generano più subagent (o li annidano) consumano più crediti.

Poiché il costo cresce con il numero di subagenti, le attività che si suddividono in molti subagenti (o li annidano) costano di più. Usa i subagenti con criterio quando il parallelismo o un contesto più mirato giustificano la spesa aggiuntiva.

Quale modello usa un subagent?

I subagent non usano tutti il modello selezionato nel selettore del modello. Ogni profilo determina da dove proviene il modello:

Profilo	Modello usato	Effetto sulla quota / sui crediti
`subagent_explore`	Il modello predefinito dei subagent — un modello veloce ed economico (SWE-1.6 per impostazione predefinita)	Economico: l’utilizzo di SWE-1.6 viene addebitato alle tariffe SWE, non a quelle del modello principale
`subagent_general`	Lo stesso modello dell’agente principale — quello che hai selezionato nel selettore del modello (ad es. Claude Opus, GPT-5)	Stessa tariffa dell’agente principale: un subagent general costa quanto un’intera sessione aggiuntiva sul modello selezionato
Subagent personalizzati	Il campo `model` nel file di definizione, se impostato; altrimenti il modello predefinito dei subagent	Dipende dal modello che blocchi

subagent_general eredita il modello dell’agente principale. Se stai usando un modello premium, anche ogni subagent general userà quel modello premium, con una propria finestra di contesto e chiamate di inferenza dedicate — quindi un’attività che si dirama in diversi subagent general moltiplica la spesa. Chiedi un subagent explore (o un subagent personalizzato con un model: più economico bloccato) quando il lavoro riguarda la ricerca più che le modifiche al codice.

Il modello predefinito dei subagent non è un nome di modello fisso — viene risolto tramite un router al momento della creazione del subagent, e un admin può impostare un override (vedi sotto). Con l’impostazione predefinita Subagent router, viene risolto in SWE-1.6 (una variante più veloce o più lenta di SWE-1.6 a seconda del livello del tuo piano).

Al momento, la CLI non indica nel pannello dei subagent quale modello sta usando un subagent in esecuzione.

Come influenzare il modello

Non c’è modo di indicare un modello per un subagent in un prompt: il tool run_subagent accetta un profilo, non un modello. Hai due possibilità:

Chiedere un profilo in linguaggio naturale. Richiedere un subagent explore (“research how auth works in an explore subagent”) mantiene il lavoro sul modello predefinito a basso costo del subagent. Se chiedi modifiche al codice, viene usato subagent_general, che gira sul modello che hai selezionato.
Bloccare un modello in un profilo subagent personalizzato. model: nel file di definizione è l’unico modo per eseguire un subagent con capacità di scrittura su un modello diverso da quello dell’agente principale. Anche una skill eseguita in un subagent può impostare model: nel suo frontmatter per fare override del modello del profilo.

Controlli Enterprise

Gli amministratori possono gestire quale modello usano i subagent — e se i subagent vengono eseguiti o meno — tramite l’impostazione Modello predefinito dei subagent nelle Settings dell’org/Enterprise. Questa impostazione controlla il modello per subagent_explore e per i subagent personalizzati che non bloccano un model: — non modifica subagent_general, che segue sempre il modello dell’agente principale.

Impostazione del modello predefinito dei subagent

Ha tre opzioni:

Opzione	Comportamento
Router dei subagent (predefinito)	Il modello predefinito dei subagent viene scelto da un router al momento dell’avvio. Attualmente corrisponde a SWE-1.6 (la variante esatta dipende dal livello del tuo piano).
Un modello specifico	Blocca il modello predefinito dei subagent sul modello selezionato, per ogni subagent che non usa il modello dell’agente principale.
Nessuno	Disabilita completamente i subagent — Devin non creerà alcun subagent.

Abilitare e disabilitare i subagent

I subagent sono abilitati per impostazione predefinita. Imposta subagents_enabled su false nel tuo file di configurazione per rimuovere gli strumenti run_subagent e read_subagent, così l’agente eseguirà tutto autonomamente:

// ~/.config/devin/config.json
{
  "subagents_enabled": false
}

La modifica viene applicata in tempo reale: una sessione in corso la recepisce senza dover essere riavviata. In Devin Desktop, la stessa funzionalità è disponibile tramite il toggle Subagents (Anteprima) nelle Settings.

I criteri dell’organizzazione hanno la precedenza: se un Admin ha impostato Default subagent model su None, i subagent restano disabilitati indipendentemente da questa impostazione.

Profili dei subagenti

Ogni subagente opera con un profilo specifico che ne determina le capacità. Sono disponibili due profili predefiniti:

Profilo	Descrizione	Accesso agli strumenti	Modello
`subagent_explore`	Esplorazione e ricerca del codebase in sola lettura	Strumenti del codebase in sola lettura più ricerca sul web; non può modificare file né recuperare URL arbitrari (sia in foreground che in background)	Modello predefinito del subagente (SWE-1.6 per impostazione predefinita)
`subagent_general`	Attività generiche, incluse modifiche al codice	Accesso completo agli strumenti (foreground) oppure solo agli strumenti pre-approvati (background)	Stesso modello dell’agente principale

L’agente sceglie automaticamente il profilo appropriato in base all’attività. I subagenti di esplorazione sono ideali per la ricerca e per comprendere il codebase, mentre i subagenti generali possono apportare modifiche. Vedi Quale modello usa un subagente? per capire come ogni profilo sceglie il proprio modello: i due profili non vengono eseguiti sullo stesso modello.

Puoi anche definire profili personalizzati per i subagenti: vedi Subagenti personalizzati più sotto.

Autorizzazioni degli strumenti

Il modo in cui funzionano le autorizzazioni degli strumenti dipende dal fatto che il subagent sia in esecuzione in foreground o in background:

I subagent in foreground si comportano come l’agente principale: ti viene chiesto di approvare o negare le chiamate agli strumenti, come di consueto. Il prompt indica il subagent che ha richiesto l’azione, così sai chi sta chiedendo.
I subagent in background ereditano tutte le autorizzazioni degli strumenti che hai già concesso nella sessione corrente. Qualsiasi strumento che non sia stato pre-approvato viene negato automaticamente. I subagent in background non possono chiederti nuove autorizzazioni.

Se un subagent in background fallisce perché l’accesso a uno strumento richiesto è stato negato, puoi riprenderlo in foreground per approvare le autorizzazioni necessarie. Vedi Riprendere i subagent qui sotto.

Monitoraggio dei subagenti

Indicatore del subagente

Quando i subagenti in background sono attivi, sotto l’area di input compare un indicatore che ne mostra lo stato. Puoi raggiungere l’indicatore premendo ↓ dall’area di input, quindi premere Enter per aprire il pannello del subagente. Quando un subagente in primo piano è attivo, l’indicatore di caricamento mostra “Subagent in esecuzione · Ctrl+B per eseguire in background”.

Pannello dei subagent

Il pannello dei subagent consente di visualizzare e gestire tutti i subagent attivi e conclusi. Mostra il profilo, il titolo, lo stato, il tempo trascorso e il numero di chiamate agli strumenti di ciascun subagent. L’attività dei subagent persiste dopo il ricaricamento di una sessione, quindi il pannello continua a mostrare i subagent dopo la ripresa.

Passaggio tra foreground e background

Puoi spostare i subagenti tra foreground e background mentre sono in esecuzione:

Spostare in background un subagente in foreground: Premi Ctrl+B mentre è in esecuzione un subagente in foreground. Il subagente continua a lavorare in background e l’agente principale riprende.
Portare in foreground un subagente in background: Apri il pannello dei subagenti e premi f su un subagente in background in esecuzione. L’output del subagente verrà visualizzato inline.

Quando sposti un subagente in background, la chiamata a uno strumento dell’agente principale è già terminata, quindi l’agente principale continua in modo indipendente. Il risultato del subagente non verrà reinserito nella pipeline corrente dell’agente principale, ma riceverai una notifica quando avrà completato l’esecuzione.

Interrompere un turno

L’interruzione dell’agente non termina i suoi subagent. I subagent in esecuzione vengono sospesi mantenendo intatto il loro stato e riprendono con il messaggio successivo, quindi interrompere l’agente principale per reindirizzarlo non comporta la perdita del lavoro in corso.

Annullare i subagenti

Puoi annullare un subagente in esecuzione in due modi:

Dal pannello dei subagenti: Apri il pannello e premi x per un subagente in esecuzione.
Subagente in primo piano: Premi Ctrl+C o Esc per annullare il subagente in primo piano attualmente in esecuzione.

Ripresa dei subagenti

I subagenti annullati, terminati con errore o completati possono essere ripresi con un nuovo prompt. Puoi chiedere all’agente di riprendere un subagente e questo continuerà da dove si era interrotto. I subagenti ripresi vengono sempre eseguiti in primo piano, così puoi approvare eventuali invocazioni degli strumenti che erano state precedentemente negate. Questo è particolarmente utile quando:

Un subagente in background è terminato con errore perché è stato negato uno strumento richiesto: riprendilo in primo piano per concedere le autorizzazioni necessarie.
Un subagente è stato completato, ma vuoi che esegua ulteriore lavoro di follow-up in base ai risultati ottenuti.
Un subagente è stato annullato prematuramente e vuoi che continui.

Profondità di annidamento

Per impostazione predefinita, i subagenti non possono generare altri subagenti: solo l’agente radice può farlo. Gli strumenti del subagente (run_subagent e read_subagent) sono disabilitati all’interno di un subagente per evitare un annidamento illimitato. Tuttavia, i profili personalizzati dei subagenti possono abilitare la generazione nidificata impostando il campo max-nesting nel proprio frontmatter. Questo valore sovrascrive la profondità massima predefinita, consentendo ai subagenti di generare elementi figli finché l’albero rimane entro quel limite. Ad esempio, max-nesting: 3 consente la seguente catena:

Root agent (depth 0)
└── Custom subagent (depth 1) — può generare figli
    └── Child subagent (depth 2) — può generare figli
        └── Grandchild subagent (depth 3) — non può generare (limite di profondità raggiunto)

I subagenti annidati possono aumentare significativamente i costi. Ogni livello di annidamento genera agenti aggiuntivi con proprie finestre di contesto e chiamate di inferenza. Utilizza questa funzionalità con attenzione.

Subagenti personalizzati

I subagenti personalizzati sono sperimentali. Il formato, il comportamento e le opzioni di configurazione potrebbero cambiare nelle prossime versioni.

Oltre ai profili integrati subagent_explore e subagent_general, puoi definire profili personalizzati per i tuoi subagenti. I subagenti personalizzati ti consentono di creare worker specializzati con prompt di sistema dedicati, restrizioni sugli strumenti e override del modello, pensati per attività specifiche nel tuo flusso di lavoro. Questo è anche il modo per ottenere un subagent con capacità di scrittura che non utilizzi il tuo modello primario (potenzialmente costoso): assegnagli un model: e gli strumenti di cui ha bisogno.

Creazione di un subagent personalizzato

I subagent personalizzati vengono definiti come file markdown in agents/, secondo uno di questi due layout:

File singolo — agents/<name>.md (la stessa convenzione usata da Claude Code, Cursor e altri strumenti). Il nome del file (senza .md) diventa l’identificatore del profilo.
Directory — agents/<name>/AGENT.md. Il nome della directory diventa l’identificatore del profilo. Sono accettati come nome file anche AGENTS.md, agent.md e agents.md (se ne sono presenti più di uno, AGENT.md ha la precedenza, poi AGENTS.md, agent.md, agents.md).

In entrambi i layout, un campo name: nel frontmatter ha la precedenza sull’identificatore ricavato dal percorso.

Specifico del progetto
Globale

.devin/agents/
├── reviewer.md
└── researcher/
    └── AGENT.md

Sono supportati anche:

.agents/agents/
├── reviewer.md
└── researcher/
    └── AGENT.md

# Linux/macOS
~/.config/devin/agents/
├── reviewer.md
└── researcher/
    └── AGENT.md

# Windows
%APPDATA%\devin\agents\
├── reviewer.md
└── researcher\
    └── AGENT.md

Formato del file di definizione

Un file di definizione di subagent usa lo stesso frontmatter YAML delle skill, seguito dal prompt di sistema del subagent:

---
name: reviewer
description: Reviews code changes for correctness and style
model: sonnet
allowed-tools:
  - read
  - grep
  - glob
  - exec
---

You are a code review subagent. Your job is to review code changes
thoroughly and report findings back to the parent agent.

Focus on:
1. Correctness — logic errors, edge cases, off-by-one mistakes
2. Security — potential vulnerabilities
3. Style — consistency with the rest of the codebase
4. Performance — obvious inefficiencies

Always cite specific file paths and line numbers in your findings.

Campi del frontmatter

Campo	Tipo	Predefinito	Descrizione
`name`	string	nome del file o della directory	Identificatore del profilo (non deve essere in conflitto con i profili integrati)
`description`	string	nessuno	Mostrato all’agente durante la selezione di un profilo
`model`	string	modello predefinito del subagent (SWE-1.6 per impostazione predefinita) — non il modello del subagent padre	Override del modello usato da questo subagent
`allowed-tools`	list	tutti gli strumenti	Limita gli strumenti che il subagent può usare. Non può concedere `ask_user_question`, che è sempre precluso ai subagent.
`max-nesting`	integer	nessuno	Override della profondità massima di annidamento, consentendo a questo subagent di generare i propri subagenti

Come vengono usati i subagenti personalizzati

Una volta definiti, i profili dei subagenti personalizzati compaiono accanto a quelli predefiniti. L’agente vede una descrizione di ciascun profilo disponibile e sceglie quello più appropriato quando avvia un subagente. Puoi anche chiedere all’agente di usare un profilo specifico indicandone il nome (ad es., “esamina questo codice usando il subagente reviewer”). I profili dei subagenti personalizzati che entrano in conflitto con il nome di un profilo predefinito (ad es., subagent_explore, subagent_general) vengono ignorati con un avviso.

Importazione da altri strumenti

I subagenti personalizzati vengono importati anche dal formato degli agenti di Claude Code:

Origine	Pattern di file
`.claude/agents/*.md`	Ogni file `.md` diventa un profilo di subagente

I file degli agenti di Claude Code usano tools invece di allowed-tools nel frontmatter. Entrambi i formati sono supportati automaticamente.

Esempi

Agent di ricerca in sola lettura

---
name: researcher
description: Deep codebase research and architecture analysis
model: sonnet
allowed-tools:
  - read
  - grep
  - glob
---

You are a research subagent specializing in codebase exploration.

Your job is to thoroughly investigate a topic and report back with:
- Relevant files and their purposes
- Architecture patterns and dependencies
- Code flow traces with specific line references

Be exhaustive — search broadly and follow references.

Agente per l’esecuzione dei test

---
name: test-runner
description: Runs tests and reports results
allowed-tools:
  - read
  - grep
  - glob
  - exec
---

You are a test runner subagent. Run the relevant test suites and report:
- Which tests passed and failed
- Failure messages and stack traces
- Suggestions for fixing failures

Per iniziare

Integrazioni dell'Editor

Estensibilità

Enterprise

Riferimento

Changelog

Come funzionano i subagent

Foreground

Background

Costo dei subagenti

Quale modello usa un subagent?

Come influenzare il modello

Controlli Enterprise

Abilitare e disabilitare i subagent

Profili dei subagenti

Autorizzazioni degli strumenti

Monitoraggio dei subagenti

Indicatore del subagente

Pannello dei subagent

Passaggio tra foreground e background

Interrompere un turno

Annullare i subagenti

Ripresa dei subagenti

Profondità di annidamento

Subagenti personalizzati

Creazione di un subagent personalizzato

Formato del file di definizione

Campi del frontmatter

Come vengono usati i subagenti personalizzati

Importazione da altri strumenti

Esempi

Agent di ricerca in sola lettura

Agente per l’esecuzione dei test

​Come funzionano i subagent

Foreground

Background

​Costo dei subagenti

​Quale modello usa un subagent?

​Come influenzare il modello

​Controlli Enterprise

​Abilitare e disabilitare i subagent

​Profili dei subagenti

​Autorizzazioni degli strumenti

​Monitoraggio dei subagenti

​Indicatore del subagente

​Pannello dei subagent

​Passaggio tra foreground e background

​Interrompere un turno

​Annullare i subagenti

​Ripresa dei subagenti

​Profondità di annidamento

​Subagenti personalizzati

​Creazione di un subagent personalizzato

​Formato del file di definizione

​Campi del frontmatter

​Come vengono usati i subagenti personalizzati

​Importazione da altri strumenti

​Esempi

​Agent di ricerca in sola lettura

​Agente per l’esecuzione dei test

Come funzionano i subagent

Costo dei subagenti

Quale modello usa un subagent?

Come influenzare il modello

Controlli Enterprise

Abilitare e disabilitare i subagent

Profili dei subagenti

Autorizzazioni degli strumenti

Monitoraggio dei subagenti

Indicatore del subagente

Pannello dei subagent

Passaggio tra foreground e background

Interrompere un turno

Annullare i subagenti

Ripresa dei subagenti

Profondità di annidamento

Subagenti personalizzati

Creazione di un subagent personalizzato

Formato del file di definizione

Campi del frontmatter

Come vengono usati i subagenti personalizzati

Importazione da altri strumenti

Esempi

Agent di ricerca in sola lettura

Agente per l’esecuzione dei test