エージェント

エージェントとは、MQTTイベントに反応してインフラストラクチャ上で動作する、デプロイされた長時間実行プロセスのことです。各エージェントは独立したサンドボックス内で実行され、設定されたMQTTトピックを監視し、トリガーに一致する受信メッセージごとに処理を実行します。

エージェントはチャットで生成されたエージェント定義をデプロイすることで作成されます。チャットは最初から開始することも、組み込みテンプレートから開始することも可能です。デプロイ後は、エージェントは人間の継続的な入力なしに独立して動作します。

エージェントの表示

左メニューの Agents をクリックすると、エージェントページが開きます。このページには現在のデプロイメント内のすべてのエージェントが表示されます。各エージェントカードには以下が表示されます：

• 名前 と 説明
• ステータス：Starting または Running
• 作成日時
• 実行回数合計

エージェントカードをクリックすると、その詳細ページが開きます。

エージェントの作成

エージェントはこのページから直接ではなく、チャットセッションから作成します。以下のいずれかの方法で作成してください：

• チャットを開き、構築したい自動化の内容を記述する。
• Templates を開き、組み込みテンプレートを選択して Use Template をクリックし、テンプレートベースのチャットを開始する。

チャット内で生成されたワークスペースを確認・修正し、エージェント定義が検証を通過したら Deploy Agent をクリックします。

エージェントはエージェントページに Starting ステータスで表示され、数分で Running に移行します。全体のワークフローについては Chats を参照してください。

新しいエージェントを最初から作成するには、エージェントページ右上の + New Agent をクリックし、新しいチャットセッションを開きます。

デプロイメントレベルのスキル

デプロイメントレベルのスキルは、類似のエージェントを作成するための再利用可能なMarkdown指示書です。現在のEMQX Agentsデプロイメント内のチャットでスキルを参照し、このエージェントの要件を記述してから生成された定義を確認・デプロイします。デプロイメントレベルのスキルは、デプロイされたエージェントにバンドルされたスキルとは独立して管理され、デプロイ済みエージェントに自動的に変更を加えることはありません。準備、アップロード、使用方法については Manage EMQX Agents Skills をご覧ください。

エージェント詳細ページ

エージェント詳細ページでは、デプロイされた設定、ワークスペースファイル、実行履歴を確認できます。タブは Overview、Runs、Configuration、Skills の4つがあります。

Overview タブ

Overviewタブでは集計統計と最近の実行履歴を表示します。

統計:

指標	説明
Total Runs	このエージェントが実行した総実行回数。
Success Rate	完了した実行のうち成功した割合（％）。
Total Cost	すべての実行における累積LLM使用コスト。

成功率は以下の式で計算されます：

Success Rate = 成功した実行数 / (成功 + 失敗 + タイムアウトの実行数) × 100%

Timeout ステータスの実行は失敗としてカウントされます。Dropped 実行は実行開始されていないため除外されます。Queued または Running ステータスの実行は、終了ステータスになるまで含まれません。

Recent Runs には直近の実行が以下の列で表示されます：

列	説明
Run ID	実行の一意識別子。クリックすると実行詳細ページが開きます。
Status	現在の実行ステータス：Queued、Running、Succeeded、Dropped、Failed、または Timeout。
Started	実行開始のタイムスタンプ。
Duration	実行にかかった時間。
Tokens	実行で消費されたLLMトークンの総数。

実行ステータス

ステータス	説明
Queued	実行がキューで待機中。
Running	実行中。
Succeeded	実行が正常に完了。
Dropped	実行キューが満杯のため開始されなかった。
Failed	実行エラーにより終了。
Timeout	実行時間制限を超過。成功率計算時は失敗としてカウント。

View all runs → をクリックするとRunsタブに移動します。

Runs タブ

Runsタブにはこのエージェントのすべての過去実行が一覧表示され、OverviewタブのRecent Runsと同じ列構成です。

Run IDをクリックすると実行詳細ページが開きます。

実行詳細ページ

実行詳細ページでは単一の実行の完全な記録を表示します。

ヘッダー:

項目	説明
Run ID	この実行の一意識別子。
Status	現在の実行ステータス：Queued、Running、Succeeded、Dropped、Failed、または Timeout。
Started / Completed	開始および終了のタイムスタンプ。
Duration	総実行時間。

トークン使用量:

項目	説明
Input Token	この実行のLLM入力コンテキスト内のトークン数。
Output Token	LLMによって生成されたトークン数。
Cached Token	LLMプロンプトキャッシュから提供されたトークン数。
Cost	この実行のLLM使用コスト。

タイムライン には実行中のすべてのイベントが時系列で表示されます：

イベントタイプ	説明
TRIGGER	実行を開始したMQTTメッセージとその到着トピック。
BUNDLE LOADED	エージェントのスキルと設定が正常に読み込まれた。
CONTEXT LOADED	会話コンテキストが準備された。
TOOLS RESOLVED	実行で使用可能なツールが解決・バインドされた。
SYSTEM INIT	エージェントの指示がシステム指示として適用された。
TOOL RESULT	エージェントによるツール呼び出しの結果（例：read、run_script、mqtt.publish、MCPコネクターのツール）。チェックマークは成功を示す。
LLM CALL	LLM呼び出し。呼び出し回数と入出力トークン数を含む。
RESPONSE	この実行におけるエージェントの最終応答テキスト。
RUN END	終了イベント。最終ステータスを含む。

任意のタイムラインイベントをクリックすると詳細が展開されます。

Configuration タブ

Configurationタブでは、デプロイされたエージェント定義（指示、トリガー、ツール）を表示します。これらがエージェントの動作を決定します。

項目	説明
Instructions	各エージェント実行に適用される指示。
Trigger	エージェントを起動するイベントソース。MQTTトピックフィルターとQoSレベルを含む。
Tools	実行中に利用可能なツールとその制限（例：mqtt.publishの許可トピック）。

MQTTトリガーの場合、設定には以下が含まれます：

項目	説明
Kind	トリガータイプ（例：mqtt.subscribe）。
Trigger Topic	エージェントがサブスクライブするMQTTトピックフィルター。ワイルドカード（+ と #）をサポート。
QoS	サブスクリプションのMQTT QoSレベル。

ツールを展開して設定を確認できます。ツールによってはツールプロバイダー、コネクターID、許可トピック、その他の制限が含まれます。

利用可能なツールはエージェント定義生成時に選択されたコネクターによって異なります。一般的なツールは以下の通りです：

ツール	説明
mqtt.publish	MQTTトピックにメッセージをパブリッシュする。allowed_topicsにリストされたトピックに制限される。
tables.sql	EMQX Tablesコネクターに対してSQLクエリを実行。クエリごとに max_rows 件までの結果に制限。
MCPコネクターのツール	GmailやSlackなどMCPコネクターサービスが公開するツール。利用可能なアクションは認可されたサービスによる。

デプロイされた設定は読み取り専用です。エージェントの動作を変更するには、Edit the Agent Behavior in a Chat に記載の Edit Agent in Chat を使用してください。

Skills タブ

Skillsタブでは、このデプロイ済みエージェントにバンドルされたスキルとサポートファイルを表示します。これらのファイルは、左ナビゲーションメニューの Skills で管理される再利用可能なデプロイメントレベルのスキルとは異なります。ワークスペースツリーでファイルを選択すると内容を確認できます。バンドルされたスキルには SKILL.md ファイルやエージェント動作を実装するスクリプトが含まれることがあります。

Markdownファイルはレンダリング表示とソース表示を切り替えられ、選択したファイルはダウンロードも可能です。

これらのファイルはエージェント詳細ページ上では読み取り専用です。スキルを変更するには Edit Agent in Chat を使い、ビルダーに動作の更新を依頼してエージェントを再デプロイしてください。

エージェントの編集

エージェント名と説明の編集

エージェント詳細ページからエージェントの名前と説明を更新できます。

1. エージェント詳細ページで、エージェント名の横にある編集アイコンをクリックします。
2. Edit Agent ダイアログで Agent Name または Description を更新します。
3. Save をクリックします。

チャットでエージェント動作を編集

エージェントのチャットを使って、指示、トリガー、ツール、スキル、スクリプト、アセットを更新します：

1. エージェント詳細ページの右上にある Edit Agent in Chat をクリックします。
2. 開いたチャットを確認します：
   • エージェントを生成したチャットがまだ存在する場合、以前の会話履歴が利用可能です。
   • チャットが削除されている場合は、以前の会話履歴なしで編集ページが開きます。
3. エージェントの変更内容を記述してリクエストします。以前の会話履歴があり動作を変更しない場合はこのステップを省略できます。
4. 変更をリクエストした場合は、ビルダーがエージェント定義を更新・検証するのを待ちます。
5. Redeploy Agent をクリックします。

詳細は Redeploy from a Chat をご覧ください。

エージェントの再起動

エージェントが停止または失敗状態になった場合、エージェント詳細ページから再起動できます。

1. エージェント詳細ページの右上にある再起動アイコンをクリックします。
2. エージェントは Running 状態に戻り、トリガーイベントの監視を再開します。

エージェントの削除

重要なお知らせ

エージェントを削除すると即座に停止し、関連するすべての実行履歴が削除されます。この操作は元に戻せません。

1. エージェント詳細ページの右上にある削除アイコンをクリックします。
2. 削除を確認します。

次のステップ

• コネクターの管理
• チャットの開始
• デプロイメントレベルのスキルの管理
• テンプレートの利用