Microsoft Teams — Chat Aziendale

Immagina di collegare Hermes Agent a Microsoft Teams come se dessi al tuo assistente AI un badge aziendale — una volta che è nel team, può partecipare alle riunioni, rispondere alle domande nei canali e dare una mano nei messaggi privati, tutto senza uscire dall’app che i tuoi colleghi usano già ogni giorno.

Perché Teams è Diverso da Slack

Se hai già usato lo Slack Socket Mode, sappi che Teams funziona in modo un po’ diverso. Invece di mantenere una connessione aperta, Teams chiama il webhook pubblico del tuo bot ogni volta che qualcuno invia un messaggio. Questo significa che la tua istanza di Hermes ha bisogno di un URL HTTPS pubblico — non localhost. Per i test, puoi usare un tunnel; per la produzione, lo punterai al dominio del tuo server reale.

Come si Comporta il Bot

Ecco la semplice regola pratica:

Dove gli parli	Cosa succede
Chat personale (DM)	Il bot risponde a ogni messaggio — nessun bisogno di @menzionarlo
Chat di gruppo	Il bot risponde solo quando lo @menzioni
Canale	Il bot risponde solo quando lo @menzioni

Teams invia le @menzioni come tag <at>NomeBot</at>, ma Hermes le rimuove automaticamente prima di elaborarle — quindi non devi preoccupartene.

Passo 1: Installa la CLI di Teams

Per prima cosa, installa lo strumento da riga di comando di Microsoft che automatizza la registrazione del bot — nessun portale Azure necessario:

npm install -g @microsoft/teams.cli@preview
teams login

Per verificare il login e trovare il tuo AAD object ID (ti servirà dopo per limitare l’accesso), esegui:

teams status --verbose

Passo 2: Esponi la Porta del Webhook

Teams non può consegnare messaggi a localhost. Per lo sviluppo locale, usa un tunnel per ottenere un URL HTTPS pubblico. La porta predefinita è 3978 (cambiala con TEAMS_PORT se necessario).

Ecco tre semplici opzioni:

# devtunnel (Microsoft)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol https
devtunnel host hermes-bot

# ngrok
ngrok http 3978

# cloudflared
cloudflared tunnel --url http://localhost:3978

Copia l’URL https:// dall’output — ti servirà nel prossimo passo. Lascia il tunnel in esecuzione mentre sviluppi.

Passo 3: Crea il Bot

Ora registra il tuo bot con Teams:

teams app create \
  --name "Hermes" \
  --endpoint "https://<il-tuo-url-tunnel>/api/messages"

La CLI restituirà il tuo CLIENT_ID, CLIENT_SECRET e TENANT_ID, più un link di installazione. Salva subito il client secret — non verrà mostrato di nuovo.

Passo 4: Configura le Variabili d’Ambiente

Aggiungile al tuo file ~/.hermes/.env:

# Richieste
TEAMS_CLIENT_ID=<il-tuo-client-id>
TEAMS_CLIENT_SECRET=<il-tuo-client-secret>
TEAMS_TENANT_ID=<il-tuo-tenant-id>

# Limita l'accesso a utenti specifici (consigliato)
# Usa gli AAD object ID da `teams status --verbose`
TEAMS_ALLOWED_USERS=<il-tuo-aad-object-id>

Passo 5: Avvia il Gateway

Se usi Docker, esegui dalla directory che contiene docker-compose.yml (di solito la repo clonata di hermes-agent, non ~):

cd /path/to/hermes-agent
HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up

Per le installazioni da sorgente, assicurati di includere prima l’extra Teams:

uv sync --extra teams
# oppure, per installazioni modificabili:
uv pip install -e ".[teams]"

Per Concludere

Collegare Hermes a Teams è una danza in quattro passi: installa la CLI, esponi un URL pubblico, crea il bot e imposta le variabili d’ambiente. Una volta in esecuzione, il tuo assistente AI diventa un membro a tutti gli effetti del team — risponde automaticamente nei DM e si unisce alle chat di gruppo quando viene chiamato.

Consiglio pratico: Inizia impostando TEAMS_ALLOWED_USERS solo con il tuo AAD object ID. In questo modo, puoi testare in sicurezza senza preoccuparti che colleghi a caso attivino il tuo bot — poi espandi l’accesso quando sei sicuro che tutto funzioni.

---