# EMQXエージェントをEMQXブローカーに接続する

EMQXブローカーコネクターは、エージェントがMQTTメッセージをイベントトリガーとして受信し、アクションとしてMQTTメッセージをパブリッシュできるようにします。このコネクターは、テレメトリ処理、異常検知、アラートルーティング、デバイスコマンドのワークフローに使用します。

## 主なユースケース

- デバイスのテレメトリがMQTTトピックに到着したときにエージェントをトリガーする。
- テレメトリを解析し、別のMQTTトピックにアラートをパブリッシュする。
- トピックのネームスペース間で正規化されたメッセージをルーティングする。
- 外部データを評価した後にデバイスコマンドをパブリッシュする。

チャットプロンプトの例：

```text
factory-brokerコネクターを使用します。devices/+/telemetryにメッセージが到着したらエージェントをトリガーします。温度が80を超えた場合、QoS 1でalerts/temperatureにJSON形式のアラートをパブリッシュします。
```

## 前提条件

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

- MQTTブローカーのアドレスとリスナーポート
- ブローカーが認証を必要とする場合のユーザー名とパスワード
- リスナーで必要なTLS設定
- エージェントがサブスクライブ可能なMQTTトピックフィルター
- エージェントがパブリッシュ可能な具体的なMQTTトピック

## EMQXブローカーコネクターの追加

1. 左側のナビゲーションメニューで **Connectors** をクリックします。
2. **Available** タブで **EMQX Broker** を見つけて **Add** をクリックします。
3. コネクターの各項目を設定します。
4. **Confirm** をクリックします。
5. **Added** タブでコネクターがリストに表示されていることを確認します。

| 項目 | 必須 | 説明 |
|---|---|---|
| **Type** | はい | 選択したコネクタータイプ、`EMQX Broker`。 |
| **Name** | はい | 表示名。例：`factory-broker`。名前は文字で始まり、文字、数字、ハイフン、アンダースコアを含めることができ、最大64文字です。 |
| **Address** | はい | `host:port`形式のブローカーアドレス。MQTTの場合は例：`broker.example.com:1883`、TLSを使う場合は例：`broker.example.com:8883`。 |
| **Username** | いいえ | ブローカー認証に使用するユーザー名。 |
| **Password** | いいえ | ブローカー認証に使用するパスワード。 |
| **Client ID Prefix** | いいえ | このコネクターが作成するMQTTクライアントIDに付与するプレフィックス。ブローカーのログでエージェント接続を識別したい場合に有用です。 |
| **Enable TLS/SSL** | いいえ | 接続にTLSを有効にします。デフォルトは無効です。 |
| **Default QoS** | いいえ | サブスクライブおよびパブリッシュのデフォルトMQTT QoS。利用可能な値は `0`、`1`、`2`。デフォルトは `1`。 |

<!-- TODO: 最終的なフィールド順が現在のドキュメントと異なる場合は、agents_add_emqx_broker_connector.pngという名前のサニタイズ済みスクリーンショットを追加してください。 -->

## EMQXブローカーコネクターの編集

1. **Added** タブで、EMQXブローカーコネクターの編集アイコンをクリックします。
2. コネクターがデプロイ済みエージェントで使用されていない場合、**Edit Connector** パネルで以下のいずれかの項目を更新できます：
   - **Name**
   - **Address**
   - **Username**
   - **Password**
   - **Client ID Prefix**
   - **Enable TLS/SSL**
   - **Default QoS**
3. コネクターがデプロイ済みエージェントで使用されている場合は、**Name** のみ更新可能です。
4. **Confirm** をクリックします。

**Type** フィールドは読み取り専用で変更できません。

::: warning 重要なお知らせ
デプロイ済みエージェントで使用されているコネクターのアドレス、認証情報、TLS設定、クライアントIDプレフィックス、デフォルトQoSは、たとえフィールドが有効になっていても変更しないでください。Consoleは `connector is used by deployed agents: <agent-id>` というメッセージでアドレス変更を拒否します。
:::

## サポートされるトリガーとツール

### MQTTサブスクリプショントリガー

`mqtt.subscribe` トリガーは、メッセージが設定されたトピックフィルターに一致したときにエージェントの実行を開始します。

チャットプロンプトには以下の値を記述してください：

- コネクター名
- MQTTトピックフィルター
- QoS
- 期待されるペイロード形式

MQTTのサブスクリプショントピックフィルターには `+` と `#` のワイルドカードを含めることができます。ワークフローを満たす最も狭いトピックフィルターを使用してください。

### MQTTパブリッシュツール

`mqtt.publish` ツールは、コネクターを通じて許可されたMQTTトピックにメッセージをパブリッシュします。

生成されるエージェント定義は、明示的に許可されたトピックへのパブリッシュのみを制限します。MQTTのパブリッシュトピックは具体的なトピック名でなければならず、ワイルドカードを含めることはできません。

::: warning 重要なお知らせ
ワークフローで必要ない限り、`#` のような広範囲なサブスクリプションや広範囲なパブリッシュ権限は避けてください。広範囲なトピックアクセスは、無関係なデバイスデータの漏洩や意図しないパブリッシュを許してしまう可能性があります。
:::

## 権限とセキュリティ

- コネクターが必要なトピックにのみアクセスできるように、ブローカーの認証および認可を設定してください。
- 可能であれば、エージェントのワークフロー用に別のMQTTユーザーを使用してください。
- チャットプロンプトにブローカーのユーザー名やパスワードを含めないでください。
- 信頼できないネットワーク経由でブローカーにアクセスする場合はTLSを使用してください。

## 制限事項

- ブローカーの認証および認可ルールにより、コネクターが正常に設定されていてもサブスクリプションやパブリッシュが拒否される場合があります。
- ネットワークやTLSのエラーにより、トリガーやパブリッシュツールがブローカーに到達できないことがあります。
- コネクターはブローカー側で設定されたMQTTトピックの認可を置き換えるものではありません。

<!-- TODO: Consoleが接続テストを提供しているか確認し、成功およびエラー状態をドキュメントに記載してください。 -->

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

| 症状 | 解決策 |
|---|---|
| コネクターがブローカーに接続できない。 | アドレス、ポート、TLS設定、リスナーの稼働状況、ネットワークアクセスを確認してください。 |
| MQTT認証に失敗する。 | コネクターのユーザー名とパスワード、およびブローカーの認証設定を確認してください。 |
| サブスクリプションでメッセージを受信しない。 | トピックフィルター、QoS、ブローカーの認可ルールを確認してください。 |
| エージェントがパブリッシュできない。 | 生成されたエージェントの許可トピックに対象トピックが含まれているか、ブローカーの認可で許可されているか確認してください。 |

## 関連リンク

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