Graph Agentic Coding: quando il workflow AI diventa un grafo (e smette di essere una chat)

Perché la chat non basta più

La chat è un modello mentale lineare: scrivi un prompt → il modello “pensa” → ottieni una risposta. Funziona bene per richieste puntuali, ma si rompe quando chiedi qualcosa di più vicino al lavoro reale:

• generare o modificare codice su una base ampia
• raccogliere contesto da fonti diverse
• prendere decisioni in più passaggi
• verificare automaticamente che il risultato sia corretto

A quel punto non stai più “chattando”: stai eseguendo un workflow. E un workflow, per natura, è fatto di passi, dipendenze, ritorni indietro, controlli e condizioni di uscita.

Dal prompt al loop: la struttura minima di un agente

Un agente moderno non aggiunge magia: aggiunge struttura attorno al modello. In forma semplificata, un workflow agentico tende a somigliare a questo ciclo:

1. Obiettivo (cosa voglio ottenere)
2. Raccolta contesto (es. RAG, ricerca, lettura repository, documentazione)
3. Piano (sequenza di passi)
4. Esecuzione (tool calling: file system, comandi, API, browser, ecc.)
5. Verifica / test
6. Se fallisce: ritorno al piano e iterazione

Il punto chiave è che l’iterazione non è un difetto, è il prodotto: il sistema migliora passando più volte su pianificazione → azione → verifica.

E a quel punto… è già un grafo

Quando introduci cicli e diramazioni, stai già descrivendo un grafo.

• i nodi sono stati/attività (pianifica, recupera contesto, modifica file, esegui test…)
• gli archi sono transizioni (se i test falliscono, torna a pianificare; se passano, chiudi)

Molti team continuano però a pensarlo come “una sequenza di prompt”. Il salto concettuale del graph agentic coding è rendere esplicito che:

• il workflow è un grafo
• il grafo è programmabile
• ogni nodo può contenere istruzioni (in linguaggio naturale) e regole di uscita

Il metodo “wiki” per costruire nodi utili

Un modo pratico per progettare nodi robusti è trattarli come piccole pagine “stile wiki”. In ogni nodo conservi tre elementi:

1. Contenuto: istruzioni operative o conoscenza (prompt, checklist, policy, snippet)
2. Riferimenti: link/logiche verso altri nodi (dipendenze, fonti, definizioni)
3. Metadati/autore (opzionale ma utile): versione, responsabilità, timestamp, scopo

Perché funziona?

• sposti la “memoria” fuori dalla chat e la rendi navigabile
• il sistema può muoversi tra nodi come noi navighiamo tra file e riferimenti nel codice
• riduci l’effetto “prompt monolitico” (troppo lungo, troppo fragile)

Se lavori con TypeScript/React (o qualsiasi codebase), l’analogia è immediata: seguire riferimenti tra definizioni e usi è già un modo di ragionare a grafo. Qui applichi lo stesso modello a istruzioni, contesto e decisioni.

Istruzioni in linguaggio naturale come “bytecode” del workflow

Un’idea sorprendentemente potente è questa: invece di rappresentare i nodi come funzioni imperative, puoi rappresentarli come testo.

• un nodo può contenere un obiettivo (“Analizza i fallimenti dei test e proponi una fix minimale”)
• un nodo può contenere una procedura (“Esegui: 1) riproduci 2) isola 3) patch 4) aggiorna snapshot…”)
• un nodo può definire criteri di successo (“Considera completato solo se: build ok, test ok, lint ok”)

È una forma di “programmazione” dove la parte eseguibile non è solo codice: è anche una sequenza di istruzioni leggibili che un motore agentico può interpretare ed eseguire con strumenti.

Multi-agente: quando i nodi delegano lavoro

La variante più interessante del modello a grafo arriva quando non hai un solo agente, ma più ruoli separati:

• Planner: scompone il problema e produce passi
• Executor: applica cambiamenti (tool calling)
• Verifier/Tester: controlla, esegue test, valida vincoli

In un grafo, questo significa che:

• un nodo può attivare più agenti
• un nodo può “spawnare” sottografi (task paralleli o sottoproblemi)
• la verifica può essere indipendente dall’esecuzione (riduce auto-indulgenza e allucinazioni)

L’impatto pratico è enorme: separare pianificazione ed esecuzione rende il sistema più controllabile, e separare la verifica rende il risultato più affidabile.

La parte che cambia davvero tutto: verifica e test come cittadini di prima classe

Molti workflow AI falliscono non perché il modello non sappia generare output, ma perché manca una disciplina di verifica ripetibile.

Nel graph agentic coding, la verifica non è un “passo finale”: è un nodo (o una sottosezione) con regole chiare:

• quali test eseguire
• quali invarianti mantenere (API compat, lint, formattazione, regressioni)
• quando tornare indietro e su quali nodi

In altre parole, è il pezzo che trasforma un assistente in un processo ingegneristico.

Implicazione pratica per chi fa frontend

Se lavori su app web o React/React Native, questo approccio è particolarmente utile perché il tuo lavoro è già pieno di grafi impliciti:

• dipendenze tra componenti
• flussi di navigazione
• stati e side effect
• pipeline CI (build → test → lint → bundle)

Un workflow agentico a grafo ti permette di modellare esplicitamente questi passaggi e farli eseguire in loop controllati, invece di affidarti a tentativi manuali in chat.

Sintesi: progettare workflow AI come grafi, non come prompt

Pensare “a grafo” significa smettere di inseguire il prompt perfetto e iniziare a progettare:

• nodi con istruzioni chiare, contesto e riferimenti
• archi con condizioni (successo/fallimento)
• loop che includono test e verifiche
• ruoli (multi-agente) per separare responsabilità

La conseguenza pratica è semplice: ottieni workflow più stabili, più debuggabili e più facili da far crescere nel tempo. Quando l’AI entra davvero nei processi di sviluppo, la differenza non la fa “quanto è bravo il modello”, ma quanto è ben disegnato il grafo che lo guida.