创建自定义工具

开发环境

POST

/v1/tools

创建一个可以接受 AI 输入并调用外部 API 的自定义工具。

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST 'http://dev-cn.your-api-server.com/v1/tools' \
--header 'authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "<string>",
  "description": "<string>",
  "speech": "<string>",
  "url": "<string>",
  "method": "<string>",
  "headers": {},
  "body": {},
  "query": {},
  "input_schema": {},
  "response": {},
  "timeout": 123
}'

响应示例

{
  "status": "success",
  "tool_id": "TL-1234567890"
}

请求参数

Header 参数

Content-Type

string

必需

示例值:

application/json

authorization

string

必需

示例值:

Body 参数application/json

name

string

必需

这是使用该工具的人工智能将看到的名称。其他一些内部工具名为Speak、Wait和Transfer-Finish自定义工具不能共享这些名称。我们列出了一些不能包含在内的可能会迷惑 AI 的保留字： - input - speak - transfer - switch - wait - finish - press - button - say - pause - record - play - dial - hang 选择与默认工具过于相似的名称可能会导致人工智能选择错误的名称，因此最好使用描述性的两到三个单词的名称。

description

string

必需

这是使用该工具的 AI 将看到的描述。描述该工具的作用或任何特殊说明的效果。作为参考，以下是默认工具的描述： - Speak：与线路另一端的人交谈 - Press Buttons：按手机上的按钮。每个字符都是一个不同的按钮。 - Wait：等待并长时间保持沉默（仅在绝对必要时使用）。 - Finish：说再见消息并在完成后结束通话。

speech

string

可选

这是人工智能在使用该工具时会说的文字。例如，如果该工具是“GenerateQuote”工具，则语音可能是“请稍等，我会为您提供报价”。由于工具可能会被口头打断，因此最好用较短的消息告诉用户工具/人工智能正在做什么。特别提示：您可以通过input.speech在input_schema.

url

string

必需

这是该工具将调用的外部 API 的端点。它必须以https://有效 URL 开头。

method

string

可选

这是该工具将用来调用外部 API 的 HTTP 方法。有效选项是GET和POST。

headers

object

可选

SUPPORTS PROMPT VARIABLES 这些是该工具将发送到外部 API 的标头。标头必须采用 JSON 格式。由于支持提示变量，因此您可以在标头中使用它们将动态信息发送到外部 API。

body

object

可选

SUPPORTS PROMPT VARIABLES 这是该工具将发送到外部 API 的正文。正文必须为 JSON 格式。这是将提示变量与 AI 输入结合使用的最常见位置。注意：GET请求没有主体。

query

object

可选

SUPPORTS PROMPT VARIABLES 将查询参数附加到 URL。查询必须采用 JSON 格式。这通常与 GET 请求和内置提示变量（如"{{phone_number}}"或）一起使用"{{call_id}}"。

input_schema

object

可选

这是 AI 输入必须与要使用的工具匹配的模式。架构必须采用 JSON 格式。该架构用于在使用该工具之前验证 AI 输入。如果 AI 输入与模式不匹配，则不会使用该工具，并且 AI 将继续使用下一个工具。 input_schema.example可用于增强人工智能对输入结构的理解，并对结构化或嵌套数据有很大帮助。特别说明：input_schema不需要严格的JSON schema结构，鼓励创造力。请在此处查找有关 JSON 模式结构的一般指南。还支持非传统 JSON 模式结构，如以下示例： - “选项”：“周一、周三、周五” - “日期”：“年-月-日” - “时间”：“HH：MM：SS（上午|下午）” - “电话号码”：“+1XXX-XXX-XXXX” 代理输入可以嵌套，并且即使最初是字符串，也会将其转换为 JSON。

response

object

必需

定义您希望如何从响应中提取数据。默认情况下，整个响应正文存储在{{data}}提示变量中。您想要的数据的路径必须采用 JSON Path 格式。一般来说，这意味着使用点表示法来遍历 JSON 对象，并且仅当您需要在其他工具上使用该信息或响应太大时才需要。例子：

json     // If the external API response is:     {         "available_times": [             {                 "time": "10:00 AM",                 "date": "2022-01-01"             },             {                 "time": "11:00 AM",                 "date": "2022-01-01"             }         ],         "store_hours": {             "open": "9:00 AM",             "close": "5:00 PM"         },         "address_info": {             "street": "123 Main St",             "city": "Anytown",             "state": "CA",             "zip": "12345"         }     }      // You can extract new Prompt Variables like this:     {         "response": {             "available_times": "$.available_times",             "store_hours": "$.store_hours",             "address_info": "$.address_info",             "zip_code": "$.address_info.zip"         }     }      // And then it'll automatically replace them elsewhere (like in the `task`/`prompt`)     {         "task": "The store is open from {{store_hours.open}} to {{store_hours.close}}.",         "prompt": "The store is located at {{address_info.street}}, {{address_info.city}}, {{address_info.state}} {{zip_code}}."     }

timeout

integer

可选

这是该工具等待外部 API 响应的最长时间（以毫秒为单位）。如果外部 API 在此时间内没有响应，该工具将失败，AI 将继续使用下一个工具。默认超时为 10 秒（10000 毫秒）。要始终等待响应，请将超时设置为极高的值，例如 99999999。

示例

返回响应

🟢200成功

application/json

Body

status

string

工具创建是否成功。

必需

tool_id

string

必需

您将来可以用来引用该工具的工具 ID。在发送呼叫请求中，您可以传递此工具 ID，而不是完整的自定义工具对象，如下所示： json { "tools": [ "TL-1234567890" // tool_id (instead of the full Custom Tool object) ] }

修改于 2024-05-10 08:26:53

生成音频样本

更新自定义工具