La maggior parte delle persone che cercano di costruire un agente multi-step finisce con una linea retta. Passo uno, passo due, passo tre – ognuno aspetta educatamente che l’ultimo finisca prima di iniziare.
9/10 si accorgono che metà di quei passi non avevano mai bisogno di aspettare.
Non instradano. Non ramificano. Non parallelizzano. Si limitano a mettersi in coda – una testa, un contesto, una cosa alla volta, finché la finestra si riempie e l’agente dimentica cosa stava facendo.
Segui il mio Substack per ricevere alpha AI fresca:
Questa è la roadmap in 14 passi che trasforma quella linea a file singolo in un grafo: uno che si dirama su una flotta, verifica le proprie scoperte e converge su un risultato che un agente solitario non potrebbe mai tenere.
Ecco il cambiamento che nessuno spiega. Un prompt è una frase. Un loop è un ciclo. Un’imbracatura è il pavimento su cui l’agente si trova.
Ma la forma del lavoro stesso – cosa viene eseguito prima di cosa, cosa può essere eseguito contemporaneamente, cosa deve aspettare tutto il resto – quella forma è un grafo. I nodi fanno il pensiero. Gli archi trasportano i risultati.
Claude Code ha rilasciato gli strumenti per costruire questi grafi direttamente: dynamic workflows.
Claude scrive un semplice script di orchestrazione in JavaScript, poi genera una flotta coordinata di subagenti per eseguirlo – e il coordinamento stesso costa zero token del modello, perché è codice, non una conversazione.
01. I nodi sono lavori. Gli archi sono ciò che scorre.
Un grafo ha esattamente due cose, e metterle in chiaro risolve la maggior parte della confusione. Un nodo è un’unità di lavoro – un agente, un lavoro limitato, un input in ingresso e un output in uscita.
Un arco è una dipendenza: dice l’output di questo nodo alimenta l’input di quel nodo. Niente di più.
L’errore è trattare “e poi” come un arco. “Riassumi il file e poi dimmi il tempo” non ha un arco tra i due – il tempo non consuma il riassunto.
Sono due nodi disconnessi che uno script lineare incatena inutilmente. L’arco esiste solo quando i dati si muovono effettivamente attraverso di esso.
Impara a chiedere, per ogni “e poi” nel tuo agente: il passo successivo legge l’output dell’ultimo passo? Se no, non c’è arco, e l’attesa è sprecata.
1Disegnalo come scatole e frecce. Una scatola è una chiamata agent().2Una freccia è una variabile passata dal ritorno di una chiamata nel prompt3di un'altra. Se non riesci a disegnare la freccia – se nessuna variabile4passa – le due scatole sono indipendenti, e l'indipendenza è la cosa che5sfrutterai per il resto di questo corso.
02. Il tuo script lineare è un grafo degenerato
Quando scrivi un agente come “fai A, poi B, poi C, poi D,” hai disegnato un grafo – una singola catena non ramificata. Ogni nodo ha esattamente un arco in entrata e uno in uscita.
Funziona correttamente. Funziona anche lentamente e in modo fragile, perché una catena non ha ridondanza: se C si blocca, D non avviene mai, e il lavoro di A rimane intrappolato a monte senza nessun posto dove andare.
La prima vera abilità dell’ingegneria dei grafi è ridisegnare la catena. Prendi il tuo agente lineare e, per ogni freccia, fai la domanda del Passo 1.
La maggior parte delle catene ha due o tre frecce che non trasportano dati – sono solo l’ordine in cui hai scritto le cose.
Taglia quelle frecce e la catena collassa in qualcosa di più ampio: alcuni nodi indipendenti che potrebbero essere eseguiti tutti insieme, alimentando un singolo nodo che li necessita tutti.
03. Dai a ogni nodo un contratto
Un nodo di cui non puoi ragionare è un nodo che non puoi parallelizzare. La soluzione è un contratto: input limitato, output limitato, esattamente un lavoro.
L’input è tutto ciò che il nodo legge – passato esplicitamente, mai assunto da una finestra condivisa. L’output è una forma definita, idealmente validata, in modo che il nodo successivo possa consumarlo senza indovinare.
In un workflow questo contratto è applicato con uno schema. Quando dai a Claude una chiamata agent() con uno schema JSON, il subagente che Claude genera è forzato a restituire dati strutturati validati – la validazione avviene a livello di tool-call, quindi Claude riprova in caso di mancata corrispondenza invece di darti testo libero che devi analizzare e su cui pregare.
Questa è la differenza tra un nodo che Claude può collegare in un grafo e un nodo che funziona solo quando un essere umano legge il suo output.
1// Un nodo con un vero contratto: input limitato, output validato, un lavoro.2const ITEM = {3 type: 'object', additionalProperties: false,4 properties: {5 title: { type: 'string' },6 url: { type: 'string' },7 impact: { type: 'string', enum: ['high', 'medium', 'low'] },8 },9 required: ['title', 'url', 'impact'],10};1112const result = await agent(source.prompt, {13 label: `research:${source.key}`,14 schema: ITEM, // forza output strutturato validato15 agentType: 'general-purpose',16});17// result è ora una forma di cui il prossimo nodo può fidarsi — non testo libero.
04. Tratta l’arco come un contratto di dati
Un arco non è solo “B viene dopo A.” È una promessa su cosa attraversa: A produce questa forma, e B è costruito per consumare questa forma. Quando nomini l’arco in base ai suoi dati – non al suo ordine – due cose diventano più facili.
Puoi vedere immediatamente se l’arco è reale (i dati si muovono effettivamente?), e puoi scambiare il nodo a ciascuna estremità senza rompere il grafo, purché la forma rimanga.
In pratica, l’arco vive in JavaScript semplice. Il passo di reduce tra fan-out e sintesi – appiattire, deduplicare, filtrare – è solo codice che opera sulle forme che i tuoi nodi hanno restituito.
Nessun agente necessario. Una delle vittorie silenziose del pensiero a grafo: una grande quantità di ciò per cui le persone spendono token del modello è in realtà un arco, e gli archi sono gratuiti.
1La tentazione è di generare un agente per "combinare i risultati." Resisti.2Se combinare significa appiattire e deduplicare, sono results.flatMap(...)3e un Set — deterministico, istantaneo, zero token. Risparmia gli agenti per4il giudizio, non per la tubatura. Un grafo in cui ogni arco è un agente è un5grafo che paga l'affitto per la propria cablatura.
05. Dirama con parallel()
Questa è la mossa che paga per tutto. Quando hai N nodi indipendenti – N fonti da controllare, N file da revisionare, N percorsi da auditare – non li incateni.
Dici a Claude di diramarli ed eseguirli tutti insieme. In un workflow è parallel(): Claude prende un array di thunk e genera un subagente per thunk, tutti eseguiti contemporaneamente, poi ti restituisce l’array di risultati.
Due dettagli lo rendono robusto. Primo, parallel() è una barriera – aspetta ogni thunk prima di restituire, così la fase successiva vede l’insieme completo. Secondo, un thunk che lancia un’eccezione si risolve in null invece di rifiutare l’intero lotto, quindi un agente traballante non può affondare l’esecuzione.
Filtra sempre .filter(Boolean) i risultati. La concorrenza è limitata intorno al numero di core e le eccedenze si accodano, quindi puoi passare cento thunk e finiranno tutti – solo una manciata alla volta.
1phase('Research');23// Nove fonti, nove agenti, tutti insieme.4const raw = await parallel(5 SOURCES.map((s) => () =>6 agent(s.prompt, {7 label: `research:${s.key}`,8 phase: 'Research',9 schema: ITEM_SCHEMA, // ogni nodo restituisce JSON validato10 agentType: 'general-purpose',11 }),12 ),13);1415const collected = raw.filter(Boolean); // elimina i null dagli agenti falliti
Il fan-out vive nel codice che Claude ha scritto, non in una conversazione del modello. Il contesto di Claude non contiene mai nove fonti contemporaneamente – ogni subagente porta le proprie, e solo la risposta finale torna indietro.
Ecco cosa permette a Claude di scalare un workflow a decine o centinaia di subagenti senza affogare la sessione. Il livello di orchestrazione costa zero token perché non è un altro turno di pensiero di Claude.
06. Raccogli a una barriera
Un fan-out è utile solo se qualcosa lo raccoglie. Il fan-in è il nodo in cui gli archi convergono – dove un agente (o un pezzo di codice) vede tutti i risultati a monte contemporaneamente e fa qualcosa che richiede l’intero insieme: deduplicare tra fonti, classificare per impatto, uscita anticipata se il totale è tornato vuoto. Questo è il posto in cui una barriera guadagna il suo costo a orologio.
La regola che mantiene i grafi veloci: usa una barriera solo quando una fase ha genuinamente bisogno di tutti i risultati precedenti insieme. Deduplicare tra tutte le fonti? Barriera – corretto.
1// L'arco: JS semplice, nessun agente, zero token.2const flat = collected.flatMap((c) => c.items);3log(`Collected ${flat.length} items`);45phase('Curate');6// Il nodo barriera: ha bisogno dell'INTERO insieme per deduplicare + classificare.7const curated = await agent(8 `Deduplica e classifica questi per impatto:\n${JSON.stringify(flat)}`,9 { phase: 'Curate', schema: CURATED_SCHEMA },10);
Solo appiattire una lista? Quello è un arco, fallo inline. Il test dell’odore è brutale e semplice: se hai scritto parallel → transform → parallel, e quella transform intermedia non ha dipendenze incrociate tra elementi, avresti dovuto usare una pipeline e saltare del tutto la barriera.
07. Il diamante: split → work → merge
Metti insieme fan-out e fan-in e ottieni la topologia di lavoro di ogni grafo di agente serio: il diamante.
Un nodo divide il lavoro, molti nodi fanno il lavoro in parallelo, un nodo unisce. È la forma dietro una scansione di mercato, un audit delle dipendenze, una revisione del codice, un rapporto di ricerca – scambia le fonti e i prompt e lo stesso scheletro si adatta.
La forma canonica ha un nome che vale la pena memorizzare: fan out → reduce → synthesize. Fan out per raccogliere ampiezza, reduce con codice semplice per comprimerla, synthesize con un agente finale per scrivere la risposta.
Una volta che vedi il diamante, smetti di chiederti “come faccio a far fare al mio agente più passi” e inizi a chiederti “dov’è la divisione, dov’è l’unione” – che è la domanda che scala davvero.
08. Instrada l’arco a runtime con un condizionale
Non tutti i grafi sono fissi. A volte l’arco da prendere dipende da ciò che un nodo ha trovato. Un nodo router ispeziona un risultato e decide quale percorso a valle si attiva – classifica il ticket, poi ramifica al gestore giusto; controlla la dimensione del diff, poi fai una revisione veloce o avvia un audit completo.
In un workflow è solo un if o switch JavaScript sull’output validato di un nodo, perché il flusso di controllo vive nel codice.
Qui è dove il determinismo diventa una caratteristica, non una limitazione. La decisione del router può essere alimentata da Claude (un subagente classifica), ma il routing è codice che Claude ha scritto – quindi funziona sempre allo stesso modo per la stessa classificazione.
Ottieni il giudizio di Claude al nodo e l’affidabilità dello script all’arco. Nessuna sorpresa emergente “Claude ha deciso di saltare l’audit” – perché il salto dovrebbe essere scritto nel grafo, e non lo è.
1// Nodo router: un agente classifica, il codice sceglie l'arco.2const { severity } = await agent(3 `Classifica il rischio di questo diff:\n${diff}`,4 { schema: { type: 'object',5 properties: { severity: { enum: ['low', 'high'] } },6 required: ['severity'] } },7);89let review;10if (severity === 'high') {11 // percorso pesante: audit parallelo completo12 review = await parallel(FILES.map((f) => () => agent(`Fai audit di ${f}`)));13} else {14 // percorso leggero: un passaggio rapido15 review = await agent(`Revisione rapida di ${diff}`);16}
09. Metti un verifier sull’arco
Il vero vantaggio di un grafo non sono più agenti – è la struttura che puoi avvolgere attorno a loro per produrre fiducia.
Un nodo verifier si trova sull’arco prima che un risultato sia permesso a valle, e il suo unico lavoro è cercare di uccidere la scoperta. Se sopravvive, passa. Se no, non raggiunge mai la risposta.
Tre modelli valgono la pena di avere a portata di mano.
- Adversarial verify: per ogni scoperta, genera N scettici indipendenti incaricati di confutarla; mantienila solo se la maggioranza sopravvive.
- Perspective-diverse verify: dai a ogni verifier una lente distinta – correttezza, sicurezza, si-riproduce – perché la diversità cattura modalità di fallimento che N controlli identici non coglieranno mai.
- Judge panel: genera N tentativi da diverse angolazioni, valutali con giudici paralleli, sintetizza dal vincitore innestando il meglio dei secondi.
Questo è esattamente il modello che ha permesso a un team reale di portare il runtime Bun con una revisione del codice adversarial integrata nel ciclo.
10. Isola i nodi in modo che un fallimento non possa avvelenare il grafo
In una catena, un fallimento si propaga – C muore, D non viene mai eseguito, tutto si ferma. In un grafo, il fallimento dovrebbe essere contenuto nel suo nodo.
Questo è già parzialmente vero: un thunk che lancia un’eccezione dentro parallel() si risolve in null, quindi otto agenti buoni restituiscono ancora mentre uno cattivo esce. Il tuo .filter(Boolean) è il contenimento.
Progetta ogni fan-in per tollerare input mancanti piuttosto che assumere un insieme completo.
Il fallimento più sottile è che i nodi si pestano i piedi a vicenda. Quando gli agenti scrivono file in parallelo, possono collidere.
La soluzione è l’isolamento: "worktree" – ogni agente viene eseguito nel suo proprio worktree git, fa il suo lavoro in una sandbox e si unisce in modo pulito.
Ricorrivo solo quando i nodi scrivono effettivamente in parallelo. È la cintura di sicurezza per l’unica topologia che ne ha bisogno, non una tassa predefinita su ogni esecuzione.
11. Aggiungi un ciclo – ma fallo convergere
A volte non sai quanto è grande il lavoro finché non ci sei dentro: scoperta di dimensione sconosciuta, una caccia ai bug in cui trovare un bug ne rivela altri tre. Questo richiede un ciclo – un arco controllato di ritorno a un nodo precedente.
Il pericolo è ovvio: un ciclo che non converge è un loop infinito che genera agenti fino all’esaurimento del budget.
Il modello che converge è loop-until-dry: continua a generare cercatori fino a quando K round consecutivi non portano alla luce nulla di nuovo, poi fermati. L’unico dettaglio che lo determina – e l’errore che quasi tutti commettono la prima volta – è contro cosa deduplicare.
Deduplica contro tutto ciò che è stato visto, non solo contro i risultati confermati. Altrimenti le scoperte respinte riappaiono ogni round, il ciclo non si esaurisce mai, e hai costruito una macchina che paga per riscoprire gli stessi vicoli ciechi per sempre.
1const seen = new Set(); const confirmed = []; let dry = 0;23while (dry < 2) { // fermati dopo 2 round vuoti4 const found = (await parallel(5 FINDERS.map((f) => () => agent(f.prompt, { schema: BUGS }))6 )).filter(Boolean).flatMap((r) => r.bugs);78 const fresh = found.filter((b) => !seen.has(key(b)));9 if (!fresh.length) { dry++; continue; } // niente di nuovo → verso esaurimento10 dry = 0;11 fresh.forEach((b) => seen.add(key(b))); // deduplica contro VISTO, non confermato1213 // verifica con lenti diverse ogni nuova scoperta prima che conti14 const judged = await parallel(fresh.map((b) => () =>15 parallel(['correctness', 'security', 'repro'].map((lens) => () =>16 agent(`Giudica "${b.desc}" tramite ${lens} — reale?`, { schema: VERDICT })))17 .then((v) => ({ b, real: v.filter(Boolean).filter((x) => x.real).length >= 2 }))));1819 confirmed.push(...judged.filter((v) => v.real).map((v) => v.b));20}
12. Classifica i modelli attraverso i nodi
Non tutti i nodi hanno bisogno del tuo modello migliore. Un grafo lo rende ovvio in un modo che un singolo agente non fa mai: alcuni nodi sono limitati e ripetitivi (estrai questo campo, classifica questo ticket), e alcuni portano il vero giudizio (sintetizza il rapporto, giudica la scoperta).
Esegui i nodi noiosi su un modello più economico e spendi i tuoi token costosi dove risiede effettivamente il giudizio.
In un workflow ogni subagente che Claude genera eredita il tuo modello di sessione a meno che lo script non lo sovrascriva – quindi per impostazione predefinita una grande esecuzione fattura interamente al tuo livello di sessione. L’opzione model su una singola chiamata agent() dice a Claude di instradare solo quel nodo altrove.
Controlla /model prima di una grande esecuzione, poi fai instradare a Claude i nodi ripetitivi del fan-out su un modello più economico e mantieni il nodo di merge su di un livello superiore. Questa è la leva che trasforma un grafo affamato di token da costoso a economico senza toccare la sua forma.
13. La topologia è il tuo costo e la tua latenza
La forma del grafo non è estetica – è la leva singola più grande sul tempo a orologio. La scelta che inciampa tutti: parallel() contro pipeline(). Una barriera parallel() fa aspettare tutto per il nodo più lento prima che la fase successiva inizi.
Una pipeline() scorre ogni elemento attraverso tutte le fasi indipendentemente, senza barriera – l’elemento A può essere nella fase 3 mentre l’elemento B è ancora nella fase 1. Gli elementi veloci finiscono presto invece di restare inattivi dietro a quelli lenti.
Predefinito su pipeline(). Ricorri a una barriera solo quando una fase ha veramente bisogno di tutti i risultati precedenti contemporaneamente – una deduplica tra insiemi, un’uscita anticipata sul totale, un prompt che confronta con “le altre scoperte.” “È codice più pulito” e “le fasi sembrano separate” non sono ragioni; la latenza della barriera è tempo reale, misurabile, sprecato. Separato non è la stessa cosa di sincronizzato.
14. Lascia che Claude disegni il grafo – self-routing
La mossa finale è smettere di disegnare il grafo a mano per lavori che non puoi pianificare in anticipo.
Con i dynamic workflows, descrivi l’obiettivo e Claude scrive lo script di orchestrazione stesso – decomponendo il compito, scegliendo il fan-out, generando una flotta coordinata di subagenti e sintetizzando il risultato. Ottieni un grafo su misura per questa esecuzione invece di uno fisso che speravi si adattasse.
Ci sono tre modi per entrare. Pronuncia la parola 'workflow' nel tuo prompt e Claude ne scrive uno per il compito. Esegui uno salvato o predefinito – /deep-research è un vero grafo in produzione: scope → parallel search → fetch → adversarial verify → synthesize, lo scheletro esatto di questo corso.
Oppure attiva ultracode e Claude pianifica un workflow per ogni compito sostanziale nella sessione. Quando un’esecuzione è buona, premi s per salvare il suo script in .claude/workflows/ – versionato, rieseguibile per nome, un grafo che chiunque cloni il repository può lanciare.
1› Esegui un workflow per controllare ogni percorso sotto src/routes/ per auth2mancante. Genera un agente per file di percorso, poi verifica ogni scoperta3prima di riportare. ● Claude ha scritto uno script di orchestrazione · avvio in4background… /workflows — auth-audit · in esecuzione ✓ Scope 1/1 2.1k tok ·54s ✓ Fan-out 18/18 un agente per file di percorso ◯ Verify 11/18 3 voti6scettici per scoperta… ○ Synthesize 0/1 in attesa di verify la sessione rimane7reattiva — continua a lavorare mentre la flotta esegue
Sei grafi da costruire con Claude questa settimana
- Spazzata di sicurezza attraverso ogni percorso. Claude genera un subagente per file di percorso, ognuno a caccia di controlli auth mancanti, poi un passaggio di verifica conferma ogni scoperta prima che raggiunga il rapporto. Ampiezza che nessun singolo contesto potrebbe contenere.
- Rapporto citato con /deep-research. Un grafo che è già incluso in Claude Code. Claude scompone la tua domanda in angolazioni distinte, esegue ricerche parallele, deduplica le fonti, poi verifica in modo adversarial ogni affermazione con tre voti scettici prima di scrivere.
- Porta un modulo, file per file. Il soffitto di Bun, scalato al tuo repository. Claude distribuisce la traduzione tra i file, esegue la suite di test come gate su ciascuno, e riporta i fallimenti indietro – revisione adversarial che cattura ciò che un singolo passaggio rilascerebbe rotto.
- Revisione adversarial di un diff. Claude instrada in base alla dimensione del diff: una piccola modifica ottiene un passaggio rapido, una grande attiva un audit parallelo completo con revisori su lenti distinte – correttezza, sicurezza, prestazioni – poi un pannello di giudici sintetizza.
- Scansione dell’ecosistema su pianificazione. Salvalo una volta, rieseguilo per sempre. Claude controlla molte fonti in parallelo – rilasci, blog, discussioni – classifica per impatto a una barriera, e scrive il digest. Versionato in .claude/workflows/, lanciabile per nome.
- Scoperta di dimensione sconosciuta. Non sai quanti bug ci sono. Claude esegue cercatori in parallelo, deduplica ogni nuova scoperta contro tutto ciò che è stato visto, verifica i sopravvissuti, e continua a ciclare fino a quando due round non portano nulla di nuovo – poi si ferma.
Conclusione:
Un promptista fa una domanda. Un architetto disegna un grafo.
L’agente lineare non è mai stato il soffitto – era solo la prima forma, quella a cui tutti tendono perché corrisponde a come scriviamo. Una linea, una testa, una cosa alla volta.
Una volta che riesci a vedere i nodi e gli archi, smetti di chiedere all’agente di fare di più e inizi a chiedere al grafo di farlo più ampio: fan-out dove il lavoro è indipendente, metti un gate sugli archi dove la fiducia conta, classifica i modelli dove il giudizio non è necessario.
La maggior parte delle persone continuerà a mettere in coda passi in una linea. Quelli che imparano a disegnare il grafo faranno funzionare una flotta – e non noteranno mai il soffitto sotto cui il resto è bloccato.
