> 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.

# 工具调用音效

## 概述

工具调用音效可在工具执行期间提供环境音频反馈，让对话体验更自然、更有参与感。当智能体执行工具（例如通过 API 获取数据或处理请求）时，这些音效可填补静默时刻，并让用户知道智能体正在处理。

ElevenLabs Agents 支持多种内置环境音效，可在工具级别和集成级别进行配置，让你精细控制对话期间音效的播放时机和方式。

> **Note**
>
> 工具调用音效仅在工具执行期间播放。如需持续的背景音，请参阅 [音频 环境](/docs/zh/eleven-agents/customization/voice/audio-environment)。

## 使用场景

工具调用音效尤其适用于以下情况：

* **API 调用需要时间完成**：从外部服务获取数据时播放环境音乐或打字声
* **长时间运行的操作**：在数据库查询、复杂计算或第三方集成期间提供音频反馈
* **自然的对话流程**：填补对话空档，避免尴尬的沉默
* **用户预期**：让用户知道智能体正在处理请求，而非遇到技术问题

> **Info**
>
> 工具调用音效为可选功能。如需静默执行工具，只需将工具调用音效设置保留为“无”。

## 可用音效

ElevenLabs 提供以下环境音频选项：

| 音效类型     | 说明          | 最适合              |
| -------- | ----------- | ---------------- |
| 无        | 工具执行期间不播放音效 | 快速操作、静默 workflow |
| 打字声      | 键盘打字音效      | 搜索查询、文本处理        |
| 电梯音乐 1-4 | 轻快的背景音乐     | 较长等待时间、常规使用      |

> **Tip**
>
> 配置工具调用音效时，可在控制台点击下拉菜单旁的播放按钮预览各个音效。

## 配置

工具调用音效可在两个位置配置，工具级别配置优先：

### 工具级别配置

在智能体的工具设置中为单个工具配置音效。

#### 通过控制台更新

#### 前往工具配置

在智能体设置的 **智能体** 部分，选择要配置的工具，或创建新工具。

#### 配置工具调用音效

滚动至工具配置底部的 **工具调用音效** 部分。

![工具调用音效下拉菜单](/docs/_fern-img/093fd6c380e2d51f0b8dbe152377a35e1e4e0e422638519910016b9f1551233d.webp)

从下拉菜单中选择音效：

* **无**：不播放音效
* **打字声**：键盘打字效果
* **电梯音乐 1-4**：多种环境背景音乐选项

#### 配置音效行为

如果已选择音效（而非“无”），会看到额外的 **音效行为** 选项：

![音效行为下拉菜单](/docs/_fern-img/00c7f6ddfb1b0240a900c8d6814c8706e045500d92f6a6c263d4a7c962e24fbe.webp)

选择音效播放时机：

* **伴随预先语音**：仅当智能体在执行工具前发言时播放音效
* **始终播放**：每次工具执行期间都播放音效，无论智能体是否先发言

#### 保存配置

点击 **保存** 应用工具调用音效设置。

#### 通过 CLI 更新

#### 拉取工具配置

```bash
elevenlabs tools pull
```

#### 编辑 \`tool_configs/\<tool-name>.json\`

设置 `tool_call_sound` 和 `tool_call_sound_behavior`：

```json
{
  "type": "webhook",
  "name": "get_weather",
  "tool_call_sound": "typing",
  "tool_call_sound_behavior": "auto"
}
```

**伴随预先语音** 使用 `"auto"`，**始终播放** 使用 `"always"`。

#### 推送更改

```bash
elevenlabs tools push
```

#### 通过 API 更新

```python
from elevenlabs import ElevenLabs, ToolRequestModel

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.tools.update(
    tool_id="tool_7101k5zvyjhmfg983brhmhkd98n6",
    request=ToolRequestModel(
        tool_config={
            "type": "webhook",
            "name": "get_weather",
            "description": "Gets current weather data",
            "tool_call_sound": "typing",
            "tool_call_sound_behavior": "auto",
            "api_schema": {
                "url": "https://api.weather.com/data",
                "method": "GET",
            },
        },
    )
)
```

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.tools.update("tool_7101k5zvyjhmfg983brhmhkd98n6", {
  toolConfig: {
    type: "webhook",
    name: "get_weather",
    description: "Gets current weather data",
    toolCallSound: "typing",
    toolCallSoundBehavior: "auto",
    apiSchema: {
      url: "https://api.weather.com/data",
      method: "GET",
    },
  },
});
```

### 集成级别配置

对于通过集成创建的工具（MCP 服务器、API 集成等），可在集成级别设置默认工具调用音效：

#### 前往集成设置

前往 **智能体设置 > 集成**，然后选择相应集成。

#### 配置默认音效

在集成概览中，找到 **工具调用音效** 设置。

![工具调用音效集成下拉菜单](/docs/_fern-img/9c4c33501c814c3d124d76060853ee6eb8c59c8b4f0cc494d16267e9fe5cf56b.webp)

选择默认音效。除非在工具级别覆盖，否则该音效将应用于此集成的所有工具。

#### 在工具级别覆盖（可选）

可在单个工具设置中配置工具调用音效，以覆盖特定工具的集成级别默认设置。

## 音效行为选项

音效行为设置决定工具调用音效在对话期间何时播放：

### 伴随预先语音（自动）

**默认行为**。仅当智能体在使用工具前发言时播放音效。

**示例场景：**

```
User: "What's the weather in Tokyo?"
Agent: "Let me check that for you..." [typing sound plays while fetching weather data]
Agent: "It's currently 72 degrees and sunny in Tokyo."
```

**适用情况：**

* 希望仅在智能体确认请求后播放音效时
* 需要更自然的对话流程，避免用户说话后出现尴尬沉默时
* 工具执行紧随智能体发言时

### 始终播放

每次工具执行期间都会播放音效，无论智能体是否事先发言。

**示例场景：**

```
User: "Check my order status"
[typing sound plays immediately while fetching order data]
Agent: "Your order #12345 shipped yesterday and will arrive tomorrow."
```

**适用情况：**

* 操作总会花费明显时间时
* 希望每次工具调用都提供一致的音频反馈时
* 可能无需智能体确认的后台操作时

> **Warning**
>
> 如果选择“始终播放”，即使智能体在使用工具前未发言，也会播放音效。这可能导致用户说完话后立即播放音效，在某些对话场景中会显得突兀。

## 最佳实践

#### 根据工具执行时间匹配音效

对于快速操作（\< 1 秒），可考虑使用“无”或打字声。对于较长操作（> 3 秒），电梯音乐选项可提供更好的用户体验。

#### 对已确认的操作使用“伴随预先语音”

当智能体在执行请求前明确确认时，使用“伴随预先语音”行为可打造自然的对话流程：

**`System prompt`**

```plaintext System prompt
When users request information, first acknowledge their request before using tools.
For example: "Let me check that for you..." then call the appropriate tool.
```

#### 在集成级别配置以保持一致

如果同一集成中有多个工具，请在集成级别配置工具调用音效，确保所有相关工具的音频反馈保持一致。

#### 使用真实延迟进行测试

使用真实的 API 延迟测试工具调用音效，确保音频反馈符合用户预期。请考虑：

* API 的网络延迟
* API 处理时间
* 用户的地理分布

#### 平衡中断处理

如果智能体支持用户中断，用户中断时会自动停止工具调用音效。请确保对话流程能妥善处理这种情况。

## 配置示例

### 搜索智能体

**使用场景**：搜索知识库或数据库的智能体

**配置**：

* 工具调用音效：**打字声**
* 音效行为：**伴随预先语音**
* 系统提示词包含：*“当用户提问时，在调用搜索工具前说‘让我帮你搜索一下’。”*

### 客户服务智能体

**使用场景**：检查订单状态、库存或客户记录的智能体

**配置**：

* 工具调用音效：**电梯音乐 3**
* 音效行为：**始终播放**
* 原因：操作可能需要 2-5 秒，背景音乐比静默提供更好的体验

### 多步骤 workflow

**使用场景**：连续执行多个工具调用的智能体

**配置**：

* 第一个工具：**打字声**，使用 **伴随预先语音**
* 后续工具：**电梯音乐 1**，使用 **始终播放**
* 系统提示词编排：*“先确认请求，然后依次执行工具。”*

## 故障排除

### 音效未播放

**可能原因：**

1. **无预先语音**：如果使用“伴随预先语音”行为，智能体必须在工具执行前发言。请更新系统提示词以包含确认语。
2. **执行过快**：如果工具在约 500ms 内完成，音效可能没有足够时间明显播放。

## 相关资源

* [Webhook 工具](/docs/zh/eleven-agents/customization/tools/webhook-tools) - 了解如何配置 Webhook 工具
* [客户端工具](/docs/zh/eleven-agents/customization/tools/client-tools) - 了解客户端工具执行
* [系统工具](/docs/zh/eleven-agents/customization/tools/system-tools) - 探索内置平台工具
* [最佳实践](/docs/zh/eleven-api/guides/how-to/websockets/multi-context-web-socket) - 构建对话式智能体的通用最佳实践