Chuyển tới nội dung chính

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: Teams Meetings.

Cách Bot phản hồi​

Bối cảnhHành vi
Trò chuyện cá nhân (DM)Bot trả lời mọi tin nhắn. Không cần @mention.
Trò chuyện nhómBot chỉ phản hồi khi được @đề cập.
KênhBot chỉ phản hồi khi được @đề cập.

Các nhóm gửi @đề cập dưới dạng tin nhắn thông thường với thẻ

<atBotName</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

):

`bash
teams status --verbose

`

---

## Bước 2: Hiện cổng Webhook

Các nhóm không thể gửi tin nhắn đến 
`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.

`bash

# 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

# cloudflared
cloudflared tunnel --url http://localhost:3978  # replace 3978 with TEAMS_PORT if changed

`
``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, thay vào đó, hãy trỏ điểm cuối của bot vào miền công cộng của máy chủ (xem [Production Deployment](#production-deployment)).

---

## Bước 3: Tạo Bot

``` bash
teams app create \

  --name "Hermes" \
  --endpoint "https://&lt;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

:

``` bash

# Required
TEAMS_CLIENT_ID=&lt;your-CLIent-id>
TEAMS_CLIENT_SECRET=&lt;your-CLIent-secret>
TEAMS_TENANT_ID=&lt;your-tenant-id>

# Restrict access to specific users (recommended)
# Use AAD object IDs from 
`teams status --verbose

TEAMS_ALLOWED_USERS=&lt;your-aad-object-id>

`

---

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

``` bash
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:

`bash
curl http://localhost:3978/health   # should return: ok
Docker logs -f Hermes

`
``Hãy tìm:

`

[teams] Webhook server listening on 0.0.0.0:3978/API/messages

`

---

## Bước 6: Cài đặt App trong Teams

`bash
teams app get &lt;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

| Biến | Mô tả |
|----------|-------------|
| 
`TEAMS_CLIENT_ID
` | ID ứng dụng Azure AD (ứng dụng khách) |
| 
`TEAMS_CLIENT_SECRET
` | Bí mật khách hàng Azure AD |
| 
`TEAMS_TENANT_ID
` | ID đối tượng thuê Azure AD |
| 
`TEAMS_ALLOWED_USERS
` | ID đối tượng AAD được phân tách bằng dấu phẩy được phép sử dụng bot |
| 
`TEAMS_ALLOW_ALL_USERS
` | Đặt 
`true
` để bỏ qua danh sách cho phép và cho phép mọi người |
| 
`TEAMS_HOME_CHANNEL
` | ID hội thoại để gửi tin nhắn cron/chủ động |
| 
`TEAMS_HOME_CHANNEL_NAME
` | Tên hiển thị cho kênh chủ |
| 
`TEAMS_PORT
` | Cổng Webhook (mặc định: 
`3978

) |

### config.yaml

Ngoài ra, hãy định cấu hình qua 

~/.Hermes/config.yaml

:

`YAML
platforms:
  teams:
    enabled: true
    extra:
      CLIent_id: "your-CLIent-id"
      CLIent_secret: "your-secret"
      tenant_id: "your-tenant-id"
      port: 3978

`

---

## Tính nă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 

/approve

:
- **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 bật [Teams meeting pipeline plugin](/docs/user-guide/messaging/msgraph-webhook), 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:

``` yaml
platforms:
  teams:
    enabled: true
    extra:

      # existing bot config (CLIent_id, CLIent_secret, tenant_id, port) ...

# Meeting summary delivery (only used when the teams_pipeline plugin is enabled)
      delivery_mode: "graph"       # or "incoming_webhook"
      # For delivery_mode: graph — pick ONE of:
      chat_id: "19:meeting_..."    # post into a Teams chat
      # team_id: "..."             # OR post into a channel
      # channel_id: "..."
      # access_token: "..."        # optional; falls back to MSGRAPH_* app credentials
      # For delivery_mode: incoming_webhook:
      # incoming_webhook_url: "https://outlook.office.com/webhook/..."

`

| Chế độ | Sử dụng khi | Đánh đổi |
|------|----------|----------|
| 
`incoming_webhook
` | Đơn giản là "đăng bản tóm tắt lên kênh này" bằng URL tĩnh do Nhóm tạo. | Không có chuỗi trả lời, không có phản hồi, hiển thị dưới dạng danh tính được định cấu hình của webhook. |
| 
`graph
` | Các bài đăng trên kênh theo chuỗi hoặc các bài đăng trò chuyện 1:1/nhóm dưới danh tính của bot thông qua Microsoft Graph. | Yêu cầu [Graph app registration](/docs/guides/Microsoft-graph-app-registration) có quyền ứng dụng 
`ChannelMessage.Send
` (kênh) hoặc 
`Chat.ReadWrite.All
` (trò chuyện). |

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:

``` bash
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:

``` bash
teams app update --id &lt;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

, 
`3978
` mặc định) 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ố

| Vấn đề | Giải pháp |
|----------|----------|
| Điểm cuối 
`health
` hoạt động nhưng bot không phản hồi | Kiểm tra xem đường hầm của bạn vẫn đang chạy và điểm cuối nhắn tin của bot khớp với URL đường hầm |
| 
`KeyError: 'teams'
` trong nhật ký | Khởi động lại vùng chứa — lỗi này đã được sửa trong phiên bản hiện tại |
| Bot phản hồi với lỗi xác thực | Xác minh 
`TEAMS_CLIENT_ID

, 
`TEAMS_CLIENT_SECRET
` và 
`TEAMS_TENANT_ID
` đều được đặt chính xác |
| 
`No inference provider configured
` | Kiểm tra xem 
`Anthropic_API_KEY
` (hoặc khóa nhà cung cấp khác) có được đặt trong 

~/.Hermes/.env
` |
| Bot nhận được tin nhắn nhưng bỏ qua chúng | ID đối tượng AAD của bạn có thể không có trong 
`TEAMS_ALLOWED_USERS

. Chạy 
`teams status --verbose
` để tìm nó |
| Thay đổi URL đường hầm khi khởi động lại | URL devtunnel sẽ liên tục nếu bạn sử dụng đường hầm có tên (
`devtunnel create Hermes-bot

). ngrok và cloudflared tạo một URL mới mỗi lần chạy trừ khi bạn có gói trả phí - cập nhật điểm cuối bot với 
`teams app update
` khi nó thay đổi |
| Teams hiển thị "Bot này không phản hồi" | Webhook trả về lỗi. Kiểm tra 
`Docker logs Hermes
` để tìm dấu vết |
| 

[teams] Failed to connect
` trong nhật ký | SDK không thể xác thực. Kiểm tra kỹ thông tin đăng nhập của bạn và ID đối tượng thuê có khớp với tài khoản bạn đã sử dụng trong 
`teams login
` |

---

## Bảo mật

:::warning

**Luôn đặt 
`TEAMS_ALLOWED_USERS

** với 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ó.

Hãy coi 
`TEAMS_CLIENT_SECRET
` như một 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/.env
` với quyền 
`600
` (
`chmod 600 ~/.Hermes/.env

)
- Bot chỉ 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

## Tài liệu liên quan
- [Teams Meetings](/docs/user-guide/messaging/teams-meetings)
- [Operate the Teams Meeting pipeline](/docs/guides/operate-teams-meeting-pipeline)