Un singolo agente è già utile. Ma il salto vero arriva quando smetti di pensarlo come una mente unica e inizi a trattarlo come un team: ruoli separati, responsabilità chiare, verifiche incrociate.
Un sistema multi-agente non è magia. È organizzazione. E si costruisce in due ore, se sai dove guardare.
Perché un agente solo non basta
Il problema di far fare tutto a un singolo agente è lo stesso problema di far fare tutto a una singola persona senza supervisione: l’errore si propaga senza essere rilevato, e la qualità dell’output dipende interamente dalla qualità del prompt iniziale.
Separare i ruoli introduce ridondanza e controllo — esattamente come in un team umano.
L’architettura minima che funziona quasi sempre
Planner. Traduce un obiettivo in una lista di task con criteri di successo e ordine di esecuzione. Non esegue mai direttamente.
Executor. Esegue task e tool call: legge repository, esegue test, fa ricerche, applica modifiche.
Critic/Verifier. Contesta, verifica, cerca edge case, prova a rompere la soluzione. Il suo unico obiettivo è trovare problemi.
Scribe (opzionale). Produce l’output finale in forma pulita: changelog, descrizione della PR, note per il team.
Prima di scegliere il framework, chiarisci le regole
Puoi costruire questo sistema con LangGraph, AutoGen, CrewAI, Semantic Kernel o LlamaIndex. La scelta del framework è meno importante di avere tre cose:
- Stato condiviso: un workspace con risultati, file modificati, log.
- Regole di handoff: quando il controllo passa da un ruolo all’altro.
- Loop di verifica: se un test fallisce, il sistema torna indietro con contesto aggiornato.
Il flusso che uso
A) Il Planner produce: lista di step, criteri di successo, rischi identificati.
B) L’Executor:
- indicizza la repository (struttura, dipendenze, search)
- scrive i test prima dove possibile
- applica le modifiche
- esegue test, lint, build
C) Il Critic:
- rilegge il diff
- cerca regressioni
- chiede prove concrete: “mostrami l’output dei test”, “cita file e funzioni”
D) Se il Critic boccia: torna all’Executor con una lista corta di fix specifici.
E) Lo Scribe prepara la PR: contesto, cosa è cambiato, come verificare.
La regola che fa davvero la differenza
Prima ancora dell’architettura, definisci un contratto per ogni agente: input atteso, output atteso, limiti espliciti. “Non fare deploy”, “mai scrivere su prod”, “solo branch feature/*” non sono dettagli opzionali — sono la fondamenta.
E poi: tool call solo all’Executor. Planner e Critic devono ragionare, non eseguire. Questo riduce il rischio e aumenta la qualità del piano.
L’ultimo elemento è la evidence rule: ogni affermazione importante deve avere una prova verificabile. Output di un comando, path di un file, test che passa, log. È l’antidoto più efficace all’hallucination in contesti agentici.