Subagent - Devin Docs

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 subagente?

I subagenti 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 subagenti — 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 subagente general costa quanto un’intera sessione aggiuntiva sul modello selezionato
Subagenti personalizzati	Il campo `model` in `AGENT.md`, se impostato; altrimenti il modello predefinito dei subagenti	Dipende dal modello che blocchi

subagent_general eredita il modello dell’agente principale. Se stai usando un modello premium, anche ogni subagente general userà quel modello premium, con una propria finestra di contesto e chiamate di inferenza dedicate — quindi un’attività che si dirama in diversi subagenti general moltiplica la spesa. Chiedi un subagente 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 subagenti non è un nome di modello fisso — viene risolto tramite un router al momento della creazione del subagente, 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 subagenti quale modello sta usando un subagente 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 subagente personalizzato. model: in AGENT.md è 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.

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 dei tool

Il modo in cui funzionano le autorizzazioni dei tool dipende dal fatto che il subagente sia in esecuzione in primo piano o in background:

I subagenti in primo piano si comportano come l’agente principale: ti viene chiesto di approvare o negare le chiamate ai tool, come di consueto.
I subagenti in background ereditano tutte le autorizzazioni dei tool che hai già concesso nella sessione corrente. Qualsiasi tool che non sia stato pre-approvato viene negato automaticamente. I subagenti in background non possono chiederti nuove autorizzazioni.

Se un subagente in background fallisce perché l’accesso a un tool richiesto è stato negato, puoi riprenderlo in primo piano per approvare le autorizzazioni necessarie. Vedi Riprendere i subagenti 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 subagenti

Il pannello dei subagenti consente di visualizzare e gestire tutti i subagenti attivi e conclusi. Mostra il profilo, il titolo, lo stato, il tempo trascorso e il numero di chiamate agli strumenti di ciascun subagente.

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.

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, override del modello e autorizzazioni, 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 subagente personalizzato

I subagenti personalizzati vengono definiti come file AGENT.md all’interno di una directory con un nome specifico sotto agents/. Il nome della directory diventa l’identificatore del profilo.

Specifico per il progetto
Globale

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

Supportato anche:

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

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

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

Formato di AGENT.md

Un file AGENT.md usa lo stesso frontmatter YAML delle skill, seguito dal prompt di sistema del subagente:

---
name: reviewer
description: Reviews code changes for correctness and style
model: sonnet
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Exec(git diff)
    - Exec(git log)
  deny:
    - write
    - edit
---

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 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 dei 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.
`permissions`	object	eredita	Override delle autorizzazioni (`allow`, `deny`, `ask`)
`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
permissions:
  allow:
    - Exec(npm run test)
    - Exec(cargo nextest)
    - Exec(pytest)
---

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

​Come funzionano i subagent

Foreground

Background

​Costo dei subagenti

​Quale modello usa un subagente?

​Come influenzare il modello

​Controlli Enterprise

​Profili dei subagenti

​Autorizzazioni dei tool

​Monitoraggio dei subagenti

​Indicatore del subagente

​Pannello dei subagenti

​Passaggio tra foreground e background

​Annullare i subagenti

​Ripresa dei subagenti

​Profondità di annidamento

​Subagenti personalizzati

​Creazione di un subagente personalizzato

​Formato di AGENT.md

​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 subagente?

Come influenzare il modello

Controlli Enterprise

Profili dei subagenti

Autorizzazioni dei tool

Monitoraggio dei subagenti

Indicatore del subagente

Pannello dei subagenti

Passaggio tra foreground e background

Annullare i subagenti

Ripresa dei subagenti

Profondità di annidamento

Subagenti personalizzati

Creazione di un subagente personalizzato

Formato di AGENT.md

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