コネクター

コネクターは、EMQX Agents に EMQX サービスおよび外部システムへの制御されたアクセスを提供します。コネクターは、1つのサービスアカウント、デプロイメント、またはワークスペースの接続情報や認可情報を保存し、チャットやデプロイされたエージェントに選択された機能を提供します。

コネクターは EMQX Agents のデプロイメントレベルで設定され、複数のチャットやエージェントで再利用可能です。

コネクターの仕組み

コネクターのワークフローは以下の3段階です：

1. 追加と認可：Available タブからコネクターを追加します。接続フィールドを設定するか、外部サービスへのアクセスを認可します。
2. チャットで選択：チャット内でコネクターを選択し、EMQX Agents が関連機能を検出してエージェント構築時に使用できるようにします。
3. 実行時に使用：生成されたエージェント定義はコネクターとエージェントが必要とするツールを参照します。デプロイ後、エージェントはコネクターを使ってこれらの操作を実行します。

コネクターを追加しただけでは、すべてのチャットやエージェントがそのツールすべてにアクセスできるわけではありません。エージェント作成時に、EMQX Agents はワークフローに必要なコネクターツールを選択し、そのツールのみが生成されたエージェント定義に含まれます。

コネクターの種類

EMQX Agents は2つのコネクターグループをサポートしています。

EMQX コネクター

EMQX コネクターは接続パラメータや API 資格情報を使ってエージェントを EMQX サービスに接続します。

コネクター	機能
EMQX Broker	MQTT トピックをイベントトリガーとしてサブスクライブし、MQTT メッセージをアクションとしてパブリッシュする。
EMQX Tables	SQL を通じて時系列データのクエリと書き込みを行う。
EMQX Fleets	デバイスレジストリ、シャドウ、コマンド、ジョブ、グループ、タグ、デバイス検索を操作する。

MCP コネクター

Model Context Protocol（MCP）コネクターは外部サービスの認可を行い、承認されたサービス固有のツールセットを EMQX Agents に公開します。

コネクター	機能
Databricks	Unity Catalog、SQL ウェアハウスとステートメント、ジョブ、モデルサービング、Vector Search を操作する。
Slack	メッセージの読み取り・送信、チャンネル管理、ファイルアップロード、リアクション追加、リマインダー作成を行う。
Microsoft Teams	チャット、チーム、チャンネル、メッセージ、会議、シフトを操作する。
Telegram	Telegram ボットを使ってメッセージ、ファイル、位置情報、投票、チャット、ボットコマンドを操作する。
Gmail	メールと下書きの読み取り、検索、送信、返信、整理を行う。
Outlook	Outlook のメール、フォルダー、添付ファイル、連絡先、カレンダーイベントを操作する。
Google Docs	Google ドキュメントの作成、読み取り、エクスポート、編集を行う。
Google Drive	ファイル、フォルダー、権限、コメント、共有ドライブを管理する。
Notion	ページ、データベース、ブロック、コメント、ファイルアップロードを操作する。
Google Tasks	タスクリストとタスクの作成・管理を行う。
Linear	イシュー、プロジェクト、コメント、チーム、ユーザー、ラベル、ワークフローステートを操作する。
Supabase	データベーステーブルのクエリ、SQL 実行、エッジファンクションの呼び出しを行う。

コネクターの表示

EMQX Agents デプロイメントの左ナビゲーションメニューで Connectors をクリックします。ページには2つのタブがあります：

• Available：追加可能なコネクタータイプを表示します。検索ボックスでフィルター可能です。
• Added：既にデプロイメントに追加されたコネクターインスタンスを表示します。名前でフィルター可能です。

Added タブには以下の情報が含まれます：

列	説明
Name	コネクターに割り当てられた表示名。
Type	コネクタータイプ（例：EMQX Fleets、Gmail、Slackなど）。
Authorization	認可ステータス。この列は MCP コネクターに適用されます。
Description	接続の概要。MCP コネクターはトランスポートと認可の詳細を表示。
Updated At	最終更新日時。
Actions	編集、削除、認可の再試行などの管理アクション。

コネクターの追加

1. 左ナビゲーションメニューで Connectors をクリックします。
2. Available タブで追加したいコネクタータイプを探します。
3. コネクターカードの Add をクリックします。
4. コネクター名を入力し、必要に応じて接続フィールドを設定します。
5. Confirm をクリックします。
6. MCP コネクターの場合は、MCP コネクターの認可に進みます。EMQX コネクターの場合は Added タブを開き、コネクターが使用可能であることを確認します。

MCP コネクターの認可

MCP コネクターは外部サービスからの認可が必要です。名前を入力して Confirm をクリックすると、EMQX Agents はコネクターを Unauthorized ステータスで追加し、認可ダイアログを開きます。

ダイアログで以下の手順を完了してください：

1. Composio の指示に従います。コネクターによっては外部サービスにサインインしアクセスを認可するか、サービス URL やアクセストークンなど必要な接続情報を入力します。
2. プロンプトが表示された場合、コネクターがアクセスすべきアカウント、ワークスペース、プロジェクトなどのリソースを選択します。
3. 統合が要求する権限を確認します（表示される場合）。
4. サービスに表示された認可または接続ボタンをクリックします。
5. Composio が接続を確認し、EMQX Agents に戻るまで待ちます。
6. Added タブで Authorization successful メッセージが表示され、コネクターのステータスが Authorized であることを確認します。

接続情報、サインイン、リソース選択、承認手順は外部サービスによって異なります。詳細はコネクター固有のページを参照してください。

コネクター固有の前提条件および設定については、コネクターの種類から該当するコネクターを選択してください。

MCP コネクターの認可ステータス

MCP コネクターは以下の認可ステータスを使用します：

ステータス	説明	対応
Unauthorized	認可が完了していないか、認可フローが途中で終了した状態。	Actions 列から認可を再試行してください。
Authorized	認可に成功し、コネクターがチャットやエージェントにツールを提供可能。	対応不要です。
Expired	外部サービスの認可が期限切れ。	Actions 列から再認可してください。
Error	認可に失敗したか、EMQX Agents が認可状態を確認できない。	認可を再試行してください。エラーが続く場合は外部サービスのアカウントや権限を確認してください。

Unauthorized、Expired、Error ステータスのコネクターはチャットのコネクターパネルに表示されることがありますが、選択はできません。

チャットでのコネクターの使用

1. チャット入力エリア左下のコネクターアイコンをクリックします。
2. Connectors パネルでワークフローに必要な認可済みコネクターを選択します。
3. チャットを離れずに別のコネクターを追加するには、パネル右上の + をクリックします。
4. チャットプロンプトで必要な外部操作を記述します。

EMQX Agents は選択されたコネクターを使って、生成されたエージェント定義のトリガーやツールを設定します。例えば、EMQX Broker コネクターは MQTT イベントトリガーと MQTT パブリッシュアクションを提供し、Slack コネクターは選択されたメッセージングツールを提供します。

ワークフローの例

以下の例は、エージェント作成時にコネクターを組み合わせる方法を示しています。例示のトピック、テーブル、チャンネル名は環境のリソースに置き換えてください。

ワークフロー	コネクター	例示プロンプト	期待される結果
MQTT アラート通知	EMQX Broker と Slack	factory/+/alerts を監視し、重要なアラートを #operations Slack チャンネルに投稿するエージェントを作成してください。	生成されたエージェントは一致する MQTT メッセージをトリガーとして使用し、重要なアラートを Slack に送信します。
デバイスインシデント調査	EMQX Fleets と Microsoft Teams	デバイスのレジストリとシャドウ情報を読み取り、インシデント概要を Device Operations Teams チャンネルに投稿するエージェントを作成してください。	生成されたエージェントは EMQX Fleets からデバイス情報を取得し、Microsoft Teams に概要を共有します。
時系列データ分析	EMQX Tables	device_metrics テーブルからデバイスのテレメトリをクエリし、異常値を要約するエージェントを作成してください。	生成されたエージェントは必要な SQL クエリツールを使ってテレメトリデータを取得し、要約します。

セキュリティと権限

コネクター使用時には以下の運用を推奨します：

• エージェントに必要な最小限の権限を持つアカウントと資格情報を使用する。
• 現在のチャットやエージェントに必要なコネクターのみを選択する。
• エージェントをデプロイする前に、生成された定義に含まれるツールを確認する。特にメッセージ送信、データの変更・削除、SQL 実行、操作キャンセルを行うツールに注意する。
• 外部サービスのプライベートチャンネル、ドキュメント、データベース、その他リソースへのアクセス管理を行う。
• チャットプロンプトやエージェント指示にパスワード、API キー、アクセストークンなどの機密接続情報を含めない。

機密性の高いコネクター設定フィールドはパブリック API レスポンスでマスクされます。コネクターの資格情報は生成されたエージェント定義とは別に管理され、定義は資格情報の値を含まずコネクターを参照します。

実行時には、デプロイされた定義で参照されているコネクターのみがエージェントに利用可能となります。管理された MCP コネクターの場合、基盤となる外部サービスの資格情報は認可プロバイダーによって管理され、EMQX Agents に保存されません。

ツールの実行は、引数と結果をサニタイズした状態での実行イベントとして記録され、実行ステータスや実行時間も含まれます。

外部サービスは独自の API クォータ、レートリミット、ファイル制限、プラン制限を適用する場合があります。既知の制限についてはコネクター固有のページを参照してください。

コネクターの編集

1. Added タブで編集したいコネクターの編集アイコンをクリックします。
2. コネクタータイプに応じて編集可能なフィールドを更新します。
3. Confirm をクリックします。

EMQX コネクターの編集可能なフィールドはコネクタータイプによって異なります。詳細は各コネクター固有の説明を参照してください：EMQX Broker、EMQX Tables、EMQX Fleets。

すべての MCP コネクターでは、Name のみ編集可能です。Type および外部サービスの認可は Edit Connector パネルで変更できません。

重要なお知らせ

デプロイ済みエージェントで使用されているコネクターは、Name のみ編集してください。アドレス、資格情報、その他の接続設定は、たとえ編集パネルで有効になっていても変更しないでください。

コネクターの削除

1. Added タブで削除したいコネクターの削除アイコンをクリックします。
2. Tips ダイアログで Confirm をクリックします。

重要なお知らせ

デプロイ済みエージェントで使用中のコネクターは削除できません。削除前にすべてのデプロイ済みエージェントから該当コネクターを削除してください。

トラブルシューティング

症状	考えられる原因	解決策
MCP コネクターがチャットで選択できない。	コネクターが認可されていないか、認可が期限切れ。	Added タブを開き、認可を完了または再試行してください。
外部サービスが権限エラーを返す。	認可されたアカウントが要求されたリソースや操作にアクセスできない。	外部サービスで必要な権限を付与するか、適切なアカウントで認可されたコネクターを使用してください。
ツールが生成されたエージェントに表示されない。	コネクターが選択されていない、ツールが統合で承認されていない、またはエージェントがツールを必要としていない。	コネクターを選択し、チャットで必要な操作を明示的に記述してください。
コネクター更新後にデプロイ済みエージェントが失敗する。	更新された資格情報、アドレス、認可が無効。	コネクターをテストまたは再認可し、エージェントを再実行してください。
外部サービスが断続的にリクエストを拒否する。	サービスがレートリミット、クォータ、プラン制限を適用している。	外部サービスのステータスとアカウント制限を確認し、後で再試行してください。

テンプレートでのコネクター使用

テンプレート詳細ページで Use Template をクリックすると、Use Template パネルにテンプレートで必要なコネクタータイプが一覧表示されます。新しいチャットとワークスペースで使用する設定済みコネクターを選択してください。

テンプレートの指示をカスタマイズすると、要求される動作に応じて必要なコネクターが変わることがあります。Builder は不要になったコネクターの要求を継続しません。カスタマイズされた動作で未選択または未設定のコネクターが必要な場合、Builder はチャット内で提供を求めます。Builder はコネクター ID を自動生成したり、認可要件を回避したりしません。

テンプレートの完全なワークフローについては、EMQX Agents テンプレートの使用を参照してください。

次のステップ

• チャットを開始する
• エージェントを管理する
• テンプレートを使用する