Microsoft Teams — Trò chuyện Doanh nghiệp

Hãy nghĩ về việc kết nối Hermes Agent với Microsoft Teams giống như việc cấp cho trợ lý AI của bạn một thẻ nhân viên công ty — một khi đã vào đội, nó có thể tham gia cuộc họp, trả lời câu hỏi trong kênh, và hỗ trợ trong tin nhắn riêng, tất cả mà không cần rời khỏi ứng dụng mà đồng nghiệp của bạn vẫn dùng hàng ngày.

Vì Sao Teams Khác Với Slack

Nếu bạn đã từng dùng Socket Mode của Slack, thì Teams hoạt động hơi khác một chút. Thay vì giữ một kết nối mở, Teams sẽ gọi đến webhook công khai của bot mỗi khi ai đó gửi tin nhắn. Điều đó có nghĩa là phiên bản Hermes của bạn cần một URL HTTPS công khai — không phải localhost. Để thử nghiệm, bạn có thể dùng tunnel; còn trong sản xuất, bạn sẽ trỏ nó tới tên miền máy chủ thật của mình.

Bot Hoạt Động Như Thế Nào

Đây là quy tắc đơn giản để nhớ:

Nơi bạn trò chuyện với nó	Điều gì xảy ra
Trò chuyện riêng tư (DM)	Bot trả lời mọi tin nhắn — không cần @đề cập
Trò chuyện nhóm	Bot chỉ trả lời khi bạn @đề cập nó
Kênh	Bot chỉ trả lời khi bạn @đề cập nó

Teams gửi @đề cập dưới dạng thẻ <at>BotName</at>, nhưng Hermes tự động loại bỏ chúng trước khi xử lý — vì vậy bạn không cần phải lo lắng về điều đó.

Bước 1: Cài Đặt Teams CLI

Đầu tiên, hãy cài đặt công cụ dòng lệnh của Microsoft để tự động hóa việc đăng ký bot — không cần cổng Azure:

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

Để xác minh đăng nhập và tìm ID đối tượng AAD của bạn (bạn sẽ cần nó sau này để giới hạn quyền truy cập), hãy chạy:

teams status --verbose

Bước 2: Mở Cổng Webhook

Teams không thể gửi tin nhắn đến localhost. Đối với phát triển cục bộ, hãy sử dụng tunnel để có một URL HTTPS công khai. Cổng mặc định là 3978 (đổi nó bằng TEAMS_PORT nếu cần).

Dưới đây là ba lựa chọn dễ dàng:

# 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

Sao chép URL https:// từ kết quả đầu ra — bạn sẽ cần nó trong bước tiếp theo. Để tunnel chạy trong khi bạn phát triển.

Bước 3: Tạo Bot

Bây giờ hãy đăng ký bot của bạn với Teams:

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

CLI sẽ xuất ra CLIENT_ID, CLIENT_SECRET, và TENANT_ID của bạn, cùng với một liên kết cài đặt. Hãy lưu client secret ngay lập tức — nó sẽ không được hiển thị lại nữa.

Bước 4: Cấu Hình Biến Môi Trường

Thêm những dòng này vào tệp ~/.hermes/.env của bạn:

# Bắt buộc
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>

# Giới hạn quyền truy cập cho người dùng cụ thể (khuyến nghị)
# Sử dụng ID đối tượng AAD từ `teams status --verbose`
TEAMS_ALLOWED_USERS=<your-aad-object-id>

Bước 5: Khởi Động Gateway

Nếu bạn dùng Docker, hãy chạy từ thư mục chứa docker-compose.yml (thường là kho lưu trữ hermes-agent bạn đã clone, không phải ~):

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

Đối với cài đặt từ mã nguồn, hãy đảm bảo bạn bao gồm phần bổ sung Teams trước:

uv sync --extra teams
# hoặc, cho cài đặt có thể chỉnh sửa:
uv pip install -e ".[teams]"

Tổng Kết

Kết nối Hermes với Teams là một vũ điệu bốn bước: cài đặt CLI, mở URL công khai, tạo bot, và thiết lập các biến môi trường của bạn. Khi nó đã chạy, trợ lý AI của bạn trở thành một thành viên chính thức của đội — tự động trả lời trong DM và tham gia các cuộc trò chuyện nhóm khi được gọi.

Mẹo thực tế: Bắt đầu với TEAMS_ALLOWED_USERS chỉ được đặt thành ID đối tượng AAD của riêng bạn. Bằng cách đó, bạn có thể kiểm tra an toàn mà không lo đồng nghiệp ngẫu nhiên kích hoạt bot của bạn — sau đó mở rộng quyền truy cập khi bạn tự tin mọi thứ hoạt động tốt.