> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# エージェントテスト

エージェントテストでは、デプロイ前に会話応答、ツールの使用、複数ターンにわたる最終結果を検証できます。テストはゼロから作成することも、既存の会話から作成することもでき、ダッシュボード、CLI、APIから実行できます。

## 動画で見る

## 概要

このフレームワークには、相互に補完し合う3種類のテストがあります。

* **シミュレーションテスト** — シミュレートされたユーザーとのエンドツーエンドの複数ターン会話を実行します
* **次の返信（シナリオ）テスト** — エージェントの次の応答が成功条件を満たすかを検証します
* **ツール呼び出しテスト** — エージェントが適切なパラメータで適切なツールを呼び出すことを確認します

### テストの使い分け

| テストタイプ         | 次のような場合に使用                                  |
| -------------- | ------------------------------------------- |
| **シミュレーション**   | 会話全体が定義した結果に到達することを確認したい場合                  |
| **次の返信（シナリオ）** | エージェントの次のメッセージが品質、トーン、ポリシーの基準を満たすことを確認したい場合 |
| **ツール呼び出し**    | エージェントが想定どおりのパラメータで特定のツールを呼び出すことを確認したい場合    |

## 会話からテストを作成する

エージェントのパフォーマンスが十分でなかったやり取りを見つけたら、実際の会話をテストケースに変換しましょう。

![会話からテストを作成する](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/7b0762965b7edb46ed6b693c126c00e9aa3e7c98dae7aa89a981b5465b949750/assets/images/conversational-ai/agent-test-from-conv.gif)

1. 通話履歴で会話を開きます
2. **この会話からテストを作成**をクリックします
3. 事前入力されたコンテキストを確認し、期待する動作を定義します
4. テストをスイートに追加し、後で同様の失敗を検出できるようにします

## シミュレーションテスト

シミュレーションテストでは、シミュレートされたAIユーザーとの完全な複数ターン会話にわたってエージェントを評価します。次の返信テストとは異なり、このテストでは会話全体が定義した結果に到達するかを確認します。

### シミュレーションテストを作成する

![シミュレーションテスト作成UI](/docs/_fern-img/ec2b27db7da62af2d82be756b2f830f0d0257a304d7c5ccb674c0a02ee8854ae.webp)

#### シナリオを定義する

ユーザーのコンテキスト、意図、行動を自然言語で説明します。シミュレーターはこの
シナリオを使用して会話を進めます。

**シナリオ例：**

> "英語があまり話せない観光客が、レストランで注文しようとしています。"

#### 成功条件を設定する

合格とみなすべき結果を定義します。このプロンプトは、会話全体が成功したかどうかを
評価するために使用されます。

**成功条件の例：**

> "エージェントが注文内容を確認し、確認事項に対応し、誤解なく注文を完了した。"

#### 最大ターン数を設定する

停止するまでにシミュレーションを実行できる長さを選択します。集中的な確認には低い値を、
複雑なワークフローには高い値を使用します。

* 最小：`1`
* 最大：`50`
* デフォルト：`5`

#### 実行して結果を確認する

テストを実行し、生成された会話のトランスクリプトを確認します。成功条件に照らして
合格／不合格の結果を確認し、プロンプト、ツール、エージェント設定を改善します。

### 任意の設定

テスト設定パネルでは、シミュレーションの動作をさらに調整できます。

* **環境**：エージェントに複数の環境が設定されている場合、テスト対象の環境を選択します。利用可能な環境が1つだけの場合、このセレクターは表示されません。
* **チャット履歴**：空の状態ではなく、途中までの会話から開始します。進行中の会話や復旧時の動作をテストする際に便利です。
* **動的変数**：基本のエージェント設定を変更せずに、ユーザー名や注文IDなど、テスト固有の値をエージェント変数に挿入します。

### ツールのモック

シミュレーションテストではツールのモックをサポートしているため、実際のシステムを呼び出す代わりに、実行中に制御された応答をエージェントに返せます。

#### モック戦略

* **モックしない**：ツールをモックしません。
* **すべてのツールをモック**：モック可能なすべてのツールがモック応答を返します。
* **選択したツールをモック**：明示的に選択したツールのみをモックします。

システムツールとワークフローツールはモックされません。

#### フォールバック動作

モックされたツールが呼び出され、一致するモック応答が見つからない場合は、次のいずれかの動作を選択します。

* **実際のツールを呼び出す**：実際のツール呼び出しを実行します。
* **エラーで終了する**：実際のツールを呼び出す代わりに、ツールからエラー応答を返します。

フォールバック設定は、少なくとも1つのツールがモックされている場合にのみ表示されます。

## 次の返信（シナリオ）テスト

次の返信（シナリオ）テストでは、複数ターンの最終結果全体ではなく、エージェントの次のメッセージだけを評価します。評価したい返信に至るまでの会話履歴を指定し、その返信を成功条件に照らして採点します。

複数ターンの最終結果には、[シミュレーションテスト](#simulation-testing)を使用してください。

### 次の返信テストを作成する

![次の返信（シナリオ）テストのインターフェース](/docs/_fern-img/62de63965584fd1b2368edfb204bd90495d03ba87fe137889a5f396859dc4dbc.webp)

#### チャット履歴を定義する

評価したい返信に至るまでの会話履歴を指定します。ユーザーのメッセージ1件でも、複数ターンの
コンテキストでもかまいません。

**チャット履歴の例：**

```
User: "I'd like to cancel my subscription. I've been charged twice this month and I'm frustrated."
```

#### 成功条件を設定する

エージェントの応答で達成すべきことを平易な言葉で説明します。期待する動作、トーン、アクションを
具体的に指定してください。

**成功条件の例：**

* エージェントは共感をもって顧客の不満を認める必要があります
* エージェントは重複請求を調査すると申し出る必要があります
* エージェントは解約または解決のための明確な次のステップを案内する必要があります
* エージェントはプロフェッショナルで親切なトーンを維持する必要があります

#### 例を指定する

評価者が基準の細かな違いを理解できるよう、成功例と失敗例の両方を指定します。

**成功例：**

> "重複請求がどれほどご不快か、よく理解しています。すぐに確認いたします。今月は実際に2件の請求があることを確認できました。重複分はただちに返金処理します。解約を進めますか、それともこの問題が解決した後も継続をご希望ですか？"

**失敗例：**

> "返金に関する問題は請求部門に連絡する必要があります。サブスクリプションは解約されます。"

#### テストを実行する

テストを実行します。LLM評価者がエージェントの次の返信を成功条件と例に照らして比較し、
合格／不合格のステータスを判定します。

## ツール呼び出しテスト

ツール呼び出しテストでは、特定の状況でエージェントがツールを正しく使用し、適切なパラメータを渡すことを検証します。これは、通話転送、データ検索、外部インテグレーションなどのアクションにおいて重要です。

### ツール呼び出しテストを作成する

![ツール呼び出しテストのインターフェース](/docs/_fern-img/291c48ac70376efa1991014f7b3ff90eb9910c9adffe250f2bf521c707c5c755.webp)

#### ツールを選択する

指定したシナリオでエージェントに呼び出してほしいツールを選択します（例：
`transfer_to_number`、`end_call`、`lookup_order`）。

#### 期待するパラメータを定義する

エージェントがツールに渡すべきデータを指定します。検証方法は3種類あります。

#### 検証方法

**完全一致**\
パラメータは指定した値と完全に一致する必要があります。

```
Transfer number: +447771117777
```

**正規表現パターン**
パラメータは特定のパターンに一致する必要があります。

```
Order ID: ^ORD-[0-9]{8}$
```

**LLM評価**
LLMが、コンテキストに基づいてパラメータが意味的に正しいかを評価します。

```
Message: "Should be a polite message mentioning the connection"
```

#### 動的変数を設定する

開発環境でテストする際は、本番環境で実際に使われる値と一致する動的変数値を使用します。
例：`{{ customer_name }}`または`{{ order_id }}`

#### 実行して検証する

テストを実行し、エージェントが適切なパラメータで正しいツールを呼び出すことを確認します。

### 重要なユースケース

ツール呼び出しテストは、重要度の高い次のシナリオで不可欠です。

* **緊急転送**：医療上の緊急事態が常に正しい番号に転送されることを確認します
* **データセキュリティ**：機密情報が許可されていないツールに渡されないことを検証します
* **ビジネスロジック**：注文検索で有効な形式と認証が使用されることを確認します

## テストを実行する

新しい動作や既知の失敗に対するテストを作成し、プロンプトや設定を調整しながら実行し、合格したら保存します。

#### ダッシュボードから実行

エージェントのインターフェースで「テスト」タブに移動します。ここから、個別のテストを実行したり、ライブラリから複数のテストを選んでバッチとして実行したり、**すべてのテストを実行**でスイート全体を実行したりできます。

![エージェントでテストを実行する](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/b1becf589a1373a780dad1109fd25e0e910d7aa821b09b047133553b1895914b/assets/images/conversational-ai/testrun.gif)

#### CLIから実行

テストを開発パイプラインに組み込みます。

```bash
elevenlabs agents test agent_7101k5zvyjhmfg983brhmhkd98n6
```

これにより、以下が可能になります。

* コード変更のたびに自動テストを実行
* デプロイ前にリグレッションを防止
* 環境間で一貫したエージェント動作を実現

#### APIから実行

[テストを作成](/docs/ja/api-reference/tests/create)してから、[エージェントでテストを実行](/docs/ja/api-reference/tests/run-tests)します。

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

invocation = elevenlabs.conversational_ai.agents.run_tests(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    tests=[{"test_id": "<test-id>"}],
)

print(invocation)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const invocation = await elevenlabs.conversationalAi.agents.runTests("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  tests: [{ testId: "<test-id>" }],
});

console.log(invocation);
```

### 確率的テスト

エージェントの出力は実行ごとに異なる場合があります。1回の合格はエージェントが成功_できる_ことを示しますが、確率的テストでは同じテストを複数回実行して合格率を報告することで、実際にどの程度成功_するか_を示します。

#### テストを複数回実行する

![テストの実行回数を選択できる分割実行コントロール](/docs/_fern-img/15d5a18c384bc193de794bf8cd7bd5803b9543c8a98acac6ecb2f518b9fd1679.webp)

ダッシュボードからテストを実行する際は、実行ボタンの分割実行コントロールを使って実行回数を選択します（例：3×、5×、15×）。各実行は独立しています。エージェントは同じチャット履歴、動的変数、その他の入力を受け取りますが、応答は毎回新たに生成されます。

複数回実行は、個別のテスト、フォルダ、エージェントに紐づくテストスイート全体で利用できます。シミュレーション、次の返信（シナリオ）、ツール呼び出しの3種類すべてのテストと互換性があり、複数ターン会話は変化の余地が大きいため、通常はシミュレーションテストで最も役立ちます。

#### 合格率と結果のバケット分け

![合格率バッジ付きで合格と失敗のバケットにグループ化された複数回実行の結果](/docs/_fern-img/17b73e8c8170162270519adad3c9d732dfabdafc820e47b4ab274ca5066fd7fc.webp)

複数回実行が完了すると、結果は色付きバッジとともに合格率（例：**5回中4回合格**）として要約されます。

* **緑** — 100%合格
* **アンバー** — 80%以上合格
* **赤** — 80%未満

個々の実行は失敗理由ごとにグループ化されるため、エージェントが失敗_したこと_だけでなく、*どのように_失敗するかも確認できます。何が異なったかを確認するために5つのトランスクリプトを個別にスクロールする代わりに、*「請求部門に正しく振り分けた（4回）」*や*「サポート番号を誤って生成した（1回）」\_のようなクラスターが表示されます。各クラスターは展開して、元となるトランスクリプトと評価の根拠を確認できます。

#### 使用するタイミング

* **変更をリリースする前** — 信頼性が低下していないことを確認するため、紐づけられたテストを確率的に再実行します（例：95%から60%への低下）。
* **不安定な動作を診断する** — 1回の失敗はノイズかもしれませんが、明確な名前の失敗バケットを伴う5回に1回の失敗は、修正すべき再現可能な問題です。
* **プロンプトとツールを調整する** — 単発の実行に頼るのではなく、設定を反復して合格率を並べて比較します。

#### APIまたはSDKから確率的に実行する

[run-tests](/docs/ja/api-reference/tests/run-tests)リクエストで`repeat_count`（`2`〜`20`）を渡すと、各テストをその回数だけ実行できます。`repeat_count`を設定すると、応答での失敗バケット分けが自動的に有効になります。そのため、返される呼び出し結果には、ダッシュボードで表示されるバケットごとのグループと合格率が含まれます。

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

invocation = elevenlabs.conversational_ai.agents.run_tests(
    agent_id="<agent-id>",
    tests=[{"test_id": "<test-id>"}],
    repeat_count=5,
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const invocation = await elevenlabs.conversationalAi.agents.runTests(
  "<agent-id>",
  {
    tests: [{ testId: "<test-id>" }],
    repeatCount: 5,
  },
);
```

## ベストプラクティス

#### エージェントのペルソナ一貫性を評価する

多様な会話シナリオや感情的なコンテキストにおいて、エージェントが定義された個性、トーン、行動上の境界を
維持することをテストします。

#### 複雑な複数ターン推論を検証する

エージェントがコンテキストを維持し、条件付きロジックに従い、長い会話にわたる状態遷移を処理する能力を
テストするシナリオを作成します。

#### プロンプトインジェクションの試みに対してテストする

敵対的な入力を通じて指示を上書きしたり、機密性の高いシステム情報を抽出したりする試みに対して、エージェントがどう応答するかを
評価します。

#### 曖昧な意図の解決を評価する

エージェントが曖昧なリクエストをどの程度効果的に明確化し、矛盾する情報を処理し、ユーザーの意図が不明確な状況を
どのように切り抜けるかをテストします。

## 次のステップ

* 自動テストの設定については[CLIドキュメント](/docs/ja/eleven-agents/operate/cli)を参照してください
* 利用可能なツールを理解するには[ツール設定](/docs/ja/eleven-agents/customization/tools)を確認してください
* テスト可能なプロンプトの作成については[プロンプティングガイド](/docs/ja/eleven-agents/best-practices/prompting-guide)をお読みください