# EMQX Agents を Microsoft Teams に接続する

Microsoft Teams コネクターを使用すると、EMQX Agents はチャット、チーム、チャネル、メッセージ、オンライン会議、ユーザープロファイル、シフトと連携できます。コラボレーション、インシデント連絡、会議作成、運用フォローアップに活用してください。

## よくあるユースケース

- エージェントがインシデントを検知した後、Teams チャネルにアラートを送信する。
- 関連する運用コンテキストをチャットやチャネルで検索する。
- インシデント対応者向けにオンライン会議を作成する。
- 最近のチャネルメッセージやシフト記録を要約する。

チャットの例文：

```text
エージェントが重大なアラートを確認した際に、operations-teams コネクターを使って Device Operations チャネルにメッセージを投稿してください。デバイスIDとインシデントの概要を含めてください。
```

## 前提条件

コネクターを追加する前に、以下を準備してください。

- Microsoft Teams へのアクセス権を持つ Microsoft アカウント
- 必要なチャット、チーム、チャネル、メッセージ、会議、プロファイル、シフト操作を認可する権限
- ワークフローで必要なチーム、チャネル、チャットのメンバーシップ

## Microsoft Teams コネクターを追加する

1. 左側のナビゲーションメニューで **Connectors** をクリックします。
2. **Available** タブで **Teams** を見つけて **Add** をクリックします。
3. 説明的なコネクター名を入力します。
4. **Confirm** をクリックします。Microsoft の認証フローがダイアログで開きます。
5. 接続する Microsoft アカウントを選択するか、**Use another account** を選択します。
6. 認証ダイアログが閉じて EMQX Agents に戻るまで待ちます。
7. **Added** タブでコネクターのステータスが **Authorized** になっていることを確認します。

<!-- TODO: Microsoft OAuth スコープ、テナント同意要件、メッセージID、プライベートチャネル対応を確認する。 -->

## 対応ツール

### チャット

| ツール | アクセス | 説明 |
|---|---|---|
| `MICROSOFT_TEAMS_CHATS_GET_ALL_CHATS` | 読み取り | ユーザーに関連するチャットの一覧を取得します。 |
| `MICROSOFT_TEAMS_GET_CHAT` | 読み取り | チャットの詳細を取得します。 |
| `MICROSOFT_TEAMS_GET_USER_CHAT` | 読み取り | 選択したユーザーのチャットを取得します。 |

### オンライン会議

| ツール | アクセス | 説明 |
|---|---|---|
| `MICROSOFT_TEAMS_CREATE_MEETING` | 書き込み | 独立したオンライン会議を作成します。 |
| `MICROSOFT_TEAMS_CREATE_USER_ONLINE_MEETING` | 書き込み | 選択したユーザーのオンライン会議を作成します。 |
| `MICROSOFT_TEAMS_GET_ONLINE_MEETING` | 読み取り | オンライン会議の詳細を取得します。 |

### チームとチャネル

| ツール | アクセス | 説明 |
|---|---|---|
| `MICROSOFT_TEAMS_GET_CHANNEL` | 読み取り | チャネルの詳細を取得します。 |
| `MICROSOFT_TEAMS_GET_PRIMARY_CHANNEL` | 読み取り | チームのプライマリチャネルを取得します。 |
| `MICROSOFT_TEAMS_GET_TEAM_FROM_GROUP` | 読み取り | グループIDからチームを取得します。 |
| `MICROSOFT_TEAMS_LIST_ASSOCIATED_TEAMS` | 読み取り | ユーザーに関連するチームの一覧を取得します。 |
| `MICROSOFT_TEAMS_LIST_USER_JOINED_TEAMS` | 読み取り | ユーザーが参加しているチームの一覧を取得します。 |
| `MICROSOFT_TEAMS_TEAMS_LIST` | 読み取り | 認可されたユーザーが利用可能なチームの一覧を取得します。 |
| `MICROSOFT_TEAMS_TEAMS_LIST_CHANNELS` | 読み取り | チーム内のチャネル一覧を取得します。 |
| `MICROSOFT_TEAMS_CREATE_CHANNEL` | 書き込み | チーム内にチャネルを作成します。 |

### ユーザーとシフト

| ツール | アクセス | 説明 |
|---|---|---|
| `MICROSOFT_TEAMS_GET_MY_PROFILE` | 読み取り | 現在の Teams ユーザープロファイルを取得します。 |
| `MICROSOFT_TEAMS_LIST_SHIFTS` | 読み取り | Microsoft Teams シフトのシフト記録を一覧表示します。 |

### メッセージ

| ツール | アクセス | 説明 |
|---|---|---|
| `MICROSOFT_TEAMS_GET_CHANNEL_MESSAGE` | 読み取り | チャネルメッセージを取得します。 |
| `MICROSOFT_TEAMS_GET_CHAT_MESSAGE` | 読み取り | チャットメッセージを取得します。 |
| `MICROSOFT_TEAMS_LIST_MESSAGE_REPLIES` | 読み取り | チャネルメッセージへの返信一覧を取得します。 |
| `MICROSOFT_TEAMS_LIST_USER_CHAT_MESSAGES` | 読み取り | ユーザーのチャット内メッセージ一覧を取得します。 |
| `MICROSOFT_TEAMS_SEARCH_MESSAGES` | 読み取り | KQL を使用してチャットおよびチャネルメッセージを検索します。 |
| `MICROSOFT_TEAMS_TEAMS_LIST_CHANNEL_MESSAGES` | 読み取り | チャネル内のメッセージ一覧を取得します。 |
| `MICROSOFT_TEAMS_POST_MESSAGE_REPLY` | 書き込み | チャネルメッセージに返信します。 |
| `MICROSOFT_TEAMS_TEAMS_POST_CHANNEL_MESSAGE` | 書き込み | チャネルにトップレベルメッセージを投稿します。 |
| `MICROSOFT_TEAMS_TEAMS_POST_CHAT_MESSAGE` | 書き込み | チャットにメッセージを投稿します。 |

::: warning 重要なお知らせ
メッセージ送信、返信、チャネル作成、会議作成のツールはユーザーと通信したり Teams リソースを変更します。書き込み操作を行う前に、対象のチーム、チャネル、チャット、参加者を必ず確認してください。
:::

## チャットでコネクターを使う

1. チャット入力欄でコネクターアイコンをクリックします。
2. 認可済みの **Teams** コネクターを選択します。
3. プロンプトで、エージェントが使用すべき外部リソースと操作を指定します。
4. 生成されたエージェント定義を確認し、必要なツールのみが含まれていることを確認します。

## 権限とデータアクセス

コネクターは認可された Microsoft アカウントを使用します。Microsoft 365 テナントポリシー、チームおよびチャネルのメンバーシップ、チャットアクセス、管理者の同意により利用可能なリソースや操作が決まります。

チャットプロンプトやエージェントの指示に外部サービスの認証情報やアクセストークンを含めないでください。

## 制限事項

- Microsoft Graph API のクォータおよびテナントポリシーが適用されます。
- プライベートまたは共有チャネルへのアクセスはメンバーシップとテナント設定に依存します。
- 会議、シフト、メッセージ機能は追加の Microsoft 365 権限が必要な場合があります。

<!-- TODO: サービス固有の結果サイズ制限、ファイル制限、API レート制限、プラン制限、非対応リソース種別を確認する。 -->

## トラブルシューティング

| 症状 | 対応策 |
|---|---|
| コネクターが **Unauthorized** のままになる。 | 認証を再試行し、意図した Microsoft アカウントを選択してください。 |
| ツールが権限エラーを返す。 | 認可されたアカウントが対象のチーム、チャネル、チャット、会議にアクセスできるか確認してください。必要に応じて Microsoft 365 テナントポリシーや管理者の同意も確認してください。 |
| 必要なツールが利用できない。 | ツールがこのコネクターでサポートされているか承認されているか確認し、チャットで再度コネクターを選択してください。 |
| リクエストが断続的に拒否される。 | 外部サービスのステータス、API クォータ、レート制限、アカウントプランを確認してください。 |

## 関連リンク

- [Connectors](../connectors.md)
- [Start a Chat](../chats.md)
- [Manage Agents](../agents.md)