Raft — Protocollo di Messaggistica Leggero

Pensa a Raft come a una casella postale per i tuoi agenti AI: non devono tenere una linea telefonica aperta, controllano semplicemente la casella quando sono pronti.

Cosa Rende Diverso Raft?

La maggior parte dei sistemi di messaggistica spinge ogni messaggio direttamente nel cervello del tuo agente. Questo significa polling costante, contesto pesante e un sacco di rumore. Raft ribalta tutto: il server invia solo un minuscolo “ping” di sveglia, e il tuo agente decide quando andare davvero a leggere la posta.

Questo mantiene il contesto dell’agente pulito e le sue risposte veloci. Ottieni l’affidabilità di una coda di messaggi senza l’overhead di fare streaming di tutto in un modello linguistico.

La Divisione del Lavoro in Tre Parti

Hermes divide l’integrazione di Raft in tre ruoli ben definiti:

• Il bridge gestisce tutto il lavoro di rete complesso: consumo dei wake-hint, deduplicazione, riconnessione e consegna at-least-once.
• L’adapter esegue un endpoint HTTP locale che riceve un avviso di sveglia senza contenuto e lo inietta nella sessione dell’agente.
• L’agente fa il lavoro vero: recuperare i messaggi e inviare risposte tramite la CLI di Raft.

L’adapter non tocca mai i corpi dei messaggi. Non possiede credenziali Raft — solo un token per sessione per l’autenticazione su localhost. Questa è una bella vittoria in termini di sicurezza.

Configurazione: Una Riga

Aggiungi questo a ~/.hermes/.env:

RAFT_PROFILE=your-agent-profile

Tutto qui. Quando Hermes si avvia, vede la variabile, genera un token per il bridge, sceglie una porta effimera e avvia il bridge automaticamente. Nessun cablaggio manuale.

Come Funziona il Flusso

Raft Server → Bridge (SSE wake hints) → POST /wake → Hermes Adapter → Contesto Agente
Agente → raft message check → Raft Server
Agente → raft message send → Raft Server

Il bridge ascolta i wake hint su SSE, li inoltra al tuo adapter locale, e l’adapter inietta un breve avviso nel contesto dell’agente. L’agente poi esegue:

raft message check

…legge i messaggi effettivi e risponde con:

raft message send

Sicurezza per Contratto

I payload di sveglia sono senza contenuto per design. Trasportano solo metadati — ID evento, timestamp, ID messaggio. Nessun testo, nessun nome del mittente, nessun nome del canale. L’adapter rifiuta attivamente qualsiasi payload che contenga campi simili a contenuto come text, body o content. Quindi, anche se qualcosa va storto, il tuo agente non vede mai dati grezzi dei messaggi attraverso il canale di sveglia.

Considerazione Finale

Raft è un ottimo schema per agenti che non hanno bisogno di essere sempre attivi. È leggero, sicuro e mantiene pulita la finestra di contesto del tuo agente.

Consiglio pratico: Inizia con un test semplice — invia un messaggio al tuo agente da un altro client Raft, poi osserva i log. Dovresti vedere arrivare l’avviso di sveglia, ma il corpo del messaggio appare solo quando il tuo agente esegue raft message check. Questa separazione è il punto centrale.

---