Subagenti - Devin Docs

I subagenti permettono all’agente principale di avviare worker indipendenti per gestire sottoattività. Un subagente condivide strumenti e contesto della codebase con l’agente padre, ma opera nella propria catena di conversazione — non eredita la cronologia delle conversazioni del padre. 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 subagenti (ad es. “analizza come funziona l’auth in un subagente”), oppure l’agente può decidere autonomamente di delegare quando ritiene che un’attività trarrebbe vantaggio da un lavoro indipendente. Secondo le nostre misurazioni, i subagenti sia migliorano le prestazioni complessive di sviluppo sia riducono i costi.

Come funzionano i subagenti

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

Primo piano

Viene eseguito inline nella tua sessione. L’agente principale si mette in pausa e aspetta che il subagente 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 subagente termina. Gli strumenti non approvati vengono rifiutati automaticamente.

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

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
`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)
`subagent_general`	Attività generiche, incluse modifiche al codice	Accesso completo agli strumenti (foreground) oppure solo agli strumenti pre-approvati (background)

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.

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.

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 del subagente	Override del modello usato da questo subagente
`allowed-tools`	list	tutti gli strumenti	Limita gli strumenti che il subagente può usare
`permissions`	object	eredita	Override delle autorizzazioni (`allow`, `deny`, `ask`)
`max-nesting`	integer	nessuno	Override della profondità massima di annidamento, consentendo a questo subagente 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

Documentation Index

​Come funzionano i subagenti

Primo piano

Background

​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 subagenti

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