Thiết lập nhóm Microsoft
Kết nối Đại lý Hermes với Microsoft Teams dưới dạng bot. Không giống như Chế độ ổ cắm của Slack, Teams gửi tin nhắn bằng cách gọi webhook HTTPS công khai, do đó, phiên bản của bạn cần một điểm cuối có thể truy cập công khai — đường hầm dành cho nhà phát triển (nhà phát triển cục bộ) hoặc miền thực (sản xuất).
Bạn cần tóm tắt cuộc họp từ các sự kiện Microsoft Graph thay vì các cuộc hội thoại thông thường với bot? Sử dụng trang thiết lập chuyên dụng: Cuộc họp nhóm.
Cách Bot phản hồi
| Context | Behavior |
|---|---|
| Personal chat (DM) | Bot responds to every message. No @mention needed. |
| Group chat | Bot only responds when @mentioned. |
| Channel | Bot only responds when @mentioned. |
Các nhóm gửi @mentions dưới dạng tin nhắn thông thường có thẻ <at>BotName</at> mà Hermes tự động loại bỏ trước khi xử lý.
Bước 1: Cài đặt Teams CLI
@microsoft/teams.cli tự động đăng ký bot — không cần cổng Azure.
npm install -g @microsoft/teams.cli@preview
teams login
Để xác minh thông tin đăng nhập của bạn và tìm ID đối tượng AAD của riêng bạn (cần thiết cho TEAMS_ALLOWED_USERS):
teams status --verbose
Bước 2: Hiện cổng Webhook
Các nhóm không thể gửi tin nhắn tới localhost. Để phát triển cục bộ, hãy sử dụng bất kỳ công cụ đường hầm nào để nhận URL HTTPS công khai. Cổng mặc định là 3978 — hãy thay đổi nó bằng TEAMS_PORT nếu cần.
# devtunnel (Microsoft)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol https # replace 3978 with TEAMS_PORT if changed
devtunnel host hermes-bot
# ngrok
ngrok http 3978 # replace 3978 with TEAMS_PORT if changed
# mây mù
đường hầm cloudflared --url http://localhost:3978 # thay thế 3978 bằng TEAMS_PORT nếu thay đổi
Sao chép URL https:// từ đầu ra — bạn sẽ sử dụng nó trong bước tiếp theo. Để đường hầm chạy trong khi phát triển.
Để sản xuất, hãy trỏ điểm cuối của bot vào miền công cộng của máy chủ (xem Triển khai sản xuất).
Bước 3: Tạo Bot
teams app create \
--name "Hermes" \
--endpoint "https://<your-tunnel-url>/api/messages"
CLI xuất ra CLIENT_ID, CLIENT_SECRET và TENANT_ID của bạn, cùng với liên kết cài đặt cho Bước 6. Lưu bí mật ứng dụng khách — nó sẽ không được hiển thị lại.
Bước 4: Cấu hình biến môi trường
Thêm vào ~/.hermes/.env:
# Required
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>
# Hạn chế quyền truy cập đối với người dùng cụ thể (được khuyến nghị)
# Sử dụng ID đối tượng AAD từ `trạng thái nhóm --verbose`
TEAM_ALLOWED_USERS=<your-aad-object-id>
Bước 5: Khởi động Gateway
HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d gateway
Điều này bắt đầu cổng. Cổng webhook mặc định là 3978 (ghi đè bằng TEAMS_PORT). Kiểm tra xem nó có đang chạy không:
curl http://localhost:3978/health # should return: ok
docker logs -f hermes
Hãy tìm:
[teams] Máy chủ Webhook đang lắng nghe trên 0.0.0.0:3978/api/messages
Bước 6: Cài đặt App trong Teams
teams app get <teamsAppId> --install-link
Mở liên kết đã in trong trình duyệt của bạn — liên kết này sẽ mở trực tiếp trong ứng dụng khách Teams. Sau khi cài đặt, hãy gửi tin nhắn trực tiếp tới bot của bạn — nó đã sẵn sàng.
Tham khảo cấu hình
Biến môi trường
| Variable | Description |
|---|---|
TEAMS_CLIENT_ID | Azure AD App (client) ID |
TEAMS_CLIENT_SECRET | Azure AD client secret |
TEAMS_TENANT_ID | Azure AD tenant ID |
TEAMS_ALLOWED_USERS | Comma-separated AAD object IDs allowed to use the bot |
TEAMS_ALLOW_ALL_USERS | Set true to skip the allowlist and allow anyone |
TEAMS_HOME_CHANNEL | Conversation ID for cron/proactive message delivery |
TEAMS_HOME_CHANNEL_NAME | Display name for the home channel |
TEAMS_PORT | Webhook port (default: 3978) |
config.yaml
Ngoài ra, hãy định cấu hình qua ~/.hermes/config.yaml:
platforms:
teams:
enabled: true
extra:
client_id: "your-client-id"
client_secret: "your-secret"
tenant_id: "your-tenant-id"
port: 3978
Đặc trưng
Thẻ phê duyệt tương tác
Khi tác nhân cần chạy một lệnh tiềm ẩn nguy hiểm, nó sẽ gửi Thẻ Thích ứng có bốn nút thay vì yêu cầu bạn nhập /phê duyệt:
- Cho phép một lần — phê duyệt lệnh cụ thể này
- Cho phép phiên — phê duyệt mẫu này cho phần còn lại của phiên
- Luôn cho phép — phê duyệt vĩnh viễn mẫu này
- Từ chối — từ chối lệnh
Việc bấm vào nút sẽ giải quyết phê duyệt nội tuyến và thay thế thẻ bằng quyết định.
Gửi bản tóm tắt cuộc họp (Đường dẫn cuộc họp nhóm)
Khi plugin đường dẫn cuộc họp Teams được bật, bộ điều hợp này cũng xử lý việc gửi đi các bản tóm tắt cuộc họp — một bề mặt tích hợp Teams chứ không phải hai. Sau khi bản ghi của cuộc họp được tóm tắt, người viết sẽ đăng bản tóm tắt vào mục tiêu Nhóm đã chọn của bạn.
Phân phối tóm tắt quy trình được định cấu hình trong mục nhập nền tảng teams cùng với cấu hình bot:
platforms:
teams:
enabled: true
extra:
# existing bot config (client_id, client_secret, tenant_id, port) ...
# Gửi bản tóm tắt cuộc họp (chỉ được sử dụng khi plugin Team_pipeline được bật)
Delivery_mode: "biểu đồ" # hoặc "incoming_webhook"
# Đối với Delivery_mode: đồ thị - chọn MỘT trong:
chat_id: "19:meeting_..." # đăng vào cuộc trò chuyện Nhóm
# team_id: "..." # HOẶC đăng lên kênh
# kênh_id: "..."
# access_token: "..." # tùy chọn; quay trở lại thông tin xác thực ứng dụng MSGRAPH_*
# Đối với Delivery_mode:coming_webhook:
# đến_webhook_url: "https://outlook.office.com/webhook/..."
| Mode | Use when | Trade-off |
|---|---|---|
incoming_webhook | Simple "post a summary into this channel" with a static Teams-generated URL. | No reply threading, no reactions, shows as the webhook's configured identity. |
graph | Threaded channel posts or 1:1/group chat posts under the bot's identity via Microsoft Graph. | Requires the Graph app registration with ChannelMessage.Send (channel) or Chat.ReadWrite.All (chat) application permissions. |
Nếu plugin teams_pipeline không được bật, thì các cài đặt này sẽ không hoạt động — chúng chỉ kết nối khi thời gian chạy quy trình liên kết với hoạt động xâm nhập vào Đồ thị webhook.
Triển khai sản xuất
Đối với máy chủ cố định, hãy bỏ qua devtunnel và đăng ký bot của bạn với điểm cuối HTTPS công khai trên máy chủ của bạn:
teams app create \
--name "Hermes" \
--endpoint "https://your-domain.com/api/messages"
Nếu bạn đã tạo bot và chỉ cần cập nhật điểm cuối:
teams app update --id <teamsAppId> --endpoint "https://your-domain.com/api/messages"
Đảm bảo cổng được định cấu hình của bạn (TEAMS_PORT, mặc định 3978) có thể truy cập được từ Internet và chứng chỉ TLS của bạn hợp lệ — Nhóm từ chối chứng chỉ tự ký.
Khắc phục sự cố
| Problem | Solution |
|---|---|
health endpoint works but bot doesn't respond | Check that your tunnel is still running and the bot's messaging endpoint matches the tunnel URL |
KeyError: 'teams' in logs | Restart the container — this is fixed in the current version |
| Bot responds with auth errors | Verify TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET, and TEAMS_TENANT_ID are all set correctly |
No inference provider configured | Check that ANTHROPIC_API_KEY (or another provider key) is set in ~/.hermes/.env |
| Bot receives messages but ignores them | Your AAD object ID may not be in TEAMS_ALLOWED_USERS. Run teams status --verbose to find it |
| Tunnel URL changes on restart | devtunnel URLs are persistent if you use a named tunnel (devtunnel create hermes-bot). ngrok and cloudflared generate a new URL each run unless you have a paid plan — update the bot endpoint with teams app update when it changes |
| Teams shows "This bot is not responding" | The webhook returned an error. Check docker logs hermes for tracebacks |
[teams] Failed to connect in logs | The SDK failed to authenticate. Double-check your credentials and that the tenant ID matches the account you used in teams login |
Bảo vệ
:::cảnh báo
Luôn đặt TEAMS_ALLOWED_USERS bằng ID đối tượng AAD của người dùng được ủy quyền. Nếu không có điều này, bất kỳ ai có thể tìm hoặc cài đặt bot của bạn đều có thể tương tác với nó.
Coi TEAMS_CLIENT_SECRET như mật khẩu — thay đổi mật khẩu định kỳ thông qua cổng Azure hoặc Teams CLI.
:::
- Lưu trữ thông tin xác thực trong
~/.hermes/.envvới quyền600(chmod 600 ~/.hermes/.env) - Bot chỉ chấp nhận tin nhắn từ người dùng trong
TEAMS_ALLOWED_USERS; tin nhắn trái phép được âm thầm loại bỏ - Điểm cuối công khai của bạn (
/api/messages) được xác thực bởi Teams Bot Framework — các yêu cầu không có JWT hợp lệ sẽ bị từ chối