create-tool

Vapi 工具管理

选择能直接提供所需能力的文档所述工具类型。除非用户明确要求实际修改 Vapi，否则默认提供请求负载或实施方案。

安全与来源规则

• 使用前，依据最新的 Create Tool API、公开的 OpenAPI 架构或特定类型的公开指南，核实工具类型和每个字段。
• 绝不可使用自定义 function 工具来仿造文档所述的 Vapi 能力。
• 绝不可臆造端点、请求架构、目标地址、电话号码、助手 ID、工具 ID、集成连接、凭据或密钥。
• 将密钥保存在 Vapi 凭据或用户的后端中。将包含令牌的 MCP 服务 URL 视为凭据。
• 区分工具配置、关联助手、连接提供商和外部实现。它们是不同的交付项，在其中一项上成功并不代表其他项也成功。

选择工具系列

需求	选择
结束通话、转接通话、在助手之间移交、发送 DTMF 或 SMS、发起 SIP 请求或处理语音信箱	对应的 Vapi 原生工具
使用公开文档说明的 Google Calendar、Google Sheets、Slack、GoHighLevel 或其他受支持提供商的操作	解析其连接和所需资源后，选择对应的集成工具
使用声明式方法、URL、标头和请求正文调用已知 HTTP 端点	apiRequest
将模型选择的函数调用发送给实现 Vapi 回调约定的自定义后端逻辑	function
发现并使用现有 MCP 服务中的工具	使用默认的 Streamable HTTP 传输方式配置 mcp

不要仅仅因为模型会调用某项能力就选择 function。原生、集成、API Request 和 MCP 工具同样由模型调用。

不要主动推荐或创建 Code Tool（type: "code"）；大多数账户通常无法使用它。对于已知 HTTP 端点，优先使用 apiRequest；对于用户托管的回调逻辑，优先使用 server.url 指向用户服务的 function。仅在用户明确询问 Code Tool 时才讨论它，而且不要将其作为推荐选项。

构建请求负载前，阅读 Tool Type Selection。只阅读所选系列对应的部分。

流程

1. 确定执行模式。

   • 如果用户要求草拟内容，或未明确授权实际修改，则返回 JSON、代码或约定。
   • 仅当用户明确要求创建、更新、关联或解除关联，且 VAPI_API_KEY 可用时，才调用 Vapi API。
   • 如果密钥不可用，则返回可直接使用的交付物和本地命令，不要要求用户将密钥粘贴到聊天中。

2. 创建前先检查。

   • 使用 GET /tool，根据提供的名称和能力匹配现有工具。
   • 如果匹配明确，且用户不要求新资源，则复用一个合适的现有工具。
   • 如果有多个工具可能符合，请让用户选择。绝不要猜测 ID。
   • 更新现有工具前，使用 GET /tool/{id}。

3. 明确能力及其依赖项。

   • 根据上表和最新公开文档选择工具系列。
   • 实际创建前，明确所有必需的端点、目标地址、提供商连接、日历、电子表格、渠道、凭据或 MCP 服务。
   • 如果某个值会阻碍有效工具的创建，先展示有用的拟定约定，然后只询问该值。

4. 构建最小有效载荷。

   • 向模型提供简洁、具体的描述，说明何时调用该工具。
   • 对于具有 function.name 的类型，使用 1–64 个字符，并匹配 ^[a-zA-Z0-9_-]+$。如果用户未提供名称，则生成一个稳定且描述性强的名称。
   • 对于 apiRequest，根据当前公开架构验证其顶层 name、方法、URL、标头、请求体架构、凭据和超时。
   • 只定义模型必须提供的参数。将可信值或机密值放在模型可见架构之外。
   • 除非进度反馈有用，否则省略语音 messages。如果包含，则只能使用所选工具架构当前接受的类型，例如 request-start、request-response-delayed、request-complete 和 request-failed。

5. 安全地创建或更新。

   • 在执行会影响生产环境的变更前，概述类型、功能、外部依赖项和目标，除非用户当前的指令已明确授权进行该项具体变更。
   • 使用 POST /tool 创建。验证返回的 id、类型、适用时的可调用名称，以及请求的配置。
   • 更新时，向 PATCH /tool/{id} 发送当前 type 和仅有的已更改顶层字段。更改嵌套对象时，将请求的变更深度合并到从获取的工具中读取的该对象，并发送合并后的嵌套对象，以免丢失未提及的键。不要重新发送未更改的顶层字段或仅用于响应的字段。
   • 重新获取工具并验证结果。创建或更新工具不会将其附加到助手。

6. 附加或移除工具，同时保留助手配置。

   • 更改助手前，请阅读 助手附件。
   • 执行 GET /assistant/{id}，复制完整的当前 model，将工具 ID 合并到 model.toolIds 中或从中移除，并保留 model.tools 及所有无关的模型字段。
   • 将合并后的完整模型发送到 PATCH /assistant/{id}。绝不要修补手写的不完整模型。
   • 重新获取助手，并验证所请求的关联状态以及保留的模型配置。

7. 仅在用户请求时实现外部行为。

   • 对于 apiRequest，Vapi 会执行配置的 HTTP 请求；不要另外构建函数回调服务器。
   • 对于 mcp，MCP 服务会提供可调用工具；不要将它们重复实现为单独的 Vapi 函数工具。
   • 对于必须构建后端的自定义 function，请阅读 函数工具服务器。其他工具系列无需加载该参考文档。

8. 如实处理失败。

   • 遇到 400 时，先修正已记录的格式或验证错误，之后最多进行一次合理的重试。
   • 遇到 401 或 403 时，因身份验证或权限问题而停止。遇到 404 时，报告缺失的工具、助手、目标或依赖项。遇到 5xx 时，报告服务故障。
   • 在相应操作得到验证之前，绝不要声称创建、更新、附加、移除、连接提供方或实现后端已成功。

API 实现示例

当用户请求 TypeScript、Python 或 cURL 实现代码时，请阅读 工具 API 示例。更新或更改附加状态前，先读取当前工具和助手状态。草稿材料中可以使用占位符，但绝不能在实时请求中使用。

公开来源

• 创建工具 API
• 默认工具
• 自定义工具
• MCP 集成