Hướng dẫn kết nối Google Chat với Hermes Agent A-Z

Khi kết nối Google Chat với Hermes Agent, bạn có thể trò chuyện trực tiếp với Agent ngay trong Google Chat, gửi yêu cầu, nhận phản hồi và triển khai các tác vụ hỗ trợ công việc ngay tại môi trường làm việc hằng ngày. Bài viết dưới đây sẽ hướng dẫn chi tiết cách cấu hình Google Chat, Cloud Pub/Sub và Hermes Agent để tạo một bot Google Chat có thể nhận tin nhắn và phản hồi thông qua Hermes Gateway.

Tại sao nên kết nối Google Chat với Hermes Agent?

Việc kết nối Google Chat với Hermes Agent giúp bạn biến Google Chat thành một kênh giao tiếp trực tiếp với AI Agent. Thay vì phải mở giao diện riêng hoặc truy cập terminal, bạn có thể nhắn tin với Hermes Agent ngay trong Google Chat.

Một số tình huống sử dụng phổ biến gồm:

• Gửi câu hỏi nhanh cho Hermes Agent trong Google Chat.
• Tạo trợ lý nội bộ cho nhóm làm việc.
• Nhận phản hồi tự động từ AI Agent trong cuộc trò chuyện 1:1.
• Kết hợp Google Chat với các tác vụ Workspace khác như Gmail, Calendar, Drive, Docs hoặc Sheets.
• Tạo kênh tương tác tiện lợi cho nhân viên, khách hàng hoặc đội vận hành.

Cách triển khai qua Cloud Pub/Sub cũng phù hợp hơn với kiến trúc chính thức của Hermes, giúp quá trình nhận message ổn định và dễ kiểm soát hơn so với việc tự dựng webhook endpoint.

Thông tin cấu hình cần chuẩn bị

Trước khi thực hiện, bạn cần chuẩn bị:

• Tài khoản Google hoặc Google Workspace.
• Quyền truy cập Google Cloud Console.
• Một Google Cloud Project.
• VPS/máy chủ đã cài Hermes Agent.
• Quyền SSH vào máy chủ Hermes.
• Quyền cấu hình Hermes Gateway.
• Email Google được phép sử dụng Chat App.

Các bước kết nối Google Chat với Hermes Agent

Bước 1: Chọn đúng Google Cloud Project

Đầu tiên, hãy truy cập Google Cloud Console: https://console.cloud.google.com/

Sau khi đăng nhập, hãy chọn đúng Google Cloud Project dùng để cấu hình Google Chat App và Cloud Pub/Sub.

Nếu chưa có project, bạn có thể tạo project mới bằng cách:

1. Nhấn vào khu vực chọn project ở thanh trên cùng.
2. Chọn New Project.
3. Nhập tên project, ví dụ: Hermes Google Chat
4. Nhấn Create.

Chọn lại project vừa tạo để tiếp tục cấu hình.

Lưu ý: Tất cả API, Topic, Subscription, Service Account và Google Chat App nên nằm trong cùng một project để tránh lỗi sai project khi cấu hình.

Bước 2: Bật các API cần thiết

Để Google Chat và Cloud Pub/Sub hoạt động, bạn cần bật 2 API sau:

• Google Chat API: Cho phép bạn cấu hình Chat App và dùng Chat REST API để phản hồi tin nhắn.
• Cloud Pub/Sub API: Cho phép tạo Topic, Subscription và xử lý luồng message giữa Google Chat và Hermes Gateway.

Truy cập nhanh trang API Library tại: https://console.cloud.google.com/apis/library

Sau đó thực hiện lần lượt:

Nhập từ khóa Google Chat API -> Chọn kết quả -> Nhấn Enable -> Chờ Google bật API cho project.

Sau khi bật thành công, nút Enable sẽ chuyển sang trạng thái đã kích hoạt hoặc giao diện sẽ hiển thị trang quản lý API.

Tương tự, nhập từ khóa Cloud Pub/Sub API -> Chọn kết quả -> Nhấn Enable -> Chờ Google bật API cho project.

Bước 3: Tạo Cloud Pub/Sub Topic

Sau khi bật API, bạn cần tạo Pub/Sub Topic để Google Chat publish event vào.

Truy cập nhanh trang quản lý Topics: https://console.cloud.google.com/cloudpubsub/topic/list

Sau đó thực hiện:

1. Chọn Topics.
2. Nhấn Create topic.
3. Nhập Topic ID: hermes-chat-events
4. Giữ các tùy chọn mặc định nếu không có yêu cầu đặc biệt.
5. Kéo xuống nhấn Create.

Sau khi tạo xong, topic sẽ có tên đầy đủ dạng:

projects/<PROJECT_ID>/topics/hermes-chat-events

Ví dụ:

projects/dulcet-legend-499603-h9/topics/hermes-chat-events

Bạn cần lưu lại tên đầy đủ này để dùng ở bước cấu hình Google Chat App.

Bước 4: Tạo Pull Subscription

Tiếp theo, bạn cần tạo Subscription để Hermes Gateway có thể đọc message từ Topic.

Tại trang quản lý Subscriptions:

1. Chọn Subscriptions.
2. Nhấn Create subscription.
3. Nhập Subscription ID: hermes-chat-events-subscription
4. Chọn Topic vừa tạo: hermes-chat-events
5. Tại Delivery type, chọn: Pull
6. Message retention có thể để mặc định hoặc đặt: 7 days
7. Giữ mặc định các thiết lập khác
8. Kéo xuống nhấn Create.

Sau khi tạo thành công, Subscription sẽ có tên đầy đủ dạng:

projects/<PROJECT_ID>/subscriptions/hermes-chat-events-sub

Ví dụ:

projects/dulcet-legend-499603-h9/subscriptions/hermes-chat-events-subscription

Bạn cần dùng tên đầy đủ này khi cấu hình Hermes.

Bước 5: Cấp quyền để Google Chat publish vào Topic

Google Chat cần quyền publish message vào Pub/Sub Topic. Nếu thiếu quyền này, bot có thể hiển thị trong Google Chat nhưng Hermes sẽ không nhận được message.

Truy cập lại danh sách Topic: https://console.cloud.google.com/cloudpubsub/topic/list

Sau đó:

1. Mở topic: hermes-chat-events
2. Chọn tab Permissions.
3. Nhấn Add principal.
4. Tại ô New principals, nhập: chat-api-push@system.gserviceaccount.com
5. Tại Role, chọn: Pub/Sub Publisher
6. Nhấn Save.

Phần này sẽ được hướng dẫn ở bước 9. Nếu trong giao diện cấu hình Google Chat có hiển thị thêm service account dạng: service-xxxxxxxxxxxx@gcp-sa-gsuiteaddons.iam.gserviceaccount.com bạn nên cấp thêm quyền Pub/Sub Publisher cho email service account này trên cùng Topic. Việc này giúp tránh trường hợp bot nhận tin nhắn nhưng không publish event vào Pub/Sub, dẫn đến bot im lặng.

Bước 6: Tạo Service Account cho Hermes

Hermes Gateway cần một Service Account để đọc message từ Pub/Sub Subscription. Service Account này sẽ được tạo trong Google Cloud và tải key JSON về server Hermes.

Truy cập nhanh trang Service Accounts: https://console.cloud.google.com/iam-admin/serviceaccounts

Sau đó thực hiện:

1. Chọn Project hiện tại.
2. Nhấn Create service account.
3. Nhập Service account name: hermes-chat-bot
4. Service account ID sẽ được tạo tự động, ví dụ: hermes-chat-bot
5. Phần cấp quyền project-level có thể bỏ trống.
6. Nhấn Create and Close để hoàn tất.

Lưu ý: Ở bước tạo service account, bạn chưa cần cấp quyền toàn project. Quyền sẽ được cấp riêng trên Subscription ở bước tiếp theo để đảm bảo nguyên tắc phân quyền tối thiểu.

Bước 7: Tạo key JSON cho Service Account và upload lên Hermes Agent

Tạo key JSON

Sau khi tạo Service Account, bạn cần tạo key JSON để Hermes Gateway sử dụng.

Thực hiện như sau:

1. Mở Service Account vừa tạo.
2. Chọn tab Keys.
3. Nhấn Add key.
4. Chọn Create new key.
5. Chọn định dạng: JSON
6. Nhấn Create.

File JSON sẽ được tải về máy tính. Bạn có thể đổi tên file đơn giản hơn, ví dụ: google-chat-sa

Upload file lên server Hermes

Tiếp theo, bạn cần upload file JSON này lên server Hermes tại đường dẫn:

/root/.hermes/google-chat-sa.json

Để thực hiện, bạn có thể dùng SCP, SFTP, WinSCP hoặc FileZilla để upload file.

Ví dụ dùng SCP trên máy tính. Mở PowerShell trên Windows và nhập lệnh:

scp "C:\Users\ADMIN\Downloads\google-chat-sa.json" root@<IP_VPS>:/root/.hermes/google-chat-sa.json

Nhập mật khẩu VPS khi được yêu cầu. Sau đó, file JSON sẽ được upload lên server Hermes.

Sau khi upload, SSH vào VPS và đặt quyền file (xem thêm: Hướng dẫn sử dụng phần mềm Xshell kết nối SSH tới VPS):

chmod 600 /root/.hermes/google-chat-sa.json

Lệnh này giúp giới hạn quyền đọc file key, tránh rủi ro lộ thông tin xác thực.

Bước 8: Cấp quyền để Hermes đọc Subscription

Hermes Gateway cần quyền đọc Subscription để pull message từ Pub/Sub. Ngoài quyền Subscriber, Hermes cũng cần quyền Viewer vì khi khởi động, Gateway có thể gọi subscription.get() để kiểm tra Subscription.

Truy cập danh sách Subscriptions: https://console.cloud.google.com/cloudpubsub/subscription/list

Sau đó:

1. Mở subscription: hermes-chat-events-subscription
2. Chọn tab Permissions.
3. Nhấn Add principal.
4. Tại New principals, nhập email Service Account Hermes, dạng: hermes-chat-bot@<PROJECT_ID>.iam.gserviceaccount.com
5. Thêm role thứ nhất: Pub/Sub Subscriber
6. Thêm role thứ hai: Pub/Sub Viewer
7. Nhấn Save.

Nếu cấu hình đúng, Hermes sẽ có đủ quyền đọc message từ Subscription.

Bước 9: Cấu hình Google Chat App

Sau khi Pub/Sub và Service Account đã sẵn sàng, bạn cần cấu hình Google Chat App để bot hiển thị trong Google Chat.

Truy cập nhanh trang cấu hình Google Chat API: https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat

Sau đó vào phần Configuration.

Cấu hình thông tin ứng dụng

Ở mục Application info, bạn điền như sau:

• App name: Hermes Agent
• Avatar URL: URL ảnh logo dạng HTTPS
• Description: AI trợ lý Hermes Agent

Lưu ý:

• Phần Avatar URL không nhập file trên máy tính được. Google yêu cầu một đường dẫn ảnh công khai dạng HTTPS, ví dụ: https://tenmiencuaban.com/hermes-agent.png. Cách đơn giản là bạn upload logo Hermes Agent lên website/hosting của mình, sau đó lấy link ảnh.
• Ảnh nên là PNG, vuông 1:1, tối thiểu 256×256 pixel.

Cấu hình Connection settings

Tại phần Connection settings, chọn Cloud Pub/Sub

Sau đó nhập Cloud Pub/Sub Topic Name theo dạng đầy đủ:

projects/<PROJECT_ID>/topics/hermes-chat-events

Ví dụ:

projects/dulcet-legend-499603-h9/topics/hermes-chat-events

Lưu ý: Đây phải là Topic đã cấp quyền Publisher cho Google Chat ở bước trước.

Đặc biệt quan trọng:

Lát nữa sau khi Save lần đầu rồi nhấn F5, Google Chat sẽ hiển thị thêm Service Account Email. Hãy copy email này.

Sau đó, quay lại phần Cấp quyền để Google Chat publish vào Topic ở bước 5 và tiến hành tạo thêm một principal khác:

Nhập Service Account Email vào ô New principals vừa copy -> sau đó cấp quyền Pub/Sub Publisher tương tự như principal trước.

Cấu hình Visibility

Tại phần Visibility, thêm email Google được phép sử dụng bot.

Nếu bạn đang test bằng tài khoản cá nhân hoặc tài khoản Workspace cụ thể, hãy thêm đúng email đó vào Visibility. Nếu sai email, khi vào Google Chat, bạn có thể không tìm thấy bot.

Sau khi cấu hình xong, nhấn Save.

Bước 10: Cấu hình biến môi trường cho Hermes

Trên server Hermes, bạn cần cấu hình các biến môi trường để Hermes Gateway biết project, subscription, service account JSON và danh sách user được phép dùng Google Chat.

Mở file cấu hình môi trường của Hermes, thường là file .env trong thư mục cài Hermes.

Vào thư mục Hermes:

cd /opt/hermes/hermes-agent

Sử dụng lệnh sau để kiểm tra xem file .env có tồn tại không:

ls -la

Bạn hãy nhìn lướt qua danh sách hiện ra xem có thấy file .env hoặc file .env.example không nhé! Thông thường VPS Hermes của Tino sẽ chứa file mẫu .env.example.

Thực hiện lệnh sau để tạo file .env từ file mẫu:

cp .env.example .env

Sau đó mở bằng vi:

vi .env

Trong vi, làm theo các bước này:

1. Di chuyển đến cuối file bằng cách nhấn Shift + g rồi nhấn i để để chuyển sang chế độ gõ
2. Dán đoạn cấu hình này vào:
   

GOOGLE_CHAT_PROJECT_ID=<PROJECT_ID>

GOOGLE_CHAT_SUBSCRIPTION_NAME=projects/<PROJECT_ID>/subscriptions/hermes-chat-events-sub

GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=/root/.hermes/google-chat-sa.json

GOOGLE_CHAT_ALLOWED_USERS=<EMAIL_ALLOWED>

GOOGLE_CHAT_MAX_MESSAGES=1

Trong đó:

• GOOGLE_CHAT_PROJECT_ID: ID project Google Cloud.
• GOOGLE_CHAT_SUBSCRIPTION_NAME: tên đầy đủ của Pull Subscription.
• GOOGLE_CHAT_SERVICE_ACCOUNT_JSON: đường dẫn file JSON service account trên server.
• GOOGLE_CHAT_ALLOWED_USERS: email được phép tương tác với bot.
• GOOGLE_CHAT_MAX_MESSAGES: số lượng message Hermes xử lý mỗi lần pull.

Ví dụ:

GOOGLE_CHAT_PROJECT_ID=dulcet-legend-499603-h9

GOOGLE_CHAT_SUBSCRIPTION_NAME=projects/dulcet-legend-499603-h9/subscriptions/hermes-chat-events-subscription

GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=/root/.hermes/google-chat-sa.json

GOOGLE_CHAT_ALLOWED_USERS=huynhdongtung.74119@gmail.com

GOOGLE_CHAT_MAX_MESSAGES=1

Nếu có nhiều allowed user, hãy kiểm tra định dạng mà Hermes hỗ trợ trước khi thêm nhiều email.

Nhấn Esc để thoát chế độ nhập.

Gõ:

:wq

Nhấn Enter để lưu và thoát.

Bước 11: Cài dependency cho Google Chat

Tiếp theo, cài các thư viện Python cần thiết để Hermes làm việc với Google Chat và Pub/Sub.

Chạy lệnh sau trên server:

/root/.local/bin/uv pip install --python /opt/hermes/hermes-agent/.venv/bin/python google-cloud-pubsub google-api-python-client google-auth google-auth-oauthlib google-auth-httplib2

Các dependency này giúp Hermes Gateway:

• Kết nối Cloud Pub/Sub.
• Xác thực bằng Service Account.
• Gọi Google Chat REST API.
• Xử lý các thư viện auth cần thiết của Google.

Bước 12: Bật plugin Google Chat Platform

Sau khi cài dependency, bật plugin Google Chat cho Hermes:

hermes plugins enable google_chat-platform

Nếu lệnh chạy thành công, plugin Google Chat Platform sẽ được bật trong Hermes.

Bước 13: Restart Hermes Gateway

Sau khi cập nhật .env hoặc bật plugin, bạn cần restart Hermes Gateway để cấu hình mới có hiệu lực.

Tùy cách cài đặt Hermes, lệnh restart có thể khác nhau. Nếu Hermes chạy bằng service, bạn có thể dùng lệnh tương ứng với service của hệ thống. Ví dụ:

systemctl restart hermes-gateway

Bước 14: Test bot trong Google Chat

Sau khi Gateway đã connected, bạn cần kiểm tra bot trong Google Chat.

Truy cập: https://chat.google.com/

Sau đó thực hiện:

1. Bấm Cuộc trò chuyện mới.
2. Gõ trực tiếp: Hermes Agent vào ô Thêm 1 hoặc nhiều người.
3. Nếu bot hiện ra, bấm chọn bot để mở ứng dụng. Có thể được yêu cầu cài đặt.
4. Gửi tin nhắn test, ví dụ: Chào Bot
5. Chờ bot phản hồi.

Bạn nên thử gõ trực tiếp tên bot trong ô thêm người trước. Nếu không thấy bot, lúc đó mới dùng tùy chọn Tìm ứng dụng và tìm Hermes Agent.

Lưu ý: Không tìm bot này trong Google Workspace Marketplace nếu đây là private/test Chat App. App private/test không phải app public Marketplace nên có thể không xuất hiện ở Marketplace.

Bước 15: Kiểm tra nếu bot không phản hồi

Nếu bot đã hiện trong Google Chat nhưng không phản hồi, hãy kiểm tra lại các điểm sau:

• Topic name trong Google Chat App có đúng không.
• Google Chat đã được cấp quyền Pub/Sub Publisher trên Topic chưa.
• Service account chat-api-push@system.gserviceaccount.com đã có quyền Pub/Sub Publisher chưa.
• Nếu UI Google Chat hiển thị service account dạng service-…@gcp-sa-gsuiteaddons.iam.gserviceaccount.com, email này đã được cấp Pub/Sub Publisher chưa.
• Hermes Service Account đã có quyền Pub/Sub Subscriber và Pub/Sub Viewer trên Subscription chưa.
• File service account JSON đã nằm đúng tại /root/.hermes/google-chat-sa.json chưa.
• File JSON đã được chmod 600 chưa.
• Dependency đã cài đầy đủ chưa.
• Plugin google_chat-platform đã bật chưa.
• Gateway đã restart sau khi đổi .env chưa.

Phần lớn lỗi bot không phản hồi thường đến từ sai Topic Name hoặc thiếu quyền Pub/Sub Publisher cho Google Chat.

Các bài viết liên quan:

• Hướng dẫn kết nối Google Workspace với Hermes Agent 
• Hướng dẫn kết nối Telegram với Hermes Agent trên VPS Hermes của Tino
• Hướng dẫn kết nối tài khoản Zalo cá nhân với Hermes Agent trên VPS Hermes của Tino
• Hướng dẫn kết nối Discord với Hermes Agent trên VPS Hermes của Tino
• VPS Hermes Agent là gì? 
• Cấu hình tối thiểu để chạy Hermes Agent
• Mua VPS Hermes Agent ở đâu uy tín?
• Có nên mua VPS cài sẵn Hermes Agent?

Kết luận

Kết nối Google Chat với Hermes Agent là một cách triển khai hiệu quả nếu bạn muốn biến Google Chat thành kênh giao tiếp trực tiếp với AI Agent. Nhìn chung, khi được cấu hình đúng, Google Chat sẽ trở thành một kênh nhắn tin tiện lợi, ổn định và phù hợp để tích hợp Hermes Agent vào môi trường làm việc hằng ngày của cá nhân, đội nhóm hoặc doanh nghiệp.

Những câu hỏi thường gặp