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

# Webhook 工具

**工具**让智能体能够连接外部数据和系统。你可以定义一组智能体可访问的工具，智能体会根据对话情况在适当时使用这些工具。

## 概述

许多应用需要智能体调用外部 API 来获取实时信息。工具让智能体能够调用第三方应用的外部函数，从而获取实时信息。

以下是一些适合使用工具的场景：

* **获取数据**：让智能体在回复用户前，从任何支持 REST 的数据库或第三方集成中检索实时数据。
* **执行操作**：让智能体根据对话触发需要身份验证的操作，例如安排会议或发起订单退货。

> **Info**
>
> 如需与应用 UI 交互或触发客户端事件，请改用 [客户端工具](/docs/zh/eleven-agents/customization/tools/client-tools)。

## 工具配置

ElevenLabs 智能体可配备工具来与外部 API 交互。与传统请求不同，智能体会根据对话和你提供的参数说明，动态生成查询参数、请求体参数和路径参数。

所有工具配置和参数说明都能帮助智能体判断**何时**以及**如何**使用这些工具。为有效编排工具使用，请更新智能体的系统提示词，指定调用这些工具的顺序和逻辑，包括：

* **使用哪个工具**以及使用条件。
* 工具正常运行所需的**参数**。
* **如何处理**响应。

\


#### 配置

定义高级别的 `Name` 和 `Description` 来说明工具用途。这有助于 LLM 理解工具并知道何时调用它。

> **Info**
>
> 如果 API 需要路径参数，请用花括号 `{}` 将变量包裹在 URL 路径中，例如：`/api/resource/{id}`，其中 `id` 是路径参数。

![配置](/docs/_fern-img/fb6e6619e4e7a5f19c2a86f9c2a489f5cb33cfb0883c14a06f0eec3cb35d71d5.webp)

#### 身份验证

通过添加自定义请求头，或通过身份验证连接使用现成的身份验证方法进行配置。

![工具身份验证](/docs/_fern-img/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630.webp)

#### 请求头

指定请求中需要包含的所有请求头。

![请求头](/docs/_fern-img/9c8c3f2d42f84a6e40922a4c777199e79646b174fa51b9e4d5b21695d7da3f66.webp)

#### 路径参数

用花括号 `{}` 将变量包裹在 URL 路径中：

* **示例**：`/api/resource/{id}`，其中 `id` 是路径参数。

![路径参数](/docs/_fern-img/12dde95654a12f8fd5894eefe2bdbebb8b819072d3589ed32ddd578997f53c1d.webp)

#### 请求体参数

指定请求中需要包含的所有请求体参数。

![请求体参数](/docs/_fern-img/17627460d24323cc40f461196625d34a5825dbe85d684618be0bc46b11ff9205.webp)

### 内容类型

配置请求体编码格式：

* **JSON**（默认）：将请求体参数作为 `application/json` 发送
* **URL 编码**：将请求体参数作为 `application/x-www-form-urlencoded` 发送

与需要提交表单数据的 API 集成时，URL 编码格式非常有用，例如：

* 仅接受表单编码请求的旧版系统
* OAuth 令牌端点
* 支付处理 API
* 对内容类型有特定要求的第三方集成

> **Info**
>
> 内容类型设置仅适用于包含请求体参数的 POST、PUT 和 PATCH 请求。

#### 查询参数

指定请求中需要包含的所有查询参数。

![查询参数](/docs/_fern-img/4127f87fe066cdaa71df0e6f75caa24ec8174e7d156c74b3c62ea9df98b9712e.webp)

#### 动态变量赋值

指定从工具响应中更新的动态变量，供后续对话使用。

![查询参数](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp)

## 指南

本指南将创建一个天气智能体，可为任何地点提供实时天气信息。智能体会利用地理知识将地点名称转换为坐标，并获取准确的天气数据。

#### 配置天气工具

天气工具向 `https://api.open-meteo.com/v1/forecast` 发送 GET 请求，并使用 LLM 提供的 `latitude` 和 `longitude` 作为路径参数。

#### 通过控制台添加

在智能体设置页面的 **Agent** 部分，选择 **Add Tool**。选择 **Webhook** 作为工具类型，然后使用以下值配置天气 API 集成：

| 字段  | 值                                                                                                                                                                                                                                                                                                                                                                              |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 名称  | get_weather                                                                                                                                                                                                                                                                                                                                                                    |
| 说明  | 获取某个地点的当前天气预报                                                                                                                                                                                                                                                                                                                                                                  |
| 方法  | GET                                                                                                                                                                                                                                                                                                                                                                            |
| URL | [https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\&current=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m](https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\&current=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m) |

添加两个值类型为 `LLM Prompt` 的路径参数：

| 数据类型   | 标识符       | 说明         |
| ------ | --------- | ---------- |
| string | latitude  | 所请求地点的纬度坐标 |
| string | longitude | 所请求地点的经度坐标 |

#### 通过 CLI 添加

#### 创建工具配置文件

将以下内容保存为 `tool_configs/get_weather.json`：

```json
{
  "type": "webhook",
  "name": "get_weather",
  "description": "Gets the current weather forecast for a location",
  "api_schema": {
    "url": "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m",
    "method": "GET",
    "path_params_schema": {
      "latitude": {
        "type": "string",
        "description": "The latitude coordinate for the requested location"
      },
      "longitude": {
        "type": "string",
        "description": "The longitude coordinate for the requested location"
      }
    }
  }
}
```

#### 添加工具

```bash
elevenlabs tools add "get_weather" --type "webhook" --config-path ./tool_configs/get_weather.json
```

#### 从智能体引用工具

编辑 `agent_configs/<agent-name>.json`，将工具 ID 添加到 `conversation_config.agent.prompt.tool_ids`，然后推送：

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### 通过 API 添加

```python
from elevenlabs import ElevenLabs, ToolRequestModel

elevenlabs = ElevenLabs()

tool = elevenlabs.conversational_ai.tools.create(
    request=ToolRequestModel(
        tool_config={
            "type": "webhook",
            "name": "get_weather",
            "description": "Gets the current weather forecast for a location",
            "api_schema": {
                "url": "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m",
                "method": "GET",
                "path_params_schema": {
                    "latitude": {
                        "type": "string",
                        "description": "The latitude coordinate for the requested location",
                    },
                    "longitude": {
                        "type": "string",
                        "description": "The longitude coordinate for the requested location",
                    },
                },
            },
        }
    )
)

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "agent": {"prompt": {"tool_ids": [tool.id]}},
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

const tool = await elevenlabs.conversationalAi.tools.create({
  toolConfig: {
    type: "webhook",
    name: "get_weather",
    description: "Gets the current weather forecast for a location",
    apiSchema: {
      url: "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m",
      method: "GET",
      pathParamsSchema: {
        latitude: {
          type: "string",
          description: "The latitude coordinate for the requested location",
        },
        longitude: {
          type: "string",
          description: "The longitude coordinate for the requested location",
        },
      },
    },
  },
});

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    agent: { prompt: { toolIds: [tool.id] } },
  },
});
```

> **Warning**
>
> 此工具不需要 API 密钥。如果需要，应通过请求头传递并存储为密钥。

#### 编排

使用以下系统提示词配置智能体，以智能处理天气查询：

**`系统提示词`**

```plaintext 系统提示词
You are a helpful conversational agent with access to a weather tool. When users ask about
weather conditions, use the get_weather tool to fetch accurate, real-time data. The tool requires
a latitude and longitude - use your geographic knowledge to convert location names to coordinates
accurately.

Never ask users for coordinates - you must determine these yourself. Always report weather
information conversationally, referring to locations by name only. For weather requests:

1. Extract the location from the user's message
2. Convert the location to coordinates and call get_weather
3. Present the information naturally and helpfully

For non-weather queries, provide friendly assistance within your knowledge boundaries. Always be
concise, accurate, and helpful.

First message: "Hey, how can I help you today?"
```

> **Success**
>
> 通过询问不同地点的天气来测试智能体。智能体应能处理具体地点（“东京天气怎么样？”），并在一般性查询后要求澄清（“今天天气怎么样？”）。

## 支持的身份验证方法

ElevenLabs Agents 支持多种身份验证方法，可安全地将工具连接到外部 API。身份验证方法在智能体设置中配置，随后可按需连接到各个工具。

![工作区身份验证连接](/docs/_fern-img/131f7e017f01eaba444cddc672efdb77415db1a4c3a39f05b92a1678c5cd68f1.webp)

配置完成后，你可以将这些身份验证方法连接到工具，并在工具配置中管理自定义请求头：

![工具身份验证连接](/docs/_fern-img/c018c5bf11266512a6d6157e33274b1a12f8c20768e5ab18da0f20f933f8aea9.webp)

#### OAuth2 客户端凭据

自动处理 OAuth2 客户端凭据流程。使用客户端 ID、客户端密钥和令牌 URL（例如 `https://api.example.com/oauth/token`）进行配置。可选择以逗号分隔的值指定作用域和其他 JSON 参数。在智能体设置页面的 **Agent** 部分，点击 **Workspace Auth Connections** 中的 **Add Auth** 进行设置。

#### OAuth2 JWT

使用 JSON Web Token 身份验证来实现 OAuth 2.0 JWT Bearer 流程。需要 JWT 签名密钥、令牌 URL 和算法（默认：HS256）。配置 JWT 声明，包括签发者、受众和主体。可选择设置密钥 ID、过期时间（默认：3600 秒）、作用域和额外参数。在智能体设置页面的 **Agent** 部分，点击 **Workspace Auth Connections** 中的 **Add Auth** 进行设置。

#### 基本身份验证

适用于支持 HTTP Basic Auth 的 API 的简单用户名和密码身份验证。在智能体设置页面的 **Agent** 部分，点击 **Workspace Auth Connections** 中的 **Add Auth** 进行设置。

#### Bearer 令牌

基于令牌的身份验证，会将 Bearer 令牌值添加到请求头。通过在工具配置中添加请求头、选择 **Secret** 作为请求头类型，然后点击 **Create New Secret** 进行配置。

#### 自定义请求头

可为专有身份验证方法添加任意名称和值的自定义身份验证请求头。通过在工具配置中添加请求头，并指定其**名称**和**值**进行配置。

## 最佳实践

#### 使用直观的工具名称和详细说明

如果发现助手没有调用正确的工具，可能需要更新工具名称和说明，让助手更清楚地理解何时应选择各个工具。避免使用缩写或首字母缩略词来简化工具和参数名称。

还可以详细说明应在何时调用工具。对于复杂工具，应为每个参数添加说明，帮助助手了解需要向用户询问哪些信息来收集该参数。

#### 使用直观的工具参数名称和详细说明

为工具参数使用清晰且描述性强的名称。适用时，请在说明中指定参数的预期格式（例如日期采用 YYYY-mm-dd 或 dd/mm/yy）。

#### 考虑在助手的系统提示词中提供有关如何及何时调用工具的补充信息

在系统提示词中提供清晰指示，可显著提高助手调用工具的准确性。例如，可使用以下指示引导助手：

```plaintext
Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.
```

为复杂场景提供上下文。例如：

```plaintext
Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.
```

#### LLM 选择

> **Warning**
>
> 使用工具时，建议选择 GPT 5.2、Gemini-2.5-Flash 或
> Claude Sonnet 4.5 等高智能模型，并避免使用 Gemini-2.0-Flash。

请注意，LLM 的选择会影响函数调用的成功率。某些 LLM 可能难以从对话中提取相关参数。

## 工具调用音效

你可以配置在工具执行期间播放的环境音频，以改善用户体验。详细了解 [工具调用音效](/docs/zh/eleven-agents/customization/tools/tool-configuration/tool-call-sounds)。