Mattermost Hermes Agent — chat aziendale

Mattermost Hermes Agent — chat aziendale

Se il tuo team usa Mattermost, conosci già il vantaggio: sembra e funziona come Slack, ma il server — e i dati — restano sulla tua infrastruttura. Hermes Agent si collega come bot, connettendosi tramite l’API REST di Mattermost (v4) più un WebSocket per gli eventi in tempo reale, così il tuo assistente può rispondere in DM e nei canali del team senza che nulla esca dalla tua rete.

Non c’è nessuna libreria extra da installare: l’adapter usa aiohttp, che è già incluso in Hermes. Funziona sia con Mattermost Team Edition (gratuita) che con Enterprise Edition.

Come si comporta Hermes in Mattermost

Dove ci parli	Cosa succede
DM	Hermes risponde a ogni messaggio — non serve @mention. Ogni DM ha la sua sessione.
Canali	Hermes risponde quando lo @mention. Senza menzione, ignora il messaggio.
Thread	Con MATTERMOST_REPLY_MODE=thread, le risposte si annidano sotto il tuo messaggio e restano isolate dal canale principale.
Canali condivisi	La cronologia della sessione è isolata per utente per impostazione predefinita, quindi due persone nello stesso canale non condividono la trascrizione.

Quest’ultimo comportamento è controllato da group_sessions_per_user in config.yaml:

group_sessions_per_user: true   # each person keeps their own context

Impostalo su false solo se vuoi deliberatamente un’unica conversazione condivisa per l’intero canale. Una sessione condivisa significa che tutti condividono la crescita del contesto e i costi in token, e l’attività lunga e piena di tool di una persona può appesantire o interrompere l’esecuzione di qualcun altro.

---

Step 1: Abilitare gli account bot (lato admin)

Gli account bot devono essere attivati sul server prima che tu possa crearne uno:

1. Accedi a Mattermost come System Admin.
2. Vai su System Console → Integrations → Bot Accounts.
3. Imposta Enable Bot Account Creation su true, poi clicca Save.

Non hai accesso admin? Chiedi al tuo amministratore di Mattermost di abilitare gli account bot e crearne uno per te.

Step 2: Creare l’account bot

1. Clicca il menu ☰ (in alto a sinistra) → Integrations → Bot Accounts → Add Bot Account.
2. Compila i dettagli: Username come hermes, Display Name come Hermes Agent, e un Role — Member è sufficiente.
3. Clicca Create Bot Account, poi copia subito il token — viene mostrato solo una volta. Se lo perdi, dovrai rigenerarlo dalle impostazioni dell’account bot.

⚠️ Non condividere mai il token e non inserirlo in Git. Chiunque lo possieda ha il pieno controllo del bot.

Preferisci che l’agente pubblichi come il tuo utente invece che come un bot separato? Crea un personal access token in Profile → Security → Personal Access Tokens → Create Token.

Step 3: Invitare il bot nei canali

Il bot risponde solo nei canali a cui appartiene:

1. Apri il canale → clicca sul nome del canale → Add Members.
2. Cerca lo username del bot (ad esempio hermes) e aggiungilo.

Per i DM, apri semplicemente un messaggio diretto con il bot — non serve invito.

Step 4: Trovare il tuo User ID di Mattermost

Hermes usa il tuo User ID — non il tuo username — per decidere chi è autorizzato a parlare con il bot:

1. Clicca il tuo avatar (angolo in alto a sinistra) → Profile.
2. La finestra mostra il tuo User ID: una stringa alfanumerica di 26 caratteri come 3uo8dkh1p7g1mfk49ear5fzs5c. Cliccala per copiarla.

Puoi anche leggerlo dall’API:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

Il tuo User ID non è lo @username che vedi nei messaggi. Incollare lo username è il motivo più comune per cui un bot resta in silenzio.

Step 5: Configurare Hermes

Esegui la configurazione guidata e scegli Mattermost quando richiesto — ti chiede l’URL del server, il token del bot e il tuo User ID:

hermes gateway setup

Oppure configuralo manualmente in ~/.hermes/.env:

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply in a thread instead of flat messages (default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without an @mention (default: true = mention required)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where no @mention is needed (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

Poi avvia il gateway:

hermes gateway

Il bot si connette al tuo server Mattermost in pochi secondi. Mandagli un DM, oppure @mention in un canale dove è stato aggiunto, per fare una prova.

Step 6: Interruttori di comportamento opzionali

Impostazione	Cosa fa
MATTERMOST_REPLY_MODE	off (predefinito) pubblica messaggi piatti; thread annida le risposte sotto il tuo messaggio e mantiene ordinati i canali trafficati.
MATTERMOST_REQUIRE_MENTION	true per impostazione predefinita. Impostalo su false per rispondere a tutti i messaggi del canale (i DM funzionano sempre).
MATTERMOST_FREE_RESPONSE_CHANNELS	ID dei canali che saltano il requisito della menzione anche quando le menzioni sono richieste.
MATTERMOST_HOME_CHANNEL	Dove vanno i messaggi proattivi — output di cron, promemoria, notifiche. Oppure digita /sethome in un canale.
mattermost.allowed_channels	Limita il bot a una lista di ID di canali; i messaggi da qualsiasi altro posto vengono scartati. I DM sono esenti.
mattermost.channel_prompts	Inietta un system prompt effimero per canale — applicato a ogni turno, mai salvato nella cronologia della trascrizione.

Quando il bot viene @mentioned, la menzione viene rimossa dal messaggio prima dell’elaborazione, quindi @hermes summarize this thread arriva come un’istruzione pulita.

Risoluzione dei problemi

Sintomo	Causa probabile	Soluzione
Il bot ti ignora nei canali	Non è nel canale, oppure il tuo User ID non è in MATTERMOST_ALLOWED_USERS	Aggiungi il bot al canale, verifica lo User ID di 26 caratteri, riavvia il gateway
Il bot non riesce a pubblicare	Token non valido, o il bot non ha i permessi in quel canale	Controlla MATTERMOST_TOKEN, conferma che l’account sia attivo e membro del canale
Disconnessioni continue	Cadute del WebSocket, riavvii del server, o problemi di proxy/firewall	L’adapter si riconnette con backoff esponenziale (2s → 60s); per nginx, assicurati che gli header di upgrade WebSocket siano configurati
Non succede nulla	Il gateway non è in esecuzione, o l’URL/token è sbagliato	Controlla l’output di hermes gateway, e che MATTERMOST_URL includa https:// senza slash finale

Testa un token direttamente con:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

Proteggere il bot

Imposta sempre MATTERMOST_ALLOWED_USERS. Senza di esso, il gateway nega tutti gli utenti per impostazione predefinita come misura di sicurezza — e gli utenti autorizzati ottengono pieno accesso alle capacità dell’agente, incluso l’uso dei tool e l’accesso al sistema, quindi mantieni la lista ristretta. Per una panoramica più ampia su come mettere in sicurezza un deployment, consulta le linee guida ufficiali sulla sicurezza.

---

E adesso?

Una volta che il gateway è attivo, Mattermost si comporta come qualsiasi altro canale di Hermes: comandi slash, caricamento di file, note vocali, output di cron consegnato al tuo canale home — tutto su infrastruttura che controlli tu. Se preferisci l’opzione hosted, l’integrazione Slack copre la strada di Socket Mode; se esegui gateway su più macchine, Hermes Relay li connette.