# EMQX Agents

EMQX Agentsは、EMQX Cloud上でホストされるサービスで、MQTTおよび時系列データを基盤にイベント駆動型のAIエージェントを構築・実行できます。カスタムの自動化コードを書く代わりに、エージェントにやってほしいことを自然言語で記述すると、プラットフォームがそれを構築してデプロイします。

エージェントはMQTTメッセージに反応し、時系列データをクエリし、アクションをデバイスにパブリッシュします。追加のミドルウェアや長時間稼働するサービスループの管理は不要です。

## EMQX Agents in EMQX Cloud

EMQX AgentsはEMQX Cloudプラットフォームの自動化レイヤーです：

| サービス | 役割 | タグ |
|---|---|---|
| EMQX ブローカー | MQTTメッセージの輸送 | CONNECT |
| EMQX Tables | 時系列データのストレージ | STORE |
| EMQX Fleets | デバイスのレジストリおよび状態管理 | MANAGE |
| EMQX Agents | イベント駆動型AI自動化 | AUTOMATE |

EMQX AgentsはEMQX ブローカーとEMQX Tablesの上に構築されています。EMQX Agentsのデプロイメントは、同じリージョン内に少なくとも1つのブローカーまたはTablesのデプロイメントが存在する既存のネットワークに関連付ける必要があります。

## コアコンセプト

### チャット

チャットは、組み込みのLLMと対話しながらエージェントにやってほしいことを記述する会話です。LLMはリクエストを解釈し、エージェントの指示やスキルを作成し、デプロイ可能なエージェント定義を組み立てます。チャット内で動作を調整したり、トリガートピックを変更したり、ロジックをテストしたりしながら繰り返し編集できます。最終的にデプロイにコミットします。

チャットは、継続的に実行する必要のない一時的なタスク（例えば、最近のデバイスデータのクエリや運用インシデントの要約）にも便利です。

### エージェント

エージェントは、イベントに反応してインフラ上で動作する長時間稼働のプロセスです。各エージェントはチャットセッションから生成されたエージェント定義に基づき、隔離されたサンドボックス環境で実行されます。トリガーとなるMQTTメッセージが届くと、エージェントは実行を開始し、指示やスキルを読み込み、必要なツールを呼び出してタスクを完了します。

エージェントには名前、説明、トリガー、ツールセット、プロンプトがあり、すべてチャットから自動生成されます。これらはエージェント詳細ページで確認可能です。

### コネクター

コネクターは、エージェントやチャットが利用できる外部サービスへの設定済み接続です。各コネクターはエージェントが呼び出せる型付きのアクションセットを公開します。EMQX Agentsは現在、以下の2種類のコネクターをサポートしています：

- **EMQX ブローカー**：MQTTトピックをトリガーとしてサブスクライブし、アクションとしてメッセージをパブリッシュします。
- **EMQX Tables**：SQLを通じて時系列データのクエリと書き込みを行います。

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

### 実行（Run）

実行は、エージェントが1つのインバウンドイベントでトリガーされて行う単一の処理です。各実行にはステータス、所要時間、トークン使用量、エージェントが実際に行った操作（呼び出したツール、受け取った応答、最終結果）を示すタイムラインがあります。

実行ステータスは以下の通りです：

| ステータス | 意味 |
|---|---|
| `success` | エージェントがタスクを完了しました。 |
| `failed` | エージェントが回復不能なエラーに遭遇しました。 |
| `timeout` | 実行が設定された時間制限を超えました。 |
| `cancelled` | 実行が完了前にキャンセルされました。 |

### スキル

スキルは、チャット中にLLMが生成し、エージェント定義にまとめられる再利用可能な機能です。スキルはドメイン固有のロジック（例：デバイスごとの温度読み取り値のローリング平均の維持など）をカプセル化し、エージェントが実行ごとに一貫して呼び出せるようにします。スキルは自動生成され、手動で作成する必要はありません。

## 動作の流れ

1. **コネクターを追加します。** EMQX ブローカーとEMQX Tablesのデプロイメントを接続し、エージェントがデータとメッセージング基盤にアクセスできるようにします。

2. **チャットで自動化内容を記述します。** 新しいチャットを開き、使用するコネクターを選択し、自然言語でやりたいことを説明します。LLMがトリガー、ツール、スキル、プロンプトを含む完全なエージェント定義を生成します。

3. **エージェントをデプロイします。** チャット内の **Deploy Agent** をクリックして生成された定義から実行中のエージェントを作成します。エージェントは設定されたMQTTトピックの監視を即座に開始します。

4. **イベントが実行をトリガーします。** トリガートピックにMQTTメッセージが届くたびに、エージェントは実行を行います。ロジックを適用し、`mqtt.publish` や `tables.sql` などのツールを呼び出してタスクを完了します。

5. **監視と反復を行います。** エージェント詳細ページで実行履歴、成功率、トークン使用量、各実行のタイムラインを確認します。動作を変更したい場合はチャットに戻り、再デプロイします。

## 主なユースケース

- **異常検知**：デバイスのテレメトリを監視し、ローリング平均が閾値を超えた場合にアラートをパブリッシュ。
- **インシデント要約**：最近のMQTTイベントを集約し、オンデマンドで人間が読める要約を生成。
- **条件付きアクション**：センサーデータが定義された条件を満たしたときにデバイストピックへコマンドをパブリッシュ。
- **データ強化**：MQTTイベントに応じてEMQX Tablesをクエリし、その結果をブローカーにパブリッシュ。
- **運用通知**：停止したデバイスやハートビートの欠如を検知し、オンコールチームに通知。

## プランと利用状況

EMQX Agentsは現在、**Starter**プランでパブリックベータとして提供されています。ベータ期間中は利用無料です。

| 仕様 | 内容 |
|---|---|
| プラン | Starter |
| 利用状況 | パブリックベータ |
| ベータ期間中の課金 | 無料（トライアル） |
| 対応クラウドプラットフォーム | AWS、Google Cloud |

## 次のステップ

- [EMQX Agentsのデプロイメントを作成する](./emqx_agents_create_deployment.md)
- [クイックスタート：最初のエージェントを構築してデプロイする](./emqx_agents_quick_start.md)