Passa al contenuto principale

Progettare un workflow multi-subagent

Avanzato
What you'll learn
  • Impostare una pipeline ricerca, implementazione, revisione in cui ogni fase ha il proprio contesto e il proprio set di strumenti
  • Scrivere descrizioni abbastanza precise da far delegare all'agente principale il subagent giusto senza che glielo si dica
  • Aggiungere un controllo di revisione che torna indietro invece di chiudersi con un timbro di routine
  • Riconoscere i tre casi in cui il coordinamento multi-agent costa più di quanto fa risparmiare
  • Verificare una run conclusa con quattro segnali che dicono se la suddivisione ha funzionato davvero

I compiti grandi vanno meglio se divisi tra subagent mirati invece di infilare tutto in un unico contesto. Progettiamo una pipeline ricerca → implementazione → revisione.

La forma​

Ogni subagent ha il proprio contesto e un set di strumenti su misura — e alla sessione principale torna solo il risultato, che così resta pulita.

Passo 1 — Definisci gli agenti​

Tramite l'interfaccia /agents, definiscine tre, ciascuno con una description precisa (così l'agente principale delega correttamente) e strumenti limitati:

Guided walkthrough1 of 3
  1. Mappa il codice rilevante e restituisce i risultati. Nessuno strumento di scrittura, ed è proprio questo che rende sicuro lasciarlo leggere ovunque. L'esplorazione pesante avviene qui, così non finisce mai nel tuo contesto principale.

Il campo description non è documentazione — è la chiave di instradamento che l'agente principale legge quando decide se delegare. Le descrizioni vaghe sono la singola causa più comune per cui un subagent che hai definito non viene mai usato.

A reviewer description that actually gets delegated to

Use this agent to review a completed code change adversarially before it ships.
Invoke it after the implementer reports done, and before telling the user the
task is finished. It reads the diff and the surrounding code and reports
problems; it does not fix them.

Passo 2 — Orchestra con i passaggi di consegne​

La sessione principale passa l'output di ogni fase alla successiva: ricerca → implementazione (usando la ricerca) → revisione (dell'implementazione). Aggiungi un controllo di revisione: se il reviewer trova problemi, si torna all'implementer prima di concludere.

The handoff instruction that creates the gate

Run this as three stages, and do not skip the gate:

1. Delegate the exploration to the researcher. Wait for its findings.
2. Give those findings to the implementer as its starting context.
 Do not ask it to re-explore.
3. Give the implementer's result to the reviewer. If the reviewer reports
 any issue, hand the issues back to the implementer and review again.
 Only report the task complete after a review that found nothing.

Passo 3 — Sapere quando NON farlo​

Parallelo/multi-agent non è gratis
  • Le dipendenze sequenziali (l'implementazione ha bisogno della ricerca) restano sequenziali — non aprire a ventaglio dove l'ordine conta.
  • Le scritture su file condivisi possono andare in conflitto — isolale con i git worktree o serializzale.
  • Per i compiti piccoli, il costo di coordinamento supera il beneficio. Usalo per lavoro corposo e scomponibile.

Passo 4 — Verifica​

Una buona run multi-agent mostra: un contesto principale mirato (la lettura pesante è avvenuta nel researcher), un'implementazione che riflette la ricerca e una revisione che ha davvero individuato qualcosa (o ha dato un via libera credibile). Se il reviewer è un timbro di routine, rendi il suo prompt avversariale ("prova a trovare cosa non va").

Check yourself

0/3
  1. Hai definito un subagent reviewer, ma in diverse run l'agente principale non delega mai a lui. Qual è la causa più probabile?
  2. Il tuo compito è piccolo: rinominare una funzione e aggiornare i suoi tre punti di chiamata. Dovresti eseguire la pipeline ricerca/implementazione/revisione?
  3. Due subagent devono scrivere sugli stessi file nello stesso momento. Qual è la soluzione?
Key takeaways
  • Dividi per contesto e set di strumenti, non solo per nome del compito: researcher in sola lettura, implementer con scrittura limitata, reviewer in sola lettura e avversariale.
  • Alla sessione principale torna solo il risultato, ed è proprio questo il punto — la lettura pesante resta nel contesto del researcher.
  • La description è una chiave di instradamento. Una vaga significa che il subagent che hai definito con cura non viene mai chiamato.
  • Un controllo di revisione funziona solo se può tornare indietro: i problemi tornano all'implementer, e il compito è concluso solo dopo una revisione che non ha trovato nulla.
  • Tieni il reviewer in sola lettura. Se gli dai accesso in scrittura corregge invece di segnalare, e perdi il segnale per cui l'avevi costruito.
  • Salta lo schema per lavoro solo sequenziale, per scritture condivise in conflitto che non hai isolato e per tutto ciò che è piccolo.

Per andare oltre​

Lo stesso schema, in modo programmatico, è Costruire agenti sull'API e nelle superfici di prodotto come Cowork e Agent Teams.

Avanti​