sidebar_position: 5 title: “Microsoft Teams” description: “Set up Hermes Agent as a Microsoft Teams bot”

Microsoft Teams 设置

需将 Hermes Agent 作为机器人连接到 Microsoft Teams。与 Slack 的 Socket 模式不同，Teams 通过调用公共 HTTPS webhook来传递消息，因此您的实例需要一个可公开访问的端点——可以是开发环境隧道（本地调试），也可以是真实域名（生产环境）。

如果需要从 Microsoft Graph 事件中获取会议摘要而非普通机器人对话内容，请使用专用设置页面：Teams 会议。

运行 hermes gateway setup 并选择 Microsoft Teams，即可获得引导式设置流程。

机器人的响应方式

Teams 会将 @提及以带有 <at>BotName</at> 标签的普通消息形式发送，Hermes 会在处理之前自动移除这些标签。

对于源码安装或本地安装版本，需包含 Teams 相关组件，以便捆绑的适配器能够导入 Microsoft Teams SDK：

uv sync --extra teams
# or, for editable installs:
uv pip install -e ".[teams]"

第1步：安装Teams CLI

@microsoft/teams.cli可自动完成机器人注册流程——无需使用Azure门户。

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

为验证您的登录身份并查询您自己的 AAD 对象 ID（该 ID 是设置 TEAMS_ALLOWED_USERS 所需的）：

teams status --verbose

第 2 步：开放 Webhook 端口

Teams 无法向 localhost 发送消息。在本地开发时，需使用任意隧道工具来获取一个公开的 HTTPS 地址。默认端口为 3978，如有需要可通过 TEAMS_PORT 参数进行修改。

# 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

从输出结果中复制 https:// 开头的网址——您将在下一步中使用它。在开发过程中请保持隧道处于运行状态。

对于生产环境，应将机器人的端点指向您服务器的公网域名（详见生产环境部署）。

第3步：创建机器人

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

CLI会输出您的CLIENT_ID、CLIENT_SECRET和TENANT_ID，同时还会提供第6步的安装链接。请务必保存好客户端密钥，因为它不会再显示一次。

第4步：配置环境变量

在~/.hermes/.env文件中添加以下内容：

# Required
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>

# Restrict access to specific users (recommended)
# Use AAD object IDs from `teams status --verbose`
TEAMS_ALLOWED_USERS=<your-aad-object-id>

第 5 步：启动网关

HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d gateway

这将启动网关。默认的 Webhook 端口为 3978（可通过 TEAMS_PORT 参数进行覆盖）。请确认该服务正在运行：

curl http://localhost:3978/health   # should return: ok
docker logs -f hermes

请查找：

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

第 6 步：在 Teams 中安装该应用

teams app get <teamsAppId> --install-link

在浏览器中打开该打印出的链接——它将直接在 Teams 客户端中打开。安装完成后，向您的机器人发送私信即可，此时机器人已准备就绪。

配置参考

环境变量

config.yaml

或者，也可以通过 ~/.hermes/config.yaml 进行配置：

platforms:
  teams:
    enabled: true
    extra:
      client_id: "your-client-id"
      client_secret: "your-secret"
      tenant_id: "your-tenant-id"
      port: 3978

功能特性

交互式审批卡片

当智能体需要执行可能具有危险性的命令时，它会发送一张包含四个按钮的自适应卡片，而无需让用户输入 /approve 命令：

• 允许一次 — 仅批准当前该命令
• 允许本次会话 — 批准本次会话中该类型的命令
• 始终允许 — 永久批准该类型的命令
• 拒绝 — 拒绝执行该命令

点击任意按钮即可立即完成审批，并用审批结果替换原有卡片。

会议摘要发送（Teams 会议流程）

当启用 Teams 会议流程插件 后，该适配器可统一处理会议摘要的发送工作——仅需一个 Teams 集成接口，而非两个。在会议记录被汇总后，系统会自动将摘要发布到您指定的 Teams 目标地址。

会议摘要发送功能可在 teams 平台配置项下与机器人配置一同设置：

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/..."

如果未启用 teams_pipeline 插件，这些设置将处于无效状态——只有当管道运行时绑定到 Graph webhook 入口时，它们才会被激活。

生产环境部署

对于永久运行的服务器，请跳过 devtunnel，将您的机器人注册到服务器的公共 HTTPS 端点上：

teams app create \
  --name "Hermes" \
  --endpoint "https://your-domain.com/api/messages"

如果您已经创建了该机器人，仅需更新端点地址即可：

teams app update --id <teamsAppId> --endpoint "https://your-domain.com/api/messages"

请确保您配置的端口（TEAMS_PORT，默认值为 3978）可从互联网访问，同时您的 TLS 证书也必须有效——Teams 不支持自签名证书。

故障排除

安全性

:::warning 务必设置 TEAMS_ALLOWED_USERS，并填入经授权用户的 AAD 对象 ID。如果不这样做，任何找到或安装了您机器人的用户都可能与其交互。

请将 TEAMS_CLIENT_SECRET 视为密码——建议通过 Azure 门户或 Teams CLI 定期更换它。

::

• 将凭证存储在 ~/.hermes/.env 文件中，并设置 600 权限（执行 chmod 600 ~/.hermes/.env）
• 机器人仅接受来自 TEAMS_ALLOWED_USERS 中用户的消息；未经授权的消息将被直接忽略
• 您的公共端点（/api/messages）由 Teams Bot Framework 进行身份验证——缺少有效 JWT 的请求将被拒绝

相关文档

• Teams 会议功能
• 操作 Teams 会议流程