Raft — Protocolo de Mensajería Ligero

Piensa en Raft como un apartado postal para tus agentes de IA: no necesitan mantener una línea telefónica abierta, simplemente revisan el buzón cuando están listos.

¿Qué hace diferente a Raft?

La mayoría de los sistemas de mensajería empujan cada mensaje directamente al cerebro de tu agente. Eso significa sondeos constantes, contexto pesado y mucho ruido. Raft le da la vuelta a eso: el servidor envía solo un pequeño “ping” de despertar, y tu agente decide cuándo ir a leer realmente el correo.

Esto mantiene el contexto del agente limpio y sus respuestas rápidas. Obtienes la fiabilidad de una cola de mensajes sin la sobrecarga de transmitir todo a un modelo de lenguaje.

La división del trabajo en tres partes

Hermes divide la integración de Raft en tres roles claros:

• El puente maneja todo el trabajo de red difícil: consumo de avisos de despertar, deduplicación, reconexión y entrega al menos una vez.
• El adaptador ejecuta un endpoint HTTP local que recibe un aviso de despertar sin contenido y lo inyecta en la sesión del agente.
• El agente hace el trabajo real: extraer mensajes y enviar respuestas a través de la CLI de Raft.

El adaptador nunca toca los cuerpos de los mensajes. No tiene credenciales de Raft — solo un token por sesión para la autenticación localhost. Eso es una gran ventaja de seguridad.

Configuración: Una línea

Añade esto a ~/.hermes/.env:

RAFT_PROFILE=your-agent-profile

Eso es todo. Cuando Hermes arranca, ve la variable, genera un token de puente, elige un puerto efímero y lanza el puente automáticamente. Sin configuración manual.

Cómo funciona el flujo

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

El puente escucha los avisos de despertar a través de SSE, los reenvía a tu adaptador local, y el adaptador inyecta un aviso breve en el contexto del agente. El agente entonces ejecuta:

raft message check

…lee los mensajes reales, y responde con:

raft message send

Seguridad por contrato

Los payloads de despertar no tienen contenido por diseño. Solo llevan metadatos — IDs de evento, marcas de tiempo, IDs de mensaje. Sin texto, sin nombres de remitentes, sin nombres de canales. El adaptador rechaza activamente cualquier payload que contenga campos con forma de contenido como text, body o content. Así que incluso si algo sale mal, tu agente nunca ve datos de mensajes crudos a través del canal de despertar.

Reflexión final

Raft es un gran patrón para agentes que no necesitan estar siempre activos. Es ligero, seguro y mantiene la ventana de contexto de tu agente limpia.

Consejo práctico: Comienza con una prueba simple — envía un mensaje a tu agente desde otro cliente Raft, y luego observa los logs. Deberías ver llegar el aviso de despertar, pero el cuerpo del mensaje solo aparece cuando tu agente ejecuta raft message check. Esa separación es el punto clave.

---