# クイックスタート：最初のエージェントの構築とデプロイ

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

このガイドの最後には、以下を達成しています。

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

## 前提条件

- 有効なプロジェクトを持つ EMQX Cloud アカウント
- **Running** 状態の EMQX Broker デプロイメント。ブローカーは EMQX Agents デプロイメントと同じプロジェクトおよびリージョンにある必要があります。
- テストメッセージをパブリッシュするための MQTT クライアント（例：[MQTTX](https://mqttx.app/)）

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

![agents_project_home](./_assets/agents_project_home.png)

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

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

3. **New Deployment** ページで：
   - **Starter** プランがデフォルトで選択されています。
   - **Cloud Provider & Region** では、EMQX Broker デプロイメントと同じプロバイダーおよびリージョンを選択します。
   - **Network Association** では、ブローカーのデプロイメントと共有されているネットワークをドロップダウンから選択します。これにより、エージェントとブローカー間のプライベート接続が有効になります。

   ::: tip
   ドロップダウンにネットワークが表示されない場合、選択したリージョンに既存の EMQX Broker または EMQX Tables デプロイメントがありません。先にそれらを作成してからこのステップに戻ってください。
   :::

4. 必要に応じて **Deployment Name** を入力します。

5. **Deploy** をクリックし、確認ダイアログで **Confirm** をクリックします。

デプロイメントの初期化には少し時間がかかります。準備ができたら、デプロイメントをクリックして開きます。

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

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

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

2. **+ Add Connector** をクリックします。

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

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

コネクターがリストに表示され、**Description** 列にアドレスが示されます。

![agents_add_connector](./_assets/agents_add_connector.png)

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

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

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

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

   ![agents_select_connector](./_assets/agents_select_connector.png)

3. 入力フィールドに、エージェントにやらせたいことを説明します。このガイドでは以下を入力してください。

   ```
   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.
   ```

4. 右下のドロップダウンから希望の思考モードを選択し、送信ボタンをクリックします。

LLM がリクエストを処理し、エージェントの指示を生成します。ローリング温度履歴を管理するスキルを作成し、MQTT トリガーとパブリッシュツールを設定した完全なエージェント定義を組み立てます。

## ステップ 4：エージェントをデプロイ

LLM がエージェント定義の生成を完了すると、チャット画面の下部に **Deploy Agent** ボタンが表示されます。

![agents_chat_response](./_assets/agents_chat_response.png)

1. **Deploy Agent** をクリックします。

2. ダイアログが表示され、事前入力された **Agent Name** と **Description** が表示されます。必要に応じて編集し、**Deploy Agent** をクリックします。

   ![deploy_agent](./_assets/deploy_agent.png)

3. エージェントの作成が即座に開始され、エージェント詳細ページに遷移します。

数分後、エージェントのステータスが **Running** になります。以下の5つのタブ（**Overview**, **Runs**, **Trigger**, **Tools**, **Prompt**）で、チャットから生成された完全な設定を確認できます。

- **Trigger**：種類は `mqtt`、トピックは `factory/+/+/temperature`、QoS は `1`、`factory-broker` コネクターに接続。
- **Tools**：`mqtt.publish`、`alerts/anomaly` トピックに制限。
- **Prompt**：LLM がこのエージェント用に作成した指示で、各イベントの振る舞いを説明。

![agents_agent_detail](./_assets/agents_agent_detail.png)

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

テストメッセージを連続してパブリッシュし、エージェントが正しく動作するか確認します。

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

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

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

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

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

   トリガートピックにマッチした各メッセージで実行が作成され、各実行は **success** ステータスを表示します。

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** イベントでアラートがパブリッシュされたことが確認できます。

![agents_run_detail_timeline](./_assets/agents_run_detail_timeline.png)

## 次にやること

- [EMQX Tables コネクターを追加](./connectors.md) して、エージェント内から時系列データのクエリや書き込みを行う。
- [エージェントの管理](./agents.md) で実行履歴の監視、タイムラインの検査、動作更新による再デプロイを行う。
- [コネクターの更新](./connectors.md) で認証情報の変更や追加ブローカーへの接続を設定する。