最初のエージェントのビルドとデプロイ

このガイドでは、EMQX Agents を使用してイベント駆動型のエージェントを作成する手順を説明します。工場のデバイスからの MQTT メッセージを監視し、各読み取り値をローリング平均と比較して、デバイスの平均温度が閾値を超えた場合にアラートをパブリッシュする温度異常監視エージェントを構築します。

このガイドの終了時には、以下が用意されています：

• EMQX Broker に接続された稼働中の EMQX Agents デプロイメント
• ブローカー用に構成されたコネクター
• ライブの MQTT イベントに反応するデプロイ済みエージェント

前提条件

• 有効なプロジェクトを持つ EMQX Cloud アカウント
• Running 状態の EMQX Broker デプロイメント
• テストメッセージをパブリッシュするための MQTT クライアント（例：MQTTX）

ステップ 1: EMQX Agents デプロイメントの作成

EMQX Agents はすべてのユーザーにパブリックベータとして提供されています。EMQX Cloud コンソールから直接 Agents デプロイメントを作成できます。

1. EMQX Cloud コンソールにログインし、プロジェクトを開きます。

2. EMQX Agents カードの + New をクリックします。

   

3. Agents デプロイメントのリージョンを選択します。Google Cloud のみがサポートされているクラウドプロバイダーです。

4. [任意] このガイドで Broker とプライベート接続を使用する場合は、Network Association (Optional) で Broker ネットワークを選択します。ネットワークの関連付けはコネクターが使用する Broker アドレスを変更しません。

5. Deploy をクリックし、操作を確認します。

デプロイメント作成後にネットワークを変更することはできません。フィールドの詳細説明やネットワークオプションについては、Create an EMQX Agents Deployment を参照してください。

デプロイメントの状態が Running に変わったら、デプロイメントをクリックして開きます。

ステップ 2: コネクターの追加

エージェントが MQTT トピックをサブスクライブしたりメッセージをパブリッシュしたりする前に、EMQX Broker を指すコネクターを構成する必要があります。

1. EMQX Agents デプロイメントで、左メニューの Connectors をクリックします。

2. Available タブで EMQX Broker を見つけ、Add をクリックします。

3. Add Connector パネルで以下を入力します：

   • Type：EMQX Broker が自動入力されます。
   • Name：例として factory-broker などの名前を入力します。
   • Address：host:port 形式でブローカーのアドレスを入力します。必ずポート番号を含めてください。例：暗号化なし MQTT は broker.example.com:1883、TLS は broker.example.com:8883。アドレスは EMQX Broker デプロイメントの概要ページの MQTT Connection Information セクションで確認できます。
   • Username と Password：EMQX Broker デプロイメントの Access Control -> Authentication で設定した認証情報を入力します。
   • Client ID Prefix：空欄のままにします。クライアントIDはシステムが自動生成します。
   • このガイドでは Enable TLS/SSL はオフ、Default QoS は 1 のままにします。

4. Confirm をクリックします。

コネクターは Added タブに表示され、Description 列にアドレスが示されます。

ステップ 3: チャットを開始しエージェントを説明する

エージェントは会話を通じて構築されます。やりたいことを説明すると、LLM がエージェント定義を生成します。

1. 左メニューの Chats をクリックし、+ New Chat をクリックします。

2. 入力エリア左下のコネクターアイコンをクリックします。Connectors パネルが表示され、構成済みのコネクターが一覧表示されます。factory-broker をチェックして、このセッションで利用可能にします。

   

3. 左下のツール承認モードセレクターから Always ask を選択します。このモードでは、デプロイ前や承認が必要なツール操作の前に確認が求められます。利用可能なモードの詳細は Select a Tool Approval Mode を参照してください。

4. 入力フィールドにエージェントにやらせたいことを記述します。このガイドでは以下を入力します：

   I want to monitor MQTT temperature events on the topic factory/+/+/temperature.
   Each message payload is JSON, for example: {"device_id": "dev-0042", "temp": 95.4}
   The agent should track the last 3 readings per device. If the rolling average
   exceeds 70, publish an alert to alerts/anomaly.

5. [任意] Add File アイコンをクリックしてスクリーンショット、サンプルペイロード、UTF-8 テキストファイルなどを添付し、LLM により多くのコンテキストを提供できます。各チャットメッセージは最大3つの添付ファイルを含められ、各ファイルは 2 MiB 以下でなければなりません。詳細は Add Attachments を参照してください。

6. [任意] 右下のセレクターから、このリクエストに使用するモデルと推論の努力レベルを選択します。詳細は Select a Model and Reasoning Effort を参照してください。

7. 送信ボタンをクリックします。

LLM がリクエストを処理し、ローリング温度履歴を維持するスキルを書き、MQTT トリガーとパブリッシュツールを構成した完全なエージェント定義を生成します。

ステップ 4: エージェントのデプロイ

Builder がエージェント定義を生成・検証すると、チャット下部に Review Agent が表示されます。

1. 生成された定義を確認します。トリガー、閾値、アラートトピック、生成されたスキルが要件に合わない場合は、追質問や変更依頼を行います。

2. Review Agent をクリックして右側のレビュー パネルを開きます。

3. 必須の Agent Name、任意の Description、Model and reasoning、Trigger、Instructions、Tools を確認します。パネルは初期状態でチャットで選択したモデルと推論の努力レベルを使用します。必要に応じて設定を編集してください。

   

4. Deploy Agent をクリックします。

5. Confirm deployment? ダイアログで Confirm をクリックします。この追加確認はチャットで Always ask を選択したため表示されます。

6. エージェントの作成が開始され、エージェント詳細ページが開きます。

数分後にエージェントの状態が Running になるのを確認できます。4つのタブ（Overview、Runs、Configuration、Skills）でデプロイ済みエージェントとそのワークスペースを表示します：

• Configuration：エージェントの指示、MQTT トリガー、mqtt.publish ツールが生成されています。トリガーはトピックフィルター factory/+/+/temperature、QoS 1、factory-broker コネクターを使用します。パブリッシュツールは alerts/anomaly に制限されています。
• Skills：生成されたスキルとサポートファイルがこのデプロイ済みエージェントにバンドルされています。ローリング温度履歴を維持し、アラートをパブリッシュするタイミングを判定します。これらのファイルは左ナビゲーションメニューの Skills で管理される デプロイメントレベルのスキル とは別です。

ステップ 5: エージェントのテスト

エージェントをトリガーし、動作を検証するために一連のテストメッセージをパブリッシュします。

1. MQTT クライアントを開き、同じ認証情報で同じ EMQX Broker に接続します。

2. factory/+/+/temperature にマッチするトピック、例えば factory/plant-a/line-3/temperature に複数のメッセージをパブリッシュします。JSON ペイロードを使用します：

   {"device_id": "dev-0022", "temp": 75.1}

   温度が70を超える値（例：75.1、78.3、80.0）で少なくとも3回パブリッシュしてください。これにより、エージェントが閾値を超えるローリング平均を計算できます。

3. EMQX Agents デプロイメントに戻り、エージェントの Runs タブを開きます。

   トリガートピックにマッチした各メッセージで1つの実行が作成されます。完了した実行は Succeeded ステータスを表示します。

4. 実行IDをクリックして実行詳細ページを開きます。Timeline にはその実行のイベントシーケンスが表示されます：

   イベント	説明
   TRIGGER	実行を開始した MQTT メッセージ（トピック含む）
   BUNDLE LOADED	エージェントのスキルと設定がロードされた
   CONTEXT LOADED	会話コンテキストが準備された
   TOOLS RESOLVED	実行で利用可能なツールが解決された
   SYSTEM INIT	エージェントの指示が適用された
   TOOL RESULT	エージェントが呼び出した各ツール（例：read、run_script、mqtt.publish）
   LLM CALL	LLM の呼び出し（入力・出力トークン数付き）
   RESPONSE	実行の最終応答
   RUN END	実行の終了ステータス

   ローリング平均閾値を超えた場合、mqtt.publish ツールの結果がタイムラインに表示され、Response イベントでアラートがパブリッシュされたことが確認できます。

オプション: MCP コネクターを使ったエージェントの構築

MCP コネクターを使うと、エージェントやチャットが Model Context Protocol (MCP) を通じて外部サービスを利用できます。

Slack などの外部サービスを使うエージェントを構築したい場合は、このオプションのフローを使用します。このフローはメインチュートリアルの MQTT 温度監視とは異なるリクエストのため、別のチャットを使います。

ステップ 1: MCP コネクターの追加

1. EMQX Agents デプロイメントで左メニューの Connectors をクリックします。

2. Available タブで MCP コネクターサービスの Slack を見つけます。

3. コネクターカードの Add をクリックします。

4. Add Connector パネルでコネクターの Name を入力します。例：ops-slack。Type フィールドは選択したサービスで自動入力され、他の設定フィールドは不要です。

5. Confirm をクリックします。

コネクターは Unauthorized ステータスで追加され、EMQX Agents は選択したサービスの認可ダイアログを開きます。外部認可フローを完了してください。認可が成功すると、Added タブのコネクターのステータスが Authorized に変わります。

ダイアログを閉じるか認可に失敗した場合は、Added タブに戻り、コネクターの認可再試行アクションをクリックしてください。

ステップ 2: MCP コネクターを使ったチャットの開始

1. 左メニューの Chats をクリックし、+ New Chat をクリックします。

2. 入力エリア左下のコネクターアイコンをクリックします。

3. Connectors パネルで作成した MCP コネクターを選択します。

   例では MQTT イベントと Slack 通知を使うため、factory-broker と認可済みの Slack コネクターの両方を選択します。

   Authorized 状態の MCP コネクターのみ選択可能です。コネクターが表示されているが無効の場合は、Connectors ページに戻り認可を完了または再試行してください。

   

4. 以下のリクエストを入力します：

   Listen to MQTT topic /devices/#. If the temperature in the MQTT message
   is above 30, please send a warning message to Slack. Channel: <channel-name>.

   <channel-name> は通知したい Slack チャンネル名に置き換えてください。

5. ツール承認モードを選択します。ガイド付きデプロイフローには Always ask を選択します。

6. [任意] このリクエストに使用するモデルと推論の努力レベルを選択します。

7. 送信ボタンをクリックします。

LLM が選択した MCP コネクターで公開されているツールを含むエージェント定義を生成します。

ステップ 3: MCP エージェントのデプロイ

1. 生成された定義が準備できたら Review Agent をクリックします。

2. レビューパネルで Agent Name、Description、Model and reasoning、Trigger、Instructions、Tools を確認し、必要に応じて設定を更新します。

3. Deploy Agent をクリックします。

4. チャットで Always ask を使っている場合は、Confirm deployment? ダイアログで Confirm をクリックします。

5. エージェント詳細ページを開き、Configuration と Skills タブで生成されたエージェントが選択した MCP コネクターを使い、要求された動作を実装していることを確認します。

ステップ 4: MCP エージェントのテスト

チャットリクエストで指定した MQTT トピックと Slack アクションに従って MCP エージェントをテストします。このテストフローはメインチュートリアルの温度異常監視とは異なります。

1. MQTT クライアントを使い、/devices/# にマッチするトピック（例：/devices/device-001）にテストメッセージをパブリッシュします。

   {"device_id": "device-001", "temperature": 31}

2. リクエストで指定した Slack チャンネルに警告メッセージが届いていることを確認します。

3. EMQX Agents に戻り、実行詳細ページを開きます。MCP コネクター呼び出しは実行タイムラインのツール結果として表示され、最終 Response イベントで結果が要約されます。

次にやること

• 生成されたスキルを再利用する ことで、異なるトピックや設定、出力要件の類似エージェントを作成できます。
• EMQX Tables コネクターを追加する と、エージェント内から時系列データのクエリや書き込みが可能になります。
• MCP コネクターを管理する と、Gmail や Slack などの外部サービスをエージェントが利用できるようにします。
• エージェントをレビュー・管理する と、実行履歴の監視、タイムラインの検査、動作を更新した再デプロイが可能です。
• コネクターを更新する と、認証情報の変更や追加ブローカーへの接続を行えます。