メインコンテンツまでスキップ

Microsoft Teams 連携

ChatWalaʻau エージェントと Microsoft Teams から直接 会話できます -- 1:1 の個人チャット、 グループチャット、チャネル投稿に対応し、Teams の Bot チャット UI と Adaptive Card を使います。 これは最初の外部チャットチャネル連携です。Web アプリで使うのと同じエージェントが Teams でも 応答し、チャットロジックは分岐しません。

本機能は オプトイン で、既定では無効です。TEAMS_ENABLED=true と Bot のクレデンシャルで 有効化します。

できること​

  • 個人・グループ・チャネルでのチャット。 グループやチャネルでは Bot を @mention で 呼び出します。Bot 自身の mention はエージェントが読む前に除去されます。
  • 入力中インジケータ + プロアクティブ返信。 エージェントは（推論やツールで）時間が かかることがあります。Teams は処理中に入力中インジケータを表示し、その後に回答を投稿します。 長い回答は Teams のメッセージサイズ上限に収まるよう分割されます。
  • Adaptive Card によるツール承認。 承認が必要なツールをエージェントが実行しようとすると、 Allow Once / Allow Session / Deny のカードとラウンド数が表示されます。Teams が自動承認 することはありません。Allow Session はそのツールをスレッドの残りの間許可し、同じツールの 他の保留中カードもまとめて解決します。
  • アクセス制御。 Bot を使えるユーザーを特定の Microsoft Entra ID ユーザー（Object ID）に 限定できます。既定では Bot が届く範囲の全員が利用可能です。
  • 画像。 生成された画像は Teams の会話に届きます。

仕組み​

Microsoft Teams クラウドが、あなたのメッセージを HTTPS で ChatWalaʻau の Bot エンドポイントへ 配信します。

Microsoft Teams クラウド
  |
  |  POST https://<your-host>/api/teams/messages
  v
ChatWalaʻau（Bot Framework JWT を検証）--> エージェント実行 --> 返信

受信リクエストは Microsoft Bot Framework JWT（製品の API キーではない）で認証されます。 ChatWalaʻau はエージェント実行をバックグラウンドで行い、プロアクティブに返信するため、遅い 回答でも Teams 側がタイムアウトしません。各 Teams 会話は専用のチャットスレッドに対応します。

有効化​

マスタースイッチと Bot のクレデンシャル（Entra アプリ / Azure Bot 登録から取得）を設定します。

TEAMS_ENABLED=true
TEAMS_APP_ID=<client-id>
TEAMS_APP_PASSWORD=<client-secret>
TEAMS_TENANT_ID=<tenant-id>

任意設定:

# Bot を使える Entra ID Object ID のカンマ区切りリスト。空欄 = 全員。
TEAMS_ALLOWED_USERS=
# 受信パス（あなたのホストと組み合わせて Bot の messaging endpoint として登録）。
TEAMS_MESSAGING_ENDPOINT_PATH=/api/teams/messages
# 送信メッセージ 1 チャンクあたりの最大文字数（Teams サイズ上限ガード）。
TEAMS_MAX_REPLY_CHARS=25000

Teams SDK（microsoft-teams-apps）は標準依存として同梱されるため、追加のインストール手順は 不要です。TEAMS_ENABLED が無効のときは Teams エンドポイントはマウントされず、SDK も import されません -- ランタイムは変わりません。

ローカル開発にはトンネルが必要​

Microsoft Teams クラウドは localhost に到達できないため、ローカル開発では稼働中の ChatWalaʻau を公開 HTTPS トンネル経由で公開します。既定は Microsoft Dev Tunnel で、ngrok や cloudflared も使えます。Bot の messaging endpoint は https://<tunnel-host>/api/teams/messages になります。

セットアップ手順書​

リポジトリに 2 つのステップバイステップのオペレータ手順書があります。

  • トンネル設定（assets/docs/guides/teams-tunnel-setup.md）-- Microsoft Dev Tunnel （既定）/ ngrok / cloudflared で localhost:8000 を公開。
  • Bot 登録（assets/docs/guides/teams-bot-registration.md）-- Microsoft Teams CLI （または Entra / Azure ポータル）で Bot を登録し、クレデンシャルを取得し、messaging endpoint を 設定し、アプリを Teams にサイドロード。

注意点と制限​

  • グループやチャネルは 共有 スレッドです。許可された全員がそこで Bot と会話でき、アクセス チェックはメッセージごとに送信者単位で行われます。
  • 共有スレッドではユーザーごとのパーソナライズ記憶は適用されません（グループ/チャネルでの プライバシーのための意図的な挙動です）。
  • デモ環境では本連携は無効です（DEMO_MODE は TEAMS_ENABLED を無効のままにします）。