> 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 用户，评估智能体在完整多轮对话中的表现。与下一条回复测试不同，此类测试会检查整个交互是否达到了预设结果。

### 创建模拟测试

![模拟测试创建界面](/docs/_fern-img/ec2b27db7da62af2d82be756b2f830f0d0257a304d7c5ccb674c0a02ee8854ae.webp)

#### 定义场景

使用自然语言描述用户的上下文、意图和行为。模拟器会根据此
场景推动对话。

**场景示例：**

> "一名英语不流利的游客正在餐厅点餐。"

#### 设置成功条件

定义应视为通过的结果。此提示词用于评估
整个对话是否成功。

**成功条件示例：**

> "智能体确认了订单详情，处理了澄清问题，并在没有误解的情况下完成订单。"

#### 设置最大轮次

选择模拟在停止前可运行的时长。对于聚焦检查使用较低值，
对于复杂 workflow 使用较高值。

* 最小值：`1`
* 最大值：`50`
* 默认值：`5`

#### 运行并查看结果

执行测试并查看生成的对话记录。根据成功条件检查通过/失败结果，
然后迭代优化提示词、工具或智能体配置。

### 可选配置

你可以在测试配置面板中进一步调整模拟行为：

* **环境**：当智能体配置了多个环境时，选择要测试的环境。如果只有一个环境，此选择器会隐藏。
* **聊天记录**：从部分对话而非空白状态开始。这适用于测试进行中的对话和恢复行为。
* **动态变量**：将测试专用值注入智能体变量（例如用户名或订单 ID），无需更改基础智能体配置。

### 工具模拟

模拟测试支持工具模拟，让智能体在运行期间接收受控回复，而不是调用线上系统。

#### 模拟策略

* **不模拟**：不模拟任何工具。
* **模拟所有工具**：每个可模拟工具都会返回模拟回复。
* **模拟选定工具**：仅模拟你明确选择的工具。

系统工具和 workflow 工具永不模拟。

#### 回退行为

如果调用了模拟工具但未找到匹配的模拟回复，可选择以下行为之一：

* **调用真实工具**：执行真实工具调用。
* **以错误结束**：由工具返回错误回复，而不调用真实工具。

仅当至少模拟了一个工具时，才会显示回退设置。

## 下一条回复（场景）测试

下一条回复（场景）测试仅评估智能体的下一条消息，而非完整多轮结果。提供目标回复之前的对话记录，然后根据成功标准对该回复评分。

如需测试完整多轮结果，请使用[模拟测试](#simulation-testing)。

### 创建下一条回复测试

![下一条回复（场景）测试界面](/docs/_fern-img/62de63965584fd1b2368edfb204bd90495d03ba87fe137889a5f396859dc4dbc.webp)

#### 定义聊天记录

提供目标回复之前的对话记录。可以是一条
用户消息，也可以是多轮上下文。

**聊天记录示例：**

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

#### 设置成功标准

用通俗语言描述智能体的回复应达成什么目标。请明确说明
预期行为、语气和操作。

**成功标准示例：**

* 智能体应以同理心理解客户对重复扣费的沮丧
* 智能体应提出调查重复扣费问题
* 智能体应为取消订阅或解决问题提供清晰的后续步骤
* 智能体应保持专业且乐于帮助的语气

#### 提供示例

同时提供成功和失败示例，帮助评估器理解标准中的细微差别。

**成功示例：**

> "我理解重复扣费会让人很沮丧。让我立即为你查一下。我看到这个月确实有两笔扣费，我会马上为重复扣费办理退款。你还想继续取消订阅，还是希望在问题解决后继续使用？"

**失败示例：**

> "退款问题需要联系账单部门。订阅将被取消。"

#### 运行测试

执行测试。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/zh/api-reference/tests/create)创建测试，并使用[在智能体上运行测试](/docs/zh/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);
```

### 概率测试

智能体输出可能因每次运行而异。单次通过仅说明智能体 *能够* 成功；概率测试通过多次运行同一测试并报告通过率，说明它 *会* 成功的频率。

#### 多次运行测试

![测试中的分次运行控件，可选择执行次数](/docs/_fern-img/15d5a18c384bc193de794bf8cd7bd5803b9543c8a98acac6ecb2f518b9fd1679.webp)

从控制台触发测试时，可使用运行按钮上的分次运行控件选择执行次数（例如 3×、5× 或 15×）。每次运行相互独立：智能体会获得相同的聊天记录、动态变量和其他输入，但每次都会重新生成回复。

多次运行适用于单个测试、文件夹，以及运行附加到智能体的整个测试套件。它兼容全部 3 种测试类型——模拟、下一条回复（场景）和工具调用——通常最适合模拟测试，因为多轮对话覆盖范围更大，回复更可能出现变化。

#### 通过率和结果分桶

![按通过和失败分桶分组的多次运行结果，带通过率徽章](/docs/_fern-img/17b73e8c8170162270519adad3c9d732dfabdafc820e47b4ab274ca5066fd7fc.webp)

多次运行完成后，结果会以通过率汇总（例如 **4/5 通过**），并显示彩色徽章：

* **绿色** — 100% 通过
* **琥珀色** — 至少 80% 通过
* **红色** — 低于 80%

随后，单次运行会按失败原因分组，让你看到智能体 *如何* 失败，而不只是 *是否* 失败。无需滚动查看 5 份独立记录来找出差异，而是会看到类似 *“正确转接至账单部门（4 次运行）”* 和 *“虚构了一个支持电话号码（1 次运行）”* 的分组；每组都可展开查看对应记录和评估依据。

#### 何时使用

* **发布变更前** — 以概率方式重新运行附加的测试，确认可靠性没有下降（例如从 95% 降至 60%）。
* **诊断不稳定行为** — 单次失败可能只是噪声；若 5 次中失败 1 次且有明确命名的失败分桶，则是可复现且需要修复的问题。
* **调优提示词和工具** — 迭代配置并并排比较通过率，而不是依赖一次性运行。

#### 通过 API 或 SDK 以概率方式运行

在[运行测试](/docs/zh/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/zh/eleven-agents/operate/cli)，设置自动化测试
* 探索[工具配置](/docs/zh/eleven-agents/customization/tools)，了解可用工具
* 阅读[提示词指南](/docs/zh/eleven-agents/best-practices/prompting-guide)，学习编写可测试的提示词