Microsoft Teams から使う

Microsoft Teams から使う

対象環境: Microsoft Teams 連携は オンプレミス導入向け です。iknow.dev（SaaS）では Teams 連携は利用できません。

iknow.dev のエージェントを Microsoft Teams のチャットから 利用できるようにする方法です。Teams ユーザーは Teams を抜けずに iknow.dev のエージェントに質問でき、回答もそのまま Teams 上に返ります（Web チャットと同様、ナレッジに基づく回答です）。

社内で Teams 連携が すでに構築済み の一般ユーザーは、「Teams 上での使い方」だけ読めば十分です。初めて組織に導入する 管理者 は「全体の流れ」から順に進めてください。

この機能でできること

Web チャットとの違い

Teams 経由の会話はプライバシー保護のため、iknow.dev の Web チャットアプリのサイドバー一覧には表示されません。

Teams 上での使い方（一般ユーザー向け）

セットアップが完了していれば、次の手順で利用できます。

1. Teams で iknow ボットを追加する — 管理者が配布した Teams アプリ（マニフェストで設定したアプリ名）を検索し、追加します。
2. 質問を送る — 1:1 チャットまたはチームのチャネルでボットにメッセージを送信します。
3. 回答を確認する — iknow.dev のエージェントがナレッジに基づいて回答し、Teams 上のメッセージとして表示されます。

Teams で初めて発言したユーザーが iknow.dev 上にまだアカウントを持っていない場合、Teams の Entra ID 情報をキーに 自動でアカウントが作成 されます。

全体の流れ（管理者向け・5 ステップ）

flowchart TD
  S1["1. Microsoft Entra ID でアプリを登録する"] --> S2["2. iknow.dev でボットシークレットを発行する"]
  S2 --> S3["3. Teams Bot（Node.js）を設定・起動する"]
  S3 --> S4["4. Azure Bot の Messaging Endpoint を設定する"]
  S4 --> S5["5. Teams アプリ（manifest）を作成・サイドロードする"]

概要と前提

Step 1: Microsoft Entra ID でアプリを登録する

1. Microsoft Entra 管理センター にサインインします。
2. 「アプリの登録」→「新規登録」で必要項目を入力して登録します。
3. 次の値を控えます。

4. 「証明書とシークレット」からクライアントシークレットを作成し、値を控えます → MicrosoftAppPassword。

Step 2: iknow.dev でボットシークレットを発行する

対象エージェントごとに、運営用 Blocs 管理画面（/admin/agent/{agentId}/edit）の「Microsoft Teams ボット」カードから Teams ボットシークレット を発行します。発行された平文は 再表示不可 のため、即コピーして IKNOW_TEAMS_BOT_SECRET（または複数モードの secret）に設定します。

エージェント一覧では発行できません。 手順の詳細は「エージェントごとの Teams ボット資格情報」（No.6.5）。エージェントコードの確認は「エージェント一覧」（No.3.1）。

Step 3: Teams Bot（Node.js）を設定・起動する

Teams Bot は iknow.dev のリポジトリに同梱されている teams-bot/ ディレクトリで動かします。

環境変数（単一エージェントモード）

teams-bot/.env に次の変数を設定します。

起動

cd teams-bot
cp .env.example .env
# .env を編集
npm install
npm start

Messaging Endpoint のデフォルトは 単一エージェントモード では http://localhost:3978/api/messages です。複数エージェントモード では /api/messages は登録されず、エージェントごとに /{agentCode}/api/messages（例: http://localhost:3978/sales-bot/api/messages）が公開されます。

ローカル開発時: ngrok などを使って HTTPS の公開 URL を払い出してください。末尾は単一エージェントモードなら /api/messages、複数エージェントモードなら /{agentCode}/api/messages にします。

Step 4: Azure Bot の Messaging Endpoint を設定する

対象: 単一エージェントモードの手順です。複数エージェントを 1 プロセスで運用する場合は後述の「複数エージェントを連携する場合」へ進んでください。

1. Azure ポータルで対象の Bot Channels Registration を開きます。
2. 「Configuration」の Messaging endpoint に以下を設定します。

https://<公開URL>/api/messages

Step 5: Teams アプリの manifest を作成・サイドロード

1. teams-bot/manifest/manifest.template.json をコピーして manifest.json を作ります。
2. プレースホルダー {{BOT_APP_ID}}（Application client ID）と {{TEAMS_APP_MANIFEST_ID}}（新規 GUID）を置換します。
3. validDomains に Bot の公開ホスト名（Messaging Endpoint のホスト。例: bot.example.com）を追加します。manifest.template.json の既定は空配列のため、必ずここに追記してください（Teams の検証でエラーになります）。
4. color.png と outline.png を teams-bot/manifest/ に配置します。
5. manifest.json / color.png / outline.png の 3 ファイルを zip のルート直下 に入れて圧縮します（ディレクトリで包まないように注意）。
6. Teams クライアントまたは Developer Portal から zip をアップロードします。

複数エージェントを Teams 連携する場合

1 つの Bot プロセスで複数のエージェントを同時に運用できます。エージェントごとに URL パスが分かれるため、エージェント追加時にリバースプロキシの設定変更は不要です。

エージェントごとに必要なリソース

環境変数（複数エージェントモード）

teams-bot/.env に IKNOW_TEAMS_AGENTS を JSON 配列で設定します。

IKNOW_TEAMS_API_URL=https://iknow.dev
MicrosoftAppTenantId=<共通テナントID>
IKNOW_TEAMS_AGENTS=[{"code":"agent-a","appId":"<A の AppId>","appPassword":"<A の Password>","secret":"<A のボットシークレット>"},{"code":"agent-b","appId":"<B の AppId>","appPassword":"<B の Password>","secret":"<B のボットシークレット>"}]

エージェントを追加するには配列にエントリを足してプロセスを再起動するだけです。

Azure Bot の Messaging Endpoint（複数エージェント）

各 Azure Bot の Messaging Endpoint を エージェントコード入りの URL で設定します。

https://<公開URL>/<エージェントコード>/api/messages

例:

• エージェント A (agent-a): https://bot.example.com/agent-a/api/messages
• エージェント B (agent-b): https://bot.example.com/agent-b/api/messages

Teams アプリ manifest（複数エージェント）

エージェントごとに manifest を作成し、name.short をエージェント名に合わせるとユーザーがアプリを区別しやすくなります（例:「iknow - 営業アシスタント」「iknow - 技術サポート」）。

起動確認

起動コマンドは単一エージェントモードと同じです。起動時のログで登録されたエージェント数を確認できます。

iknow Teams bot listening on 3978 [複数エージェントモード (2 agents)]

IKNOW_TEAMS_AGENTS が未設定の場合は、従来の環境変数（MicrosoftAppId / MicrosoftAppPassword / IKNOW_TEAMS_AGENT_CODE / IKNOW_TEAMS_BOT_SECRET）を使った単一エージェントモードで動作します。既存設定は変更不要です。

ユーザー識別の仕組み

困ったとき