---
title: "内置工具"
description: "提示 ThunderPhone 智能体结束通话、转接来电者、操作按键菜单、在保持等待时等待、搜索知识、播放声音以及发送电子邮件。"
---

内置工具可让智能体执行常见通话操作，无需连接您自己的 API。大多数工具会自动提供；电子邮件、声音和知识搜索仅在您配置相关设置或来源后显示。请在提示词中告知智能体何时使用各项操作。

| 工具 | 用途 | 启用方式 | 支持的通话 |
| --- | --- | --- | --- |
| `end_call` | 结束已完成的对话 | 始终可用 | 电话、浏览器 Talk、小组件、模拟和 Realtime |
| `transfer_call` | 转接电话来电者 | 在提示词中配置路由 | 常规电话；带有 `call_events` 的内联 Realtime 可使用冷转接。已保存智能体的 Realtime 不包含此功能。 |
| `send_keypad_input` | 在电话菜单中按键 | 在常规电话中始终可用 | 电话；带有 `call_events` 的内联外呼 Realtime。已保存智能体的 Realtime 不包含此功能。 |
| `no_response` | 在自动菜单播报或来电者思考时继续聆听；来电者要求智能体等待时，智能体只会回答“当然。” | 始终可用 | 所有通话类型 |
| `wait_on_hold` | 静默等待对方返回 | 包含在外呼通话中 | 外呼电话和外呼内联 Realtime 会话 |
| `search_knowledge_base` | 根据已附加的来源回答 | 为智能体附加知识 | 带有已附加知识的已保存智能体通话 |
| `play_sound` | 播放已配置的通知声音 | **高级 → 工具声音** | 已保存智能体通话 |
| `send_email` | 向一个固定收件人发送电子邮件 | **高级 → 发送电子邮件** | 已保存智能体通话 |

## `end_call`

当提示词指示模型这样做时，结束当前通话。默认可用，且没有智能体设置。

请在提示词中写明条件以及任何必要的告别语：

```text
When the caller confirms they need nothing else, say goodbye and end the call.
```

由模型结束的通话具有 `end_reason: "ai_hangup"`，包括在通话时长限制警告后结束的通话。只有在时长限制先达到时，通话才会以 `max_duration` 结束；当预付余额用尽时，则以 `balance_exhausted` 结束。

## `transfer_call`

将电话来电者转接至模型提供的固定号码。冷转接会立即进行。筛选式热转接会在连接双方之前私下呼叫目标号码。热转接需要一个已验证、已导入且能够拨打出站电话的 VoIP 号码。

请在提示词中写明目标号码和准确的路由条件：

```text
If the caller asks for billing, transfer them to +15551234567.
```

成功的冷转接会显示 `end_reason: "ai_transfer"`；完成的热转接会显示 `end_reason: "ai_warm_transfer"`。热转接尝试失败时，控制权将返回智能体，因此通话后续的结束方式决定其结束原因。在非电话会话中，转接请求会改为结束该会话。

有关控制台和 API 设置、路由、筛选、失败处理、限制及测试，请参阅[转接通话](/zh/guides/call-transfers)。

## `send_keypad_input`

向电话线路发送 DTMF（电话键盘）数字 `0`–`9`、`*` 和 `#`。模型使用此工具导航 IVR，即要求来电者按键的自动菜单。默认可用，且没有智能体设置。

请告知模型可以导航哪些菜单，以及所需值来自何处。不要要求它猜测菜单选项：

```text
Follow the phone menu for account status. Press a key only after the menu
states what that key does. Enter the account number supplied by the caller.
```

平台会移除不支持的字符，并按顺序发送有效数字。如果没有剩余有效数字，或通话无法发送键盘输入，失败信息将返回给智能体，以便其恢复处理。

## `no_response`

当自动系统仍在说话或要求智能体继续聆听时，以及来电者自言自语（“嗯，让我想想”）或转向与他人交谈时，让智能体保持静默。当来电者要求智能体在其处理某事时等待（“等一下”“让我查一下”“您能稍等一下吗？”），且未提供其他需要回答的内容时，智能体只会说“当然。”（不会说“您慢慢来”），然后等待来电者再次说话。如果线路保持安静，智能体的静默主动询问仍会照常运行，并且始终会说出来。此功能不适用于真人的问候、提问或真正的保持等待队列。默认可用，且没有智能体设置。

如果您的提示词指定了来电者请求稍等时智能体应说什么，则以提示词为准。

通常，内置说明已足够。对于大量使用 IVR 的通话，请在提示词中强化这一界限：

```text
Stay silent while a phone menu is still speaking. Answer a live person as soon
as they address you.
```

此操作不会结束通话。

## `wait_on_hold`

使外呼智能体进入静默保持状态，直到真人返回。
模型仅在对方明确表示要让智能体保持等待后使用此工具。
它会自动用于外呼通话，且没有控制台设置。

```text
If a person explicitly puts you on hold, wait silently. When they return,
continue from the question you were discussing.
```

不要提示智能体针对 IVR 的“请稍候”消息使用此工具。默认情况下，保持最长可持续
15 分钟。对于普通外呼通话，`POST /v1/call`
接受正整数 `max_hold_seconds`；内联 Realtime 将
`max_hold_seconds` 限制为 10–900 秒。如果对方
返回，智能体会继续通话，而不会更改通话的结束原因。如果达到时限，
平台会以 `end_reason: "ai_hangup"` 结束通话。

## `search_knowledge_base`

搜索附加到智能体的文档并返回相关段落。附加知识库或单个知识文档
以启用此工具，然后告知模型哪些回答必须来自这些来源：

```text
Search the knowledge base before answering policy questions. If the first
search is inconclusive, try once more with different key terms.
```

如果搜索失败，结果会返回给智能体。有关控制台和 API 设置，请参阅[知识
库](/zh/guides/knowledge-base)。

## `play_sound`

在同一轮中的任何语音之后播放智能体配置的通知音。在控制台中，将**高级 → 工具音效**设置为**提示音**、**叮咚**
或**哔声**，然后部署智能体。**无**会移除此工具。

使用 [Agents API](/api-reference/agents) 时，将 `play_sound_asset` 暂存为
`"chime"`、`"ding"` 或 `"beep"`，然后部署。将其设为 `""` 可禁用
此工具。

```text
After confirming that an appointment was saved, say "You're all set" and play
the notification sound.
```

播放失败会返回给智能体，但不会结束通话。

## `send_email`

向智能体所有者配置的唯一收件人发送纯文本电子邮件。
模型提供主题和正文。它永远不会看到收件人参数，
也无法选择或更改地址。

在控制台中，启用**高级 → 发送电子邮件**，保存收件人地址，
然后部署智能体。使用 [Agents API](/api-reference/agents) 时，同时暂存
`send_email_enabled: true` 和非空的 `send_email_recipient`，然后部署。
在提示词中定义触发条件和所需内容：

```text
When the caller asks to leave a message, collect their name, callback number,
and message. Read the details back for confirmation, then email them.
```

一次通话最多可尝试发送三封电子邮件。每个主题最多 300
个字符，每个正文最多 20,000 个字符。缺少配置、内容无效、
单次通话限制以及投递失败都会返回给智能体。
投递失败仍会占用三次尝试中的一次。

在广泛部署前，请先使用受控收件人进行测试。浏览器 Talk 和
模拟会发送真实电子邮件；没有试运行模式。

## 兼容性说明

**高级 → 不可打断的告知**设置和旧版
`speak_uninterruptible_enabled` 字段保留用于兼容性，但启用它们不会产生任何效果。
请保持该设置关闭；任何提示词都无法启用此工具。

如需在通话开始时进行必需告知，请使用**同意声明**。它会在普通对话前
逐字播放，且无法被打断。请参阅[通话录音同意法律](/zh/guides/recording-consent-laws)。

## 测试和监控内置工具

使用浏览器 Talk 或模拟来检查提示词、知识库搜索、声音和电子邮件。
这些环境无法复现电话网络行为。请在外呼电话中测试按键导航和保持，
并使用符合条件的已导入 VoIP 号码在真实通话中测试完整的热转接。Realtime
支持范围如上表所示。

## 通话、定价和 Webhook

内置操作不收取按次使用的工具费用。常规通话和服务商费用仍然适用；请参阅[定价](/zh/guides/pricing)。其调用和结果可能会显示在已完成的转写记录中，但不会触发 `telephony.tool` 或 `web.tool`。
这些事件适用于[用户定义函数](/zh/tools/overview)。只有已完成的挂断或转接才会更改通话的 `end_reason`；其他失败会返回给智能体。有关通话记录，请参阅[完成 Webhook](/zh/webhooks/call-complete)。