手动添加工具

本文介绍如何在 PBX 上手动填写工具配置以添加一个自定义工具。

前提条件

从第三方 API 获取以下所需信息：

项目 说明
端点 URL API 请求地址 (必须使用 HTTPS)。
请求方法 GET、POST、PUT、PATCH 或 DELETE
参数 API 请求所需的路径参数、头域参数、查询参数或请求体参数。
认证凭证 若第三方 API 要求认证，获取其静态凭证 (如 API 密钥、基本身份认证的用户名和密码、静态 Bearer Token)。
注： 不支持动态认证 (如 OAuth 2.0)，因其需要动态获取 token，无法预先配置。

操作步骤

  1. 登录 PBX 管理平台，进入 AI > AI接待员 > 工具。
  2. 点击 添加，添加并配置一个工具。
    提示： 可从工具页面右上角无缝切换 表单编辑 和 JSON 编辑 视图。

  3. 配置基本信息。

    设置 说明 JSON 字段 & 示例
    名称 为工具设置一个唯一的名称。
    注： 仅允许使用数字、字母、下划线、(_) 和连字符 (-)。
    		 
    "basic.name": "query_order"
    请求方式 选择 HTTP 请求方法。 
    "basic.method": "GET"  //有效值：GET/POST/PUT/PATCH/DELETE
    URL 填入 API 端点 URL。
    注：
    • URL 必须以 https:// 开头。
    • URL 中最多可添加 5 个路径参数 ({path_param})。参数名仅可包含数字、字母、下划线 _、非连续的点号 . 以及符号 @。在后续配置中可设置 AI 接待员根据对话内容动态获取这些参数的值。
    		 
    "basic.url":"https://jsonplaceholder.typicode.com/posts/{order_id}"
    备注 可选。输入备注，以便快速识别工具的用途。 
    "basic.remark": "查询订单状态工具"
    描述 输入自然语言描述，指示 AI 接待员何时使用该工具以及如何调用。 
    "basic.description": "当客户要求“查询订单”、“查看订单状态”或“获取订单详情”时使用此工具，从对话中提取数字订单号
(例如, '订单 3' → order_id=3)。"
  4. 配置执行规则。

    设置 说明 JSON 字段 & 示例
    工具执行期间禁止打断

    勾选后，工具运行时来电者无法打断 AI 接待员。

    		 
    "response_settings.disable_interruptions":true
// true = 勾选, false = 未勾选
    执行工具前始终播报语音提示 勾选后，AI 接待员在执行工具前始终会播报提示语 (例如：“正在为您查询”)。

    未勾选时，AI 接待员会根据工具最近的执行延迟自动判断是否播报提示语。例如，工具响应快则跳过提示语，响应慢则先播报提示语。

    		 
    "response_settings.force_pre_tool_speech":true
// true = 勾选, false = 未勾选
    执行模式 决定工具的执行行为。
    • 大模型请求时立即执行：AI 接待员请求后立即执行。
    • 语音提示后执行：在 AI 接待员播报语音提示后执行。
    • 异步：工具在后台运行，不打断对话。AI 接待员不等待响应，继续说话。
      注： 此模式适合无需响应结果的操作，如发送邮件或触发外部工作流。
    		 
    "response_settings.execution_mode":"lazy"
// 有效值：immediate/lazy/async
    工具执行音效 指定工具执行时的背景音效。
    注： 当 执行模式 为 异步 时，此设置不可用。
    • 无：无背景音效。
    • 键盘打字音：播放打字音效。
    • 音乐 1 - 音乐 4：播放内置的背景音乐。
    		 
    "response_settings.tool_call_sound":"Typing"
// 有效值：None/Typing/Music 1/Music 2/Music 3/Music 4
    音效播放规则
    指定何时播放音效。
    注： 当 执行模式 为 异步 或 工具执行音效 为 无 时，此设置不可用。
    • 仅在语音提示后播放：仅当 AI 接待员执行工具前先播报语音提示时，才播放音效。
    • 始终播放：每次执行工具时都播放音效。
    		 
    "response_settings.sound_behavior":"with_pre_speech"
// 有效值：with_pre_speech/always_play
    响应超时时长（s） 设置响应超时时长 (单位：秒)。
    注： 取值范围为 5 到 120 秒。
    		 
    "response_settings.response_timeout":20
  5. 配置请求参数。
    路径参数
    路径参数是使用 {} 嵌入在 URL 路径中的变量，系统自动从工具的 API 端点 URL 中提取。
    设置 说明 JSON 字段 & 示例
    参数 参数名。该名称从 URL 路径中自动识别，且为只读。 
    "path_params[].parameter":"id"
    数据类型 选择参数的数据类型。
    • String：文本类信息，如姓名、邮箱、地址。允许字母、数字和特殊字符。
    • Boolean：是/否类信息，如是否订阅通知、是否接受条款。
    • Integer：不含小数的整数，如数量、年龄、评分。
    • Number：可为整数或小数的数值，如订单金额、折扣率、产品重量。
    		 
    "path_params[].data_type":"String"
// 有效值：Boolean/Integer/Number/String
    取值逻辑
    决定参数值的获取方式。
    • 固定值：使用 值 字段中指定的固定参数值。
    • 由大模型生成：AI 接待员从对话中动态提取或生成参数值。
    		 
    "path_params[].value_logic":"llm"
// 有效值：constant/llm
    值 指定参数的固定值。
    注： 仅当 取值逻辑 为 固定值 时，此设置才可用。
    		 
    "path_params[].constant_value":"123"
// 当 data_type 为 Boolean 时，值应为 True 或 False。
    描述 输入自然语言描述，以指示 AI 接待员如何从通话中提取或生成参数值。
    注： 仅当 取值逻辑 为 由大模型生成 时，此设置才可用。
    		 
    "path_params[].description": "从客户请求中提取订单 ID，例如客户说 "order 3"，则提取值为 3。"
    可选项 可选。点击 添加选项 添加预定义值。当提取的信息匹配指定选项时，AI 接待员可直接选择。
    注：
    • 仅当 数据类型 为 String 且 取值逻辑 为 由大模型生成 时，此设置才可用。
    • 支持添加最多 10 个选项。
    		 
    "path_params[].optional_values": ["standard", "express", "overnight"]
    头域
    添加并指定需要包含在请求中的请求头。
    注：
    • 仅支持静态请求头值。如要在请求头中传递认证信息，需使用静态认证凭证 (如 Authorization: Bearer <Your_API_KEY>)。
    • 支持添加最多 20 个请求头。

    设置 说明 JSON 字段 & 示例
    参数 请求头名称。 
    "headers[].parameter": "Content-Type"
    值 固定的请求头值。
    注： 不支持动态值。
    		 
    "headers[].value": "application/json"
    Query 参数
    添加并指定需要包含在请求中的查询参数。
    注： 支持添加最多 10 个查询参数。
    设置 说明 JSON 字段 & 示例
    参数 参数名称。
    注： 仅允许输入数字、字母、下划线 _、非连续的点号 . 以及符号 @。
    		 
    "query_params[].parameter": "status"
    必需 该参数是否必需。

    若勾选，当来电者未提供此信息时，AI 接待员将反复进行提示。 

    "query_params[].required": false
    数据类型 选择参数的数据类型。
    • String：文本类信息，如姓名、邮箱、地址。允许字母、数字和特殊字符。
    • Boolean：是/否类信息，如是否订阅通知、是否接受条款。
    • Integer：不含小数的整数，如数量、年龄、评分。
    • Number：可为整数或小数的数值，如订单金额、折扣率、产品重量。
    		 
    "query_params[].data_type": "String"
// 有效值：Boolean/Integer/Number/String
    取值逻辑
    决定参数值的获取方式。
    • 固定值：使用 值 字段中指定的固定参数值。
    • 由大模型生成：AI 接待员从对话中动态提取或生成参数值。
    		 
    "query_params[].value_logic": "llm"
// 有效值：constant/llm
    值 指定参数的固定值。
    注： 仅当 取值逻辑 为 固定值 时，此设置才可用。
    		 
    "query_params[].constant_value": "active"
// 当 data_type 为 Boolean 时，值应为 True 或 False。
    描述 输入自然语言描述，以指示 AI 接待员如何从通话中提取或生成参数值。
    注： 仅当 取值逻辑 为 由大模型生成 时，此设置才可用。
    		 
    "query_params[].description": "从客户请求中提取状态筛选条件，例如客户说 "show me active orders"，则提取值为 "active"。"
    可选项 可选。点击 添加选项 添加预定义值。当提取的信息匹配指定选项时，AI 接待员可直接选择。
    注：
    • 仅当 数据类型 为 String 且 取值逻辑 为 由大模型生成 时，此设置才可用。
    • 支持添加最多 10 个选项。
    		 
    "query_params[].optional_values": ["active", "pending", "completed", "cancelled"]
    Body 参数
    添加并指定需要包含在请求中的 JSON Body 参数。
    注：
    • 仅当 请求方式 为 POST、PUT 或 PATCH 时会出现此设置。
    • 支持添加最多 30 个查询参数。
    • Body 描述
      设置 说明 JSON 字段 & 示例
      说明 输入描述信息，以指导 AI 接待员如何从通话中提取 Body 参数。 
      "body_description":"从对话中提取用户注册信息。"
    • Body 参数配置

      设置 说明 JSON 字段 & 示例
      参数 参数名称。
      注： 仅允许输入数字、字母、下划线 _、非连续的点号 . 以及符号 @。
      		 
      "body_params[].parameter": "userId"
      必需 该参数是否必需。

      若勾选，当来电者未提供此信息时，AI 接待员将反复进行提示。 

      "body_params[].required": true
      数据类型 选择参数的数据类型。
      • String：文本类信息，如姓名、邮箱、地址。允许字母、数字和特殊字符。
      • Boolean：是/否类信息，如是否订阅通知、是否接受条款。
      • Integer：不含小数的整数，如数量、年龄、评分。
      • Number：可为整数或小数的数值，如订单金额、折扣率、产品重量。
      • Object: 键值对结构，可将多个不同类型字段组合为一组信息，例如注册信息 (包含用户名、邮箱、注册日期)。
      • Array: 相同类型的值组成的列表，例如电话号码、邮箱地址或产品 ID。
      		 
      "body_params[].data_type": "String"
// 有效值：Boolean/Integer/Number/String/Object/Array
      Boolean/Integer/Number/String 数据类型
      取值逻辑
      决定参数值的获取方式。
      • 固定值：使用 值 字段中指定的固定参数值。
      • 由大模型生成：AI 接待员从对话中动态提取或生成参数值。
      		 
      "body_params[].value_logic": "constant"
// 有效值：constant/llm
      值 指定参数的固定值。
      注： 仅当 取值逻辑 为 固定值 时，此设置才可用。
      		 
      "body_params[].constant_value": "active"
// 当 data_type 为 Boolean 时，值应为 True 或 False。
      描述 输入自然语言描述，以指示 AI 接待员如何从通话中提取或生成参数值。
      注： 仅当 取值逻辑 为 由大模型生成 时，此设置才可用。
      		 
      "body_params[].description": "从通话中提取用户 ID，例如客户说 "user 123"，则提取值为 123。"
      可选项 可选。点击 添加选项 添加预定义值。当提取的信息匹配指定选项时，AI 接待员可直接选择。
      注：
      • 仅当 数据类型 为 String 且 取值逻辑 为 由大模型生成 时，此设置才可用。
      • 支持添加最多 10 个选项。
      		 
      "body_params[].optional_values": ["standard", "premium", "enterprise"]
      Object 数据类型
      描述 输入自然语言描述，以指导 AI 接待员如何从通话中提取或生成 Object (对象) 的内容。 
      "body_params[].description:"从通话中提取地址信息。"
      Object (对象)
      定义一个或多个嵌套在对象中的子参数。
      注： 
      "body_params[].children:[{ "parameter": "city", "required": true, "data_type": "String", "value_logic": "llm", "description": "提取城市名称" }, 
{ "parameter": "zipcode", "required": false, "data_type": "String", "value_logic": "llm", "description": "提取邮政编码" }]
      Array 数据类型
      描述 输入自然语言描述，以指导 AI 接待员如何从通话中提取或生成数组的内容。 
      "body_params[].description:"从通话中提取客户提及的所有产品标签。"
      数据类型 选择数组中参数的数据类型。
      • String：文本类信息，如姓名、邮箱、地址。允许字母、数字和特殊字符。
      • Boolean：是/否类信息，如是否订阅通知、是否接受条款。
      • Integer：不含小数的整数，如数量、年龄、评分。
      • Number：可为整数或小数的数值，如订单金额、折扣率、产品重量。
      		 
      "body_params[].array_item.data_type": "String"
      描述 输入自然语言描述，以指示 AI 接待员如何从通话中提取或生成具体参数值。 
      "body_params[].array_item.description": "Extract a single product tag"
      可选项 可选。点击 添加选项 添加预定义值。当提取的信息匹配指定选项时，AI 接待员可直接选择。
      注：
      • 仅当 数据类型 为 String 时，此设置才可用。
      • 支持添加最多 10 个选项。
      		 
      "body_params[].array_item.optional_values": ["electronics", "books", "clothing"]
  6. 点击 保存。

执行结果

工具已添加成功，并显示在工具列表中。

后续操作

为 AI 接待员分配工具 并 测试会话结果。