Mattermost Hermes Agent — Chat Tim Mandiri | Easy Understand Hermes Agent

Mattermost Hermes Agent — Chat Tim Mandiri

Jika tim Anda memakai Mattermost, Anda sudah tahu daya tariknya: tampilan dan rasanya seperti Slack, tetapi server — dan datanya — tetap berada di infrastruktur Anda sendiri. Hermes Agent terhubung ke sana sebagai bot, melalui REST API Mattermost (v4) plus WebSocket untuk peristiwa real-time, sehingga asisten Anda bisa menjawab di DM dan kanal tim tanpa ada apa pun yang keluar dari jaringan Anda.

Tidak ada pustaka tambahan yang perlu dipasang: adapter ini memakai aiohttp, yang sudah disertakan bersama Hermes. Ini berfungsi baik dengan Mattermost Team Edition (gratis) maupun Enterprise Edition.

Bagaimana Hermes Berperilaku di Mattermost

Di mana Anda mengobrol dengannya	Apa yang terjadi
DM	Hermes menjawab setiap pesan — tidak perlu `@mention`. Setiap DM punya sesinya sendiri.
Kanal	Hermes menjawab saat Anda `@mention` dirinya. Tanpa mention, ia mengabaikan pesan itu.
Thread	Dengan `MATTERMOST_REPLY_MODE=thread`, balasan bersarang di bawah pesan Anda dan tetap terpisah dari kanal induknya.
Kanal bersama	Riwayat sesi dipisahkan per pengguna secara default, jadi dua orang di satu kanal tidak berbagi transkrip.

Perilaku terakhir itu dikendalikan oleh group_sessions_per_user di config.yaml:

group_sessions_per_user: true   # each person keeps their own context

Setel ke false hanya jika Anda memang ingin satu percakapan bersama untuk seluruh kanal. Sesi bersama berarti semua orang berbagi pertumbuhan konteks dan biaya token, dan tugas berat berbasis tool milik satu orang bisa membengkakkan atau mengganggu proses orang lain.

Langkah 1: Aktifkan Akun Bot (Sisi Admin)

Akun bot harus diaktifkan di server sebelum Anda bisa membuatnya:

Masuk ke Mattermost sebagai System Admin.
Buka System Console → Integrations → Bot Accounts.
Setel Enable Bot Account Creation ke true, lalu klik Save.

Tidak punya akses admin? Minta administrator Mattermost Anda untuk mengaktifkan akun bot dan membuatkannya untuk Anda.

Langkah 2: Buat Akun Bot

Klik menu ☰ (kiri atas) → Integrations → Bot Accounts → Add Bot Account.
Isi detailnya: Username seperti hermes, Display Name seperti Hermes Agent, dan Role — Member sudah cukup.
Klik Create Bot Account, lalu salin tokennya segera — token hanya ditampilkan sekali. Jika hilang, Anda harus membuat ulang dari pengaturan akun bot.

⚠️ Jangan pernah membagikan token atau meng-commit-nya ke Git. Siapa pun yang memegangnya punya kendali penuh atas bot.

Lebih suka agen memposting sebagai pengguna Anda sendiri alih-alih bot terpisah? Buat personal access token di Profile → Security → Personal Access Tokens → Create Token.

Langkah 3: Undang Bot ke Kanal

Bot hanya merespons di kanal tempat ia menjadi anggota:

Buka kanal → klik nama kanal → Add Members.
Cari username bot (misalnya hermes) dan tambahkan.

Untuk DM, cukup buka pesan langsung dengan bot — tidak perlu undangan.

Langkah 4: Temukan User ID Mattermost Anda

Hermes memakai User ID Anda — bukan username — untuk menentukan siapa yang boleh berbicara dengan bot:

Klik avatar Anda (pojok kiri atas) → Profile.
Dialog menampilkan User ID Anda: string alfanumerik 26 karakter seperti 3uo8dkh1p7g1mfk49ear5fzs5c. Klik untuk menyalinnya.

Anda juga bisa membacanya dari API:

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

User ID Anda bukan @username yang Anda lihat di pesan. Menempelkan username adalah alasan paling umum bot tetap diam.

Langkah 5: Konfigurasikan Hermes

Jalankan penyiapan terpandu dan pilih Mattermost saat diminta — ia akan menanyakan URL server, token bot, dan User ID Anda:

hermes gateway setup

Atau sambungkan secara manual di ~/.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

Lalu jalankan gateway:

hermes gateway

Bot terhubung ke server Mattermost Anda dalam beberapa detik. Kirim DM, atau @mention dirinya di kanal tempat ia sudah ditambahkan, untuk menguji.

Langkah 6: Sakelar Perilaku Opsional

Pengaturan	Fungsinya
`MATTERMOST_REPLY_MODE`	`off` (default) memposting pesan datar; `thread` membuat balasan bersarang di bawah pesan Anda dan menjaga kanal yang ramai tetap rapi.
`MATTERMOST_REQUIRE_MENTION`	`true` secara default. Setel ke `false` untuk merespons semua pesan kanal (DM selalu berfungsi).
`MATTERMOST_FREE_RESPONSE_CHANNELS`	ID kanal yang melewati syarat mention meskipun mention diwajibkan.
`MATTERMOST_HOME_CHANNEL`	Tempat pesan proaktif dikirim — keluaran cron, pengingat, notifikasi. Atau ketik `/sethome` di sebuah kanal.
`mattermost.allowed_channels`	Batasi bot ke daftar ID kanal; pesan dari mana pun selain itu akan dibuang. DM dikecualikan.
`mattermost.channel_prompts`	Menyuntikkan system prompt sementara per kanal — diterapkan pada setiap giliran, tidak pernah disimpan ke riwayat transkrip.

Saat bot di-@mention, mention tersebut dihapus dari pesan sebelum diproses, jadi @hermes summarize this thread tiba sebagai instruksi yang bersih.

Pemecahan Masalah

Gejala	Kemungkinan penyebab	Perbaikan
Bot mengabaikan Anda di kanal	Ia tidak ada di kanal, atau User ID Anda tidak ada di `MATTERMOST_ALLOWED_USERS`	Tambahkan bot ke kanal, verifikasi User ID 26 karakter, mulai ulang gateway
Bot tidak bisa memposting	Token tidak valid, atau bot tidak punya izin di kanal itu	Periksa `MATTERMOST_TOKEN`, pastikan akun aktif dan menjadi anggota kanal
Sering terputus	WebSocket terputus, server restart, atau masalah proxy/firewall	Adapter menyambung ulang dengan exponential backoff (2s → 60s); untuk nginx, pastikan header upgrade WebSocket sudah dikonfigurasi
Tidak terjadi apa-apa sama sekali	Gateway tidak berjalan, atau URL/token salah	Periksa keluaran `hermes gateway`, dan pastikan `MATTERMOST_URL` menyertakan `https://` tanpa garis miring di akhir

Uji token secara langsung dengan:

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

Mengamankan Bot

Selalu setel MATTERMOST_ALLOWED_USERS. Tanpanya, gateway menolak semua pengguna secara default sebagai langkah pengamanan — dan pengguna yang diizinkan mendapat akses penuh ke kemampuan agen, termasuk penggunaan tool dan akses sistem, jadi jaga daftarnya tetap ketat. Untuk pandangan yang lebih luas tentang memperkuat deployment, lihat panduan keamanan resmi.

Apa Selanjutnya?

Setelah gateway aktif, Mattermost berperilaku seperti kanal Hermes lainnya: perintah slash, unggahan berkas, catatan suara, keluaran cron yang dikirim ke kanal home Anda — semuanya di infrastruktur yang Anda kendalikan. Jika Anda lebih suka opsi terkelola, integrasi Slack membahas jalur Socket Mode; jika Anda menjalankan gateway di beberapa mesin, Hermes Relay menghubungkannya.