Discord — AI nel Tuo Server

Discord — AI nel Tuo Server

Vuoi mettere Hermes Agent nel tuo server Discord? Ottima scelta. Questa guida ti accompagna attraverso tutto ciò che devi sapere — da come si comporta Hermes una volta invitato, alla procedura di configurazione completa, fino ad alcune importanti nuove funzionalità di health-check.

Iniziamo con la parte divertente: com’è davvero chattare con Hermes su Discord.

Come si Comporta Hermes nel Tuo Server

Hermes non è solo un bot stupido che risponde a tutto. È intelligente su quando e dove parlare. Ecco il riepilogo:

Contesto	Comportamento
Messaggi diretti	Hermes risponde a ogni messaggio. Nessun @mention necessario. Ogni DM ha la propria sessione privata.
Canali del server	Di default, Hermes risponde solo quando lo menzioni con @mention. Altrimenti, rimane in silenzio.
Canali a risposta libera	Vuoi un canale dove le persone possono chattare senza taggare? Aggiungilo a DISCORD_FREE_RESPONSE_CHANNELS e Hermes risponderà a ogni messaggio inline.
Thread	Hermes risponde nello stesso thread. Le regole di menzione restano valide a meno che il thread o il suo canale padre non sia a risposta libera.
Canali condivisi	Di default, Hermes mantiene separata la cronologia delle conversazioni di ogni utente — anche nello stesso canale. Alice e Bob che parlano in #ricerca hanno due sessioni indipendenti.
Messaggi che menzionano altri	Se qualcuno menziona un altro utente ma non Hermes, il bot rimane in silenzio di default. Niente intrusioni in conversazioni che non lo riguardano.

Consiglio da pro: Vuoi un canale dedicato di assistenza al bot dove le persone possono semplicemente scrivere e ricevere risposte? Aggiungi quel canale a DISCORD_FREE_RESPONSE_CHANNELS e il gioco è fatto.

Il Modello Gateway: Più di un Semplice Webhook

Ecco una cosa importante: Hermes su Discord non è un semplice webhook che invia una risposta preimpostata. Ogni messaggio passa attraverso un pipeline completo:

1. Controllo autorizzazione (DISCORD_ALLOWED_USERS)
2. Controlli menzione / risposta libera
3. Ricerca sessione
4. Caricamento trascrizione sessione
5. Esecuzione completa dell’agente — strumenti, memoria, comandi slash
6. Invio della risposta a Discord

Questo significa che ogni risposta è supportata dall’intelligenza completa di Hermes, non solo da una risposta scriptata.

Sessioni: Chi Condivide Cosa?

Di default, Hermes isola le conversazioni:

• Ogni DM ha la propria sessione
• Ogni thread ha il proprio namespace di sessione
• Ogni utente in un canale condiviso ha la propria sessione

Questo è controllato in config.yaml:

group_sessions_per_user: true

Se vuoi una conversazione condivisa per un intero canale (utile per spazi collaborativi), impostalo su false:

group_sessions_per_user: false

Ma attenzione: sessioni condivise significano contesto condiviso e costi di token condivisi. Un compito lungo e pesante di strumenti di una persona può gonfiare il contesto di tutti. E se qualcuno interrompe a metà esecuzione, può disturbare l’intero canale.

Interruzioni e Concorrenza

Con sessioni per utente (il default), Alice può interrompere la sua richiesta senza influenzare la conversazione di Bob nello stesso canale. Bob mantiene la sua cronologia, Alice mantiene la sua, e nessuno pesta i piedi a nessuno.

Con sessioni condivise, l’intero canale condivide un unico “slot agente in esecuzione”. I messaggi di follow-up di persone diverse possono interrompersi o accodarsi a vicenda. Divertente per la collaborazione, ma potenzialmente caotico.

Novità: Health Check del Gateway WebSocket

Ecco un miglioramento recente che vale la pena conoscere. Discord ha due trasporti separati: REST e il Gateway WebSocket. Una chiamata REST riuscita non prova che il bot possa ancora ricevere eventi in tempo reale.

Hermes ora monitora la salute del gateway controllando:

• Stato di ready
• Stato di chiusura client/socket
• Apertura del socket
• Età dell’ACK dell’heartbeat
• Latenza dell’heartbeat

Dopo un numero configurato di campioni non sani, l’adapter emette un evento fatale ritentabile e si riconnette in modo pulito. Niente loop di riconnessione infiniti.

Configura le soglie in config.yaml:

discord:
  websocket_liveness_interval_seconds: 15
  websocket_liveness_failure_threshold: 2
  websocket_heartbeat_ack_max_age_seconds: 60
  websocket_max_latency_seconds: 30

Nota: i vecchi nomi liveness_interval_seconds e liveness_failure_threshold funzionano ancora come alias di compatibilità, ma non significano più probing REST.

Passo 1: Crea un’Applicazione Discord

1. Vai al Discord Developer Portal e accedi.
2. Clicca su New Application nell’angolo in alto a destra.
3. Dai un nome alla tua applicazione (es. “Hermes Agent”) e accetta i Termini di Servizio per Sviluppatori.
4. Clicca su Create.

Ti ritroverai sulla pagina General Information. Annota il tuo Application ID — ti servirà per costruire l’URL di invito.

Passo 2: Crea il Bot

1. Nella barra laterale di sinistra, clicca su Bot.
2. Discord crea automaticamente un utente bot per la tua applicazione. Personalizza il nome utente se vuoi.
3. Sotto Authorization Flow, imposta Public Bot su ON — necessario per il link di invito fornito da Discord.

Questa è la base. Da qui, recupererai il token del tuo bot, imposterai le variabili d’ambiente e inviterai Hermes nel tuo server. In men che non si dica, il tuo assistente AI sarà proprio lì in Discord — pronto a chattare, usare strumenti e ricordare il contesto, tutto in tempo reale.