Microsoft Teams の設定

Hermes Agent を Microsoft Teams のボットとしてつなぎます。Slack の Socket Mode とは違い、Teams は公開された HTTPS の webhook を呼び出す形でメッセージを届けます。そのため、外部から到達できるエンドポイントが必要です。手元で試すなら開発用トンネル、本番なら実際のドメインを用意します。

ふつうのボット会話ではなく、Microsoft Graph のイベントから会議の要約を受け取りたい場合は、専用の設定ページを見てください: Teams Meetings。

> hermes gateway setup を実行して Microsoft Teams を選ぶと、手順を案内してもらえます。

ボットが応答する条件

Teams は @メンションを <at>BotName</at> タグ付きの通常メッセージとして届けます。Hermes は処理の前にこのタグを自動で取り除きます。

ソースから入れる場合やローカルにインストールする場合は、同梱のアダプターを使えるように Teams の extra を入れてください。

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（TEAMS_ALLOWED_USERS に必要です）の確認は次のコマンドで行います。

teams status --verbose

ステップ 2: webhook のポートを公開する

Teams は localhost にメッセージを届けられません。手元で開発するときは、好きなトンネルツールで公開 HTTPS URL を用意します。既定のポートは 3978 で、変えたい場合は TEAMS_PORT で指定します。

# devtunnel (Microsoft)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol http  # 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:// の URL をコピーします。次のステップで使います。開発中はトンネルを起動したままにしてください。

公開トンネルの URL は HTTPS ですが、Hermes 側で webhook を待ち受けるのはプレーンな HTTP です。TLS はトンネルで終端され、HTTP としてポート 3978 に転送されます。ローカル側のトンネルポートを 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: ゲートウェイを起動する

Docker の場合（docker-compose.yml があるディレクトリで実行してください。ふつうは ~ ではなく、クローンした hermes-agent のリポジトリです）:

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

ネイティブ / systemd インストール の場合（hermes のワンライナーインストーラーで ~/.hermes/hermes-agent に入れた形）:

hermes gateway restart
# or foreground: hermes gateway run

Teams SDK は任意です。Teams を有効にしておくと、初回起動時にゲートウェイが Hermes 専用の venv へ遅延インストールします（Ubuntu 24.04 でシステムの pip install を使うのは避けてください。PEP 668 の externally-managed-environment に引っかかります）。手動で Hermes の venv に入れるには次のようにします。

~/.hermes/hermes-agent/venv/bin/pip install microsoft-teams-apps aiohttp
# or from a clone of the agent: uv sync --extra teams

webhook の既定ポートは 3978 です（TEAMS_PORT で変更できます）。動いているかどうかは次で確認します。

curl http://localhost:3978/health   # should return: ok
# Docker:
docker logs -f hermes
# Native:
hermes gateway status -l

次の行が出ていれば大丈夫です。

[teams] Webhook server listening on * (all interfaces, IPv4+IPv6):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 と打たせる代わりに、4 つのボタンを持つアダプティブカードを送ります。

• Allow Once — このコマンドだけを承認します
• Allow Session — このセッションの間、同じパターンを承認します
• Always Allow — このパターンを恒久的に承認します
• Deny — コマンドを却下します

ボタンを押すとその場で承認が決まり、カードは決定の内容に置き換わります。

会議要約の配信（Teams 会議パイプライン）

Teams 会議パイプラインのプラグインを有効にすると、このアダプターが会議要約の送信も担当します。Teams との接点は 2 つに分かれず、1 つのままです。会議の文字起こしが要約されたあと、書き出し側が指定の 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 の受け口に結びついたときだけ効いてきます。

本番環境へのデプロイ

常時稼働のサーバーでは、TLS をリバースプロキシで終端し、プレーンな HTTP で待ち受ける Hermes（通常は http://127.0.0.1:3978）へ転送します。プロキシ側の公開 HTTPS エンドポイントを Teams に登録してください。

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

すでにボットを作ってあって、エンドポイントだけ更新したい場合は次のようにします。

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

公開 HTTPS エンドポイントがインターネットから到達でき、有効な TLS 証明書を使っていることを確かめてください。Teams は自己署名証明書を受け付けません。Hermes 側はプロキシの後ろに置いたままにします。ポート 3978 自身は HTTPS を話しません。

困ったときは

セキュリティ

• 認証情報は権限 600 の ~/.hermes/.env に置きます（chmod 600 ~/.hermes/.env）
• ボットが受け付けるのは TEAMS_ALLOWED_USERS にいる人からのメッセージだけで、それ以外は黙って捨てられます
• 公開エンドポイント（/api/messages）は Teams Bot Framework によって認証され、正しい JWT のないリクエストは拒否されます

関連ドキュメント

• Teams Meetings
• Teams 会議パイプラインの運用