Agents
エージェントとは、MQTTイベントに反応してインフラストラクチャ上で動作する、デプロイされた長時間実行プロセスのことです。各エージェントは独立したサンドボックス内で動作し、設定されたMQTTトピックを監視し、トリガーに一致する受信メッセージごとに実行を行います。
エージェントはチャットで生成されたエージェント定義をデプロイすることで作成されます。チャットはゼロから開始することも、組み込みテンプレートから開始することも可能です。デプロイ後は、人間の継続的な入力なしでエージェントは独立して動作します。
エージェントの表示
左メニューの Agents をクリックすると、エージェントページが開きます。このページにはこのデプロイメント内のすべてのエージェントが表示されます。各エージェントカードには以下が表示されます：
- 名前 と 説明
- ステータス：
StartingまたはRunning - 作成日時
- 実行回数合計
エージェントカードをクリックすると、その詳細ページが開きます。
エージェントの作成
エージェントはこのページから直接ではなく、チャットセッションから作成します。以下のいずれかの方法で作成してください：
- チャットを開き、構築したい自動化内容を説明する。
- Templates を開き、組み込みテンプレートを選択して Use Template をクリックし、テンプレートベースのチャットを開始する。
チャット内で生成されたワークスペースを確認・修正します。エージェント定義が検証に合格したら、Review Agent をクリックし、右側のパネルでデプロイ設定を確認してから 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トリガーの場合、設定には以下が含まれます：
| 項目 | 説明 |
|---|---|
| Type | トリガータイプ（例：MQTT Event）。 |
| 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 を使用し、Builderに動作更新を依頼してからエージェントを再デプロイしてください。
エージェントの編集
エージェント名と説明の編集
エージェント詳細ページからエージェントの名前と説明を更新できます。
- エージェント詳細ページで、エージェント名の横にある編集アイコンをクリックします。
- Edit Agent ダイアログで Agent Name または Description を更新します。
- Save をクリックします。
チャットでエージェントの動作を編集
チャットを使って、指示、トリガー、ツール、スキル、スクリプト、アセットを更新します：
- エージェント詳細ページ右上の Edit Agent in Chat をクリックします。
- 開いたチャットを確認します：
- エージェントを生成したチャットが存在する場合、その過去の会話履歴が利用可能です。
- チャットが削除されている場合は、過去の会話履歴なしで編集ページが開きます。
- エージェントの変更内容を説明するリクエストを入力します。過去の会話履歴があり、動作を変更しない場合はこのステップを省略できます。
- 変更を依頼した場合は、Builderがエージェント定義を更新・検証するのを待ちます。
- Review Changes をクリックしてレビューパネルを開きます。
- 名前、説明、モデルと推論努力度、トリガー、指示、ツールを確認し、必要に応じて設定を更新します。
- Redeploy Agent をクリックします。
- チャットが Always ask モードの場合は、Confirm deployment? ダイアログで Confirm をクリックします。その他のツール承認モードでは追加の確認は不要です。
更新されたモデルと推論努力度は再デプロイ成功後に反映されます。レビューパネルで変更してもチャットリクエストで選択されたモデルと推論努力度は変わりません。
詳細は Redeploy from a Chat をご覧ください。
エージェントの再起動
エージェントが停止または失敗状態になった場合、エージェント詳細ページから再起動できます。
- エージェント詳細ページ右上の再起動アイコンをクリックします。
- エージェントは Running 状態に戻り、トリガーイベントの監視を再開します。
エージェントの削除
重要なお知らせ
エージェントを削除すると即座に停止し、関連するすべての実行履歴が削除されます。この操作は元に戻せません。
- エージェント詳細ページ右上の削除アイコンをクリックします。
- 削除を確認します。