Webhook 工具

将助手连接到外部数据和系统。

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

概述

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

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

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

如需与应用 UI 交互或触发客户端事件，请改用客户端工具。

工具配置

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

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

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

配置

身份验证

请求头

路径参数

请求体参数

查询参数

动态变量赋值

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

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

指南

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

配置天气工具

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

通过控制台添加

通过 CLI 添加

通过 API 添加

在智能体设置页面的 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

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

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

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

编排

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

系统提示词

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?"

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

支持的身份验证方法

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

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

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）。

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

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

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

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

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

LLM 选择

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

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

工具调用音效

你可以配置在工具执行期间播放的环境音频，以改善用户体验。详细了解工具调用音效。