9 agenti, 3 orchestratori, 1 VPS: anatomia di un team AI
Non una demo. Un sistema che gira in produzione su una VPS con 31 GB di RAM, quattro sessioni tmux persistenti e un knowledge graph con 5.000 nodi. Ecco chi fa cosa e come comunicano senza parlarsi.
Parlare di "team di agenti AI" è facile. Costruirne uno che funziona su problemi reali è un'altra cosa. In questo articolo descrivo l'anatomia del sistema che ho costruito sulla VPS: chi sono gli agenti, come sono strutturati, e — la parte più interessante — come comunicano tra loro senza un canale di chat condiviso.
L'infrastruttura
Il sistema gira su una VPS Ubuntu con 31 GB di RAM e Docker come runtime. Il motore di orchestrazione è n8n — non perché sia il migliore in assoluto, ma perché la combinazione di workflow visuali e webhook HTTP lo rende flessibile per iterare velocemente senza riscrivere codice ogni volta.
Al centro della memoria condivisa c'è Neo4j: un knowledge graph con oltre 5.000 nodi che mappa entità, relazioni e decisioni accumulatesi nel tempo. Non è un database SQL con tabelle e foreign key. È una rete dove ogni nodo può avere relazioni arbitrarie con ogni altro nodo — il che lo rende adatto a rappresentare la complessità reale di un progetto in evoluzione.
La domanda che mi veniva posta più spesso quando descrivevo questo setup era: "non bastava un singolo modello potente?". La risposta è no — ma non perché un singolo modello non sia potente. È perché un singolo agente con troppe responsabilità produce decisioni di qualità inferiore rispetto a più agenti specializzati che collaborano. L'ho verificato empiricamente, non lo sto assumendo per principio.
I 9 agenti V2
Il team è composto da nove agenti specializzati, ognuno con un system prompt dedicato e un perimetro di responsabilità definito:
- Backend Developer — logica server, API, integrazioni
- Database Architect — schema, query, ottimizzazione Neo4j e PostgreSQL
- DevOps Engineer — container, deployment, monitoraggio
- Frontend Architect — struttura UI, componenti, performance
- Security Auditor — review del codice per vulnerabilità, validazione input
- QA Engineer — test, casi limite, regressioni
- API Integrator — connessioni con servizi esterni, webhook
- N8N Expert — workflow automation, orchestrazione
- Tech Writer — documentazione, CLAUDE.md, changelog
La separazione dei ruoli non è decorativa. Il Backend Developer non tocca la struttura del database — quella è responsabilità del Database Architect. Il Frontend Architect non scrive logica API. Il Security Auditor non modifica il codice che ha identificato come vulnerabile — segnala e delega.
Questa separazione produce design migliori perché ogni agente ottimizza per il suo dominio senza dover fare trade-off con gli altri. L'architect che non deve preoccuparsi delle API produce design più coerenti. Il backend che non deve pensare all'UI scrive codice più pulito.
I 3 orchestratori
Gli orchestratori sono lo strato sopra agli agenti specializzati. Ne ho tre con caratteristiche diverse: ORCHESTRATOR-V4 è l'orchestratore principale, con accesso completo a tutti gli agenti e capacità di gestire task complessi multistep. ORCHESTRATOR-L2 è un livello intermedio, più veloce, usato per task che richiedono coordinamento tra 2-3 agenti ma non l'intero team. ORCHESTRATOR-L2_TextOnly è la variante senza accesso a tool visivi, ottimizzata per task puramente testuali dove la latenza è critica.
Il compito di un orchestratore è decidere chi fa cosa, in quale ordine, e come gestire i conflitti quando due agenti producono risultati incompatibili. Un caso concreto: il Backend Developer propone un'implementazione che il Security Auditor segnala come insufficiente per i requisiti di autenticazione. L'orchestratore non sceglie arbitrariamente — raccoglie le posizioni, identifica i vincoli non negoziabili, e produce un mandato per la revisione che soddisfa entrambi.
Il bridge — come comunicano gli agenti
La parte più interessante del sistema non è la potenza dei singoli agenti. È il protocollo di comunicazione tra loro.
Gli agenti non si parlano in chat. Comunicano attraverso file JSON in una cartella chiamata _bridge/. Il formato è semplice e non negoziabile:
{
"id": "task_20260310_143022_backend",
"from": "ORCHESTRATOR-V4",
"to": "backend-developer",
"type": "task",
"payload": {
"description": "Implementa endpoint POST /api/sessions con validazione JWT",
"constraints": ["usa FastAPI", "logging obbligatorio", "test unitari inclusi"],
"deadline": "sessione corrente"
}
}Quando l'agente completa il task, scrive un file result_20260310_143022_backend.json con l'output, lo stato e eventuali note per l'orchestratore. Ogni interazione è tracciata, ogni risultato è persistente, ogni errore è documentato.
Non è una chat. È un protocollo di comunicazione strutturato con audit trail completo. La differenza pratica: posso rileggere l'intera storia di una sessione di lavoro del team come se fosse un log di sistema. Questo ha un valore enorme per capire cosa è andato storto — e per migliorare i prompt degli agenti in modo mirato.
Le sessioni TMUX — il terminale come ufficio
Il runtime del team è organizzato in quattro sessioni tmux persistenti sulla VPS: architect, builder, ops e teamlead. Ogni sessione ospita uno o più agenti che girano in parallelo, con compaction automatica del contesto quando si avvicina al limite della finestra.
Il watchdog anti-zombie controlla ogni cinque minuti che nessuna sessione si sia bloccata silenziosamente. È uno script semplice — meno di cinquanta righe — ma ha salvato ore di lavoro perché i processi bloccati senza output visibile sono la forma più subdola di failure in un sistema multi-agente.
In una demo, gli agenti collaborano su esempi costruiti per funzionare. In produzione, collaborano su problemi reali con vincoli reali, codice legacy reale, e output che devono essere deployed su sistemi reali. I failure modes sono completamente diversi. Quello che ho imparato osservando il team su problemi reali non avrei potuto impararlo in un ambiente controllato.
Cosa ho imparato osservando il team
Tre pattern emergono con consistenza. Primo: gli agenti specializzati producono output di qualità superiore ma richiedono un orchestratore ben calibrato. Un orchestratore impreciso nelle istruzioni produce lavoro ridondante tra agenti che si sovrappongono.
Secondo: i fallimenti del sistema avvengono quasi sempre ai confini tra agenti, non al centro delle responsabilità. Il Backend Developer e l'API Integrator hanno aree di sovrapposizione che richiedono una definizione esplicita di chi possiede cosa — altrimenti entrambi implementano la stessa cosa in modi diversi.
Terzo, e più sorprendente: la qualità della comunicazione scritta nel bridge determina la qualità dell'output più dei system prompt. Un task descritto male produce un risultato insoddisfacente anche con un agente eccellente. Un task descritto con precisione — vincoli chiari, output atteso specificato, casi limite menzionati — produce risultati consistentemente buoni anche con modelli meno potenti.
Questa ultima osservazione ha cambiato il mio approccio: ho smesso di ottimizzare i system prompt degli agenti e ho iniziato a ottimizzare il formato dei task nel bridge. Il ritorno è stato immediato e misurabile.
Quarta parte della saga Cloud & Code. Il prossimo articolo affronta il Model Context Protocol: perché ha cambiato tutto nel modo in cui gli agenti accedono alle risorse.