# エージェント

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

エージェントはチャットセッションから生成されたエージェント定義をデプロイすることで作成されます。デプロイ後は、人間の継続的な入力なしに独立して動作します。

## エージェントの表示

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

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

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

![agents_list](./_assets/agents_list.png)

## エージェントの作成

エージェントはこのページから直接ではなく、チャットセッションから作成されます。エージェントを作成するには：

1. チャットを開き、構築したい自動化内容を説明します。
2. LLMがエージェント定義を生成したら、**Deploy Agent**をクリックします。

エージェントはエージェントページに**Starting**ステータスで表示され、数分で**Running**に移行します。フルワークフローについては[Chats](./chats.md)を参照してください。

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

## エージェント詳細ページ

エージェント詳細ページでは、エージェントの完全な設定と実行履歴が表示されます。タブは**Overview**、**Runs**、**Trigger**、**Tools**、**Prompt**の5つがあります。

### Overviewタブ

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

**統計情報：**

| 指標 | 説明 |
|---|---|
| **Total Runs** | このエージェントが実行した総回数。 |
| **Success Rate** | `success`ステータスで完了した実行の割合。 |
| **Total Cost** | すべての実行にかかった累積LLM使用コスト。 |

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

| 列 | 説明 |
|---|---|
| **Run ID** | 実行の一意識別子。クリックすると実行詳細ページが開きます。 |
| **Status** | 実行の最終ステータス：`success`、`failed`、`timeout`、`cancelled`のいずれか。 |
| **Started** | 実行開始のタイムスタンプ。 |
| **Duration** | 実行にかかった時間。 |
| **Tokens** | 実行で消費されたLLMトークンの総数。 |

#### 実行ステータス

| ステータス | 説明 |
| ----------- | ------------------------------------------------------------ |
| `success`   | エージェントがエラーなくタスクを完了しました。                 |
| `failed`    | エージェントが回復不能なエラーに遭遇しました。                 |
| `timeout`   | 実行が設定された時間制限（`run_timeout_s`、デフォルト300秒）を超えました。 |
| `cancelled` | 実行が完了前にキャンセルされました。                           |

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

タブ下部の**Agent Definition**にはエージェント定義のJSON全文が表示されます。クリックすると展開されます。

![agents_overview_tab](./_assets/agents_overview_tab.png)

### Runsタブ

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

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

#### 実行詳細ページ

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

**ヘッダー：**

| フィールド | 説明 |
|---|---|
| **Run ID** | この実行の一意識別子。 |
| **Status** | 最終ステータス：`success`、`failed`、`timeout`、`cancelled`のいずれか。 |
| **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`）。チェックマークは成功を示します。 |
| `LLM CALL` | LLM呼び出し。呼び出し回数および入出力トークン数を含みます。 |
| `RESPONSE` | この実行におけるエージェントの最終応答テキスト。 |
| `RUN END` | 最終イベント。最終ステータスを含みます。 |

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

![agents_run_timeline](./_assets/agents_run_timeline.png)

### Triggerタブ

Triggerタブにはこのエージェントを起動するイベントソースが表示されます。

| フィールド | 説明 |
|---|---|
| **Kind** | トリガーの種類。現在は `mqtt` のみ。 |
| **Trigger Topic** | エージェントがサブスクライブするMQTTトピックフィルター。ワイルドカード（`+` と `#`）をサポート。 |
| **QoS** | サブスクリプションのMQTT QoSレベル。 |
| **Connector** | サブスクリプションに使用されるEMQXブローカーのコネクター名。 |

### Toolsタブ

Toolsタブには実行中にエージェントが呼び出せるツールが一覧表示されます。各ツールには名前と設定が表示され、クリックすると詳細が展開されます。

現在利用可能なツール：

| ツール | 説明 |
|---|---|
| `mqtt.publish` | MQTTトピックにメッセージをパブリッシュします。`allowed_topics`にリストされたトピックに制限されます。 |
| `tables.sql` | EMQX Tablesコネクターに対してSQLクエリを実行します。クエリごとに`max_rows`件までの結果に制限されます。 |

### Promptタブ

Promptタブにはエージェントが各実行で使用する指示文が表示されます。このテキストはエージェントを生成したチャットセッション中にLLMが生成したもので、各受信MQTTイベントに対するエージェントの動作を記述しています。

このページ上ではプロンプトは読み取り専用です。エージェントの動作を変更するには、元のチャットに戻り、変更内容を説明してエージェントを再デプロイしてください。

## エージェントの編集

エージェントの**名前**と**説明**はエージェント詳細ページから更新可能です。

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

トリガー、ツール、スキル、プロンプトの変更は元のチャットに戻って再デプロイしてください。詳細は[Chats](./chats.md#redeploy-from-a-chat)を参照してください。

## エージェントの再起動

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

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

## エージェントの削除

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

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

## 次のステップ

- [コネクターの管理](./connectors.md)
- [チャットを開始する](./chats.md)