EMQX Agents スキルの管理

デプロイメントレベルのスキルは、EMQX Agents にタスクやワークフローを案内する再利用可能なパッケージです。このパッケージには、スキルを説明するルートレベルの SKILL.md ファイルが含まれ、スクリプト、リファレンス、アセット、その他のサポートファイルも含めることができます。チャット内でスキルを参照することで、異なるトピック、設定、出力要件を持つ類似のエージェントを作成できます。

例えば、スキルは以下のようなエージェントの作成方法を説明できます。

• デバイスのオフラインイベントを監視し、アラートの要約を生成する。
• EMQX Tables からテレメトリーデータを照会し、日次レポートを作成する。
• MQTT トピックをリッスンし、異常を検出して標準アクションを実行する。
• チーム定義の形式で根本原因分析レポートを作成する。

スキルは現在のチャット実行を案内します。スキルを参照しただけでは直接エージェントが作成・デプロイされるわけではありません。生成されたエージェント定義を確認し、検証後にデプロイする必要があります。スキルはコネクター、ツール、権限を追加せず、エージェントの指示を置き換えることもありません。

デプロイメントレベルのスキルは、デプロイされたエージェントにバンドルされたスキルとは異なります。実行時に EMQX Agents は選択された SKILL.md の内容を読み込み、選択されたパッケージファイルを Builder に読み取り専用ファイルとして提供します。パッケージは Builder のワークスペースにコピーされたり、デプロイ済みエージェントバンドルに追加されたりしません。デプロイメントレベルのスキルは左側のナビゲーションメニューの Skills から管理します。バンドルされたエージェントスキルはエージェント詳細ページで読み取り専用のままです。

前提条件

デプロイメントレベルのスキルを管理または使用する前に：

• EMQX Agents のデプロイメントを作成し、Running 状態であることを確認してください。
• デプロイメントのスキルを閲覧する権限があることを確認してください。

スキルはデプロイメント管理と同じロール権限を使用します。

メンバーロール	スキルの権限
Administrator	スキルの閲覧、アップロード、削除、置換が可能。
Project Administrator および Project User	許可されたプロジェクト内でスキルの閲覧、アップロード、削除、置換が可能。
その他のデプロイメントアクセス権を持つメンバー	読み取り専用アクセス。

Console でスキルを更新するには、同名のスキルパッケージで置き換えます。読み取り専用ユーザーは、許可されたチャット内でのみスキルを参照できます。プロジェクトアクセスの詳細は Roles and Permissions を参照してください。

エージェント作成ワークフローの再利用

エージェント作成時に生成されたスキルを再利用するか、自分でスキルを書いてエージェントの作成方法を定義できます。

生成されたスキルの再利用

1. チャットを開始し、作成したいエージェントを説明します。
2. 生成されたエージェント定義を確認し、要件を満たすまでフォローアップメッセージで調整します。
3. 検証後、エージェントをデプロイします。
4. エージェント詳細ページで Skills タブ を開き、生成された SKILL.md ファイルを選択してダウンロードします。
5. ダウンロードしたファイルをスキルパッケージに入れ、スキルパッケージの準備 に従って .tar.gz または .zip アーカイブを作成します。
6. デプロイメントの Skills ページにアーカイブをアップロードします。
7. 類似のエージェントを作成するときは、チャットでスキルを参照し、エージェント名、MQTT トピック、閾値、出力要件などの違いを説明します。

独自のスキルを書く

生成されたエージェントが要件を満たさない場合、SKILL.md ファイルを作成してエージェントの目的、トリガー、データソース、ツール、動作、出力形式を指定できます。ファイルをパッケージ化してアップロードし、その後のチャットでスキルを参照して作成要件を再利用します。完全な例は スキルパッケージの準備 を参照してください。

スキルパッケージの準備

1つの .tar.gz または .zip アーカイブに1つのスキルパッケージを含めてアップロードします。アーカイブは、ルートに1つの非空の UTF-8 エンコードされた SKILL.md ファイルを含む、1つのトップレベル <skill-name>/ ディレクトリを正確に含む必要があります。

<skill-name>/SKILL.md
<skill-name>/scripts/process.py
<skill-name>/references/guide.md
<skill-name>/assets/example.json

トップレベルディレクトリ名は SKILL.md のフロントマターの name フィールドと一致しなければなりません。パッケージにはスクリプト、リファレンス、アセット、その他スキルに必要な通常ファイルを含められます。アーカイブに複数のスキルパッケージ、シンボリックリンク、ハードリンク、その他特殊ファイルを含めることはできません。

一般的なOSのメタデータファイルは無視され、パッケージサイズにカウントされません。

以下の例は、デバイスのオフラインイベントの急増を検出するエージェントの作成方法を示しています。エージェント確定前に要求するデータと設定を指定しています。内容を <skill-name>/SKILL.md として保存し、ワークフローに合わせて調整し、ディレクトリを .tar.gz または .zip アーカイブにパッケージしてください。

---
name: device-offline-monitor
description: デバイスのオフラインイベントの急増を検出し、MQTT 運用アラートを生成するエージェントを作成します。
---

# Device Offline Monitor Agent

## 目的

デバイスのステータスメッセージを監視し、オフラインイベントの異常増加を検出して簡潔な運用アラートを生成するエージェントを作成します。

## トリガーとデータ

1. `factory/+/device/+/status` の MQTT イベントトリガーを使用します。
2. `status = offline` のメッセージをオフラインイベントとして扱います。
3. EMQX Tables から過去15分間のデバイスステータス履歴を照会し、過去データと比較します。

## エージェントの動作

1. ユーザー提供のデータマッピングを使い、工場と生産ラインごとにオフラインイベントをグループ化します。
2. 現在の5分間のイベント数を直近のベースラインと比較します。
3. イベント数が設定された閾値を超えた場合のみ報告します。
4. 影響を受けたデバイス、時間範囲、考えられる原因、推奨される次のアクションを含めます。

## 要求する設定

- MQTT トピックフィルターと必要なコネクター。
- EMQX Tables のテーブルと工場、生産ライン、デバイス、ステータス、タイムスタンプのデータマッピング。
- オフラインイベント数の閾値。
- 比較ウィンドウとベースラインウィンドウ。
- 出力言語とアラート送信先。

## 出力形式

以下のセクションを含む短いアラートを返します：概要、証拠、影響デバイス、考えられる原因、推奨アクション。

## ガードレール

MQTT イベントや一致する過去データなしにデバイスがオフラインと断定しないでください。コネクター、トピック、データマッピング、閾値、アラート送信先の不足情報はエージェント確定前に問い合わせてください。

Console は .tar.gz と .zip アーカイブを受け付けます。ディレクトリの直接アップロードはサポートしていません。同名のスキルが既にアップロードされている場合はエラーになります。スキルを更新するには、完全なパッケージで置き換えてください。

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

左側のナビゲーションメニューの Skills をクリックすると、デプロイメントにアップロードされたスキルパッケージを表示・管理できます。各スキルの概要には、スキル名、説明、パッケージの合計サイズ、更新日時が含まれます。

スキル名をクリックすると詳細が開き、SKILL.md の内容とパッケージファイル一覧を確認できます。ファイル一覧には相対パスとファイルサイズが表示されます。UTF-8 テキストファイルは Console でプレビュー可能ですが、バイナリファイルはプレビューできません。アーカイブのダウンロードやエクスポートはサポートしていません。

スキルのアップロード

1. Skills ページで Upload Skill をクリックします。
2. 1つの .tar.gz または .zip アーカイブをアップロードエリアにドラッグするか、クリックして選択します。
3. アーカイブが スキルパッケージの準備 の要件を満たす1つのスキルパッケージを含むことを確認します。
4. Confirm をクリックします。
5. スキルが Skills ツリーに表示されることを確認します。

アップロードされたスキルパッケージは、同じデプロイメント内のチャットで即座に選択可能になります。新しいスキルをアップロードするとき、同名のスキルが既に存在する場合は拒否されます。スキルを更新するには、Replace を使って同名の置換パッケージをアップロードしてください。EMQX Agents は置換を検証し、失敗した場合は以前のパッケージを保持します。成功した場合、置換パッケージに含まれないファイルは削除されます。

スキルの削除

1. Skills ページでスキルを見つけ、Actions 列の削除アイコンをクリックします。
2. ダイアログで削除を確認します。

削除後、そのスキルは候補リストに表示されず、現在のデプロイメントでの新規実行で読み込めなくなります。過去のメッセージはスキル参照を保持しますが、削除されたスキルを参照する応答の再生成は、参照を削除または置換するまで失敗します。スキルの削除は他の EMQX Agents デプロイメントのスキルやチャットには影響しません。

スキルを使ってエージェントを作成する

デプロイメントレベルのスキルは、Overview ページの最初のチャット、新規メッセージの Chats ページ、または過去のユーザーメッセージを編集して応答を再生成するときに参照できます。

スキルを参照するには：

1. メッセージの先頭または空白の後に / とスキル名の一部（例：/device）を入力します。
2. 候補リストからスキルを選択します。各候補にはスキル名と説明が表示されます。
3. このエージェントの要件（スキルの例からの違いなど）を説明し、メッセージを送信します。

キーボードでも候補を選択できます：

• 上矢印キーまたは下矢印キーでリストを移動。
• Enter または Tab でスキルを選択。
• Escape でリストを閉じる。

選択された参照はメッセージ内に残り、ハイライトされます。例えば、オフライン監視スキルを冷蔵倉庫用にステータストピックと英語アラートを変更して適用した例：

1つのメッセージで複数のスキルを参照可能です。同じスキルが複数回参照されても、EMQX Agents は1回だけ選択し、最初に出現した順にスキルを読み込みます。

生成されたエージェント定義を確認し、チャットで要求された不足情報を提供してください。定義が要件を満たし検証に合格したら、エージェントをデプロイします。

スキルが適用されるタイミングの理解

スキル参照は、現在のメッセージから作成または再生成されたチャット実行にのみ適用されます。その会話内でエージェントの作成や変更を案内し、デプロイ済みエージェントを自動的に変更することはありません。稼働中のエージェントを更新するには、変更を確認し、チャットから再デプロイしてください。

スキル参照は以下のルールに従います：

• EMQX Agents は、現在のデプロイメントに存在し、メッセージ送信時に認識されたスキルのみを読み込みます。
• 選択されたスキルは次のメッセージに自動適用されません。
• 実行中、EMQX Agents は選択されたスキルパッケージのサポートファイルを読み込み、利用可能なインタープリターでスクリプトを実行できます。スキルの allowed-tools フィールドはツールの付与や承認要件の変更を行いません。
• スキルリストが読み込み中に手動で /skill-name を入力すると、EMQX Agents はそれをプレーンテキストとして送信します。入力はリストの読み込み完了や自動選択を待ちません。
• 不明なスキル名や /path のような通常のパスはプレーンテキストのままです。単語の途中のスラッシュはスキル参照を開始しません。
• 過去のメッセージを編集するときは、応答を再生成する前にスキル参照を確認・調整してください。新しい実行は編集されたメッセージで選択されたスキルを使用します。
• 応答を再生成するとき、EMQX Agents は選択された各スキルの現在のパッケージを読み込みます。スキルのバージョンや内容のスナップショットはメッセージに保存されないため、置換パッケージによって再生成される応答が変わる可能性があります。

現在のデプロイメントに / の後のテキストに一致するスキルがない場合、メニューに No matching skills と表示されます。

既存のスキルとチャットとの互換性

ルートレベルに SKILL.md ファイルのみを含むスキルはアップグレード後も有効なパッケージのままです。サポートファイルを追加しない限り、移行や再パッケージは不要です。

過去のメッセージは構造化されたスキル参照を保持します。過去の参照は、応答を再生成するときに同名の現在のパッケージに解決されます。構造化スキル参照が記録される前に作成されたメッセージには選択されたスキルがなく、EMQX Agents はそれらのメッセージ内のプレーンな /skill-name テキストから参照を推測しません。

スキルの問題解決

状況	動作および対応
アップロードされたファイルが .tar.gz または .zip アーカイブでない。	スキルを .tar.gz または .zip アーカイブとしてパッケージ化し、再試行してください。
複数のアーカイブが選択された。	1つずつアップロードしてください。
圧縮アーカイブが 10 MiB を超える。	アーカイブサイズを 10 MiB 以下に減らしてください。
パッケージ内の通常ファイルの合計が 50 MiB を超える。	ファイルを削除または縮小し、合計を 50 MiB 以下にしてください。
アーカイブ構造または SKILL.md が無効。	表示されたエラーメッセージに従いパッケージを修正し、再度アーカイブを作成して試してください。
同名のスキルが既に存在する。	Replace を使って同名の置換パッケージをアップロードしてください。
ロールがスキルの読み取り専用アクセスのみ。	Administrator、Project Administrator、または Project User に依頼してスキルのアップロード、削除、置換を行ってもらってください。
サービスが利用不可でスキル操作が失敗。	デプロイメントが稼働中であることを確認し、再試行してください。
参照されたスキルが削除または無効で再生成が失敗。	メッセージを編集して参照を削除または利用可能なスキルに変更し、再試行してください。

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

項目	制限
アップロード形式	1つの .tar.gz または .zip アーカイブに1つのスキルパッケージを含むこと。
パッケージ構造	トップレベルに UTF-8 エンコードの非空 SKILL.md を含む1つの <skill-name>/ ディレクトリのみ。ディレクトリ名は SKILL.md の name フィールドと一致すること。
圧縮アーカイブサイズ	10 MiB 以下（Console では 10 MB と表示）。
展開後パッケージサイズ	全ての通常ファイルの合計が 50 MiB 以下。
スキル名	64文字以内のケバブケース名。
フロントマター	description は1～1024文字。存在する場合、compatibility は1～500文字、allowed-tools は文字列、metadata は文字列キーと値のみ。
追加ファイル	スクリプト、リファレンス、アセット、その他通常ファイルをサポート。シンボリックリンク、ハードリンク、特殊ファイル、重複パス、安全でないパスは拒否。
非対応操作	ディレクトリアップロード、アーカイブのダウンロード、エクスポートは非対応。
重複名	既存のスキル名での作成は拒否。Replace で完全な同名置換パッケージをアップロード。
スコープ	スキルはアップロードされた EMQX Agents デプロイメント内でのみ利用可能。必要な各デプロイメントで別々にアップロード。
権限	スキルはデプロイメント管理の権限を使用。管理可能なロールは 前提条件 を参照。

次のステップ

• チャットの開始と管理
• エージェントの管理
• コネクターの管理