需要在 Vapi 中创建、更新、附加…

通过 Vapi 公开 API 管理原生、集成、API Request、function、MCP 工具及其助手附件时使用。

适用场景

解决思路

1. 在构建请求负载前，依据当前 Create Tool API、公开 OpenAPI schema 或类型专属公开指南核对工具类型和每个字段。
2. 不要用自定义 function 工具模仿 Vapi 已记录能力。
3. 不要臆造 endpoint、request schema、destination、phone number、assistant ID、tool ID、integration connection、credential 或 secret。
4. 将 secret 保存在 Vapi credentials 或用户后端；将含 token 的 MCP server URL 视为 credential。
5. 区分工具配置、助手附件、provider 连接和外部实现；一个成功不代表另一个成功。
6. 若需要结束通话、转移通话、助手间转交、发送 DTMF 或 SMS、发起 SIP 请求或处理 voicemail，选择匹配的原生 Vapi 工具。
7. 若使用公开文档的 Google Calendar、Google Sheets、Slack、GoHighLevel 或其他受支持 provider action，在解析其 connection 和必需资源后选择确切 integration 工具。
8. 若调用已知 HTTP endpoint 且可使用声明式 method、URL、headers 和 body，选择 apiRequest。
9. 若将模型选择的函数调用发送到实现 Vapi callback contract 的自定义后端逻辑，选择 function。
10. 若发现并使用现有 MCP server 的工具，选择 mcp 并使用默认 Streamable HTTP transport。
11. 不要仅因模型会调用能力就选择 function；native、integration、apiRequest 和 mcp 工具也会被模型调用。
12. 不要主动推荐或创建 Code Tool（type: "code"）；它在大多数账户不普遍可用；优先用 apiRequest 处理已知 HTTP endpoint，或用 function 搭配用户 server.url 处理用户托管 callback 逻辑；仅当用户明确询问 Code Tool 时讨论，且不要作为推荐选项。
13. 构建请求负载前阅读 references/tool-types.md；只读所选 family 的章节。
14. 确定执行模式：用户要草稿或未明确授权实时变更时，返回 JSON、代码或 contract。
15. 仅当用户明确要求 create、update、attach 或 detach 且 VAPI_API_KEY 可用时，调用 Vapi API。
16. 若 VAPI_API_KEY 不可用，返回就绪产物和本地命令，不要让用户把 key 粘贴进聊天。
17. 创建前检查：用 GET /tool 将提供的 name 和 capability 与已有工具匹配。
18. 若匹配明确且用户不要求新资源，复用合适的已有工具。
19. 若多个工具可能匹配，让用户选择；绝不要猜 ID。
20. 更新现有工具前用 GET /tool/{id}。
21. 解析能力和依赖：按工具选择表与当前公开文档选择工具族。
22. 在实时创建前解析每个必需 endpoint、destination、provider connection、calendar、spreadsheet、channel、credential 或 MCP server。
23. 若某个值阻塞有效工具，先展示有用的 proposed contract，只询问该值。
24. 构建最小有效请求负载。
25. 给模型简洁、具体的 description，说明何时调用该工具。
26. 对含 function.name 的类型，使用 1–64 字符并匹配 ^[a-zA-Z0-9_-]+$；用户未提供时生成稳定的描述性名称。
27. 对 apiRequest，按当前公开 schema 校验顶层 name、method、URL、headers、body schema、credentials 和 timeout。
28. 只定义模型必须提供的参数；将可信或 secret 值排除在模型可见 schema 之外。
29. 除非进度反馈有用，省略 spoken messages；若包含，只用所选工具 schema 当前接受的类型，如 request-start、request-response-delayed、request-complete、request-failed。
30. 对生产有影响的变更前，除非用户当前指令已明确授权该确切变更，否则复述 type、capability、external dependencies 和 target。
31. 用 POST /tool 创建；验证返回的 id、type、适用时的 callable name 和请求的配置。
32. 更新时，向 PATCH /tool/{id} 发送当前 type 和仅变更的顶层字段。
33. 变更嵌套对象时，从已获取工具中 deep-merge 请求的变更到该对象，并发送合并后的嵌套对象，避免省略键丢失。
34. 不要重发未变更的顶层字段或 response-only 字段。
35. 重新获取工具并验证结果；创建或更新工具不会将其附加到 assistant。
36. 更改 assistant 前阅读 references/assistant-attachments.md。
37. 用 GET /assistant/{id} 复制完整当前 model，将 tool ID 合并进 model.toolIds 或从中移除，并保留 model.tools 及所有不相关 model 字段。
38. 将完整合并后的 model 发送到 PATCH /assistant/{id}；绝不要 patch 手写 partial model。
39. 重新获取 assistant 并验证请求的 membership 和保留的 model 配置。
40. 仅在请求时实现外部行为：对 apiRequest，Vapi 执行配置的 HTTP 请求；不要额外构建 function callback server。
41. 对 mcp，MCP server 提供可调用工具；不要将它们重复为单独的 Vapi function tools。
42. 对需要构建后端的自定义 function，阅读 references/function-tool-server.md；其他工具族不要加载该参考。
43. 处理失败时诚实：400 时先纠正已记录的 shape 或 validation error，再最多一次合理重试。
44. 401 或 403 时停止，处理认证或权限问题；404 时报告缺失的 tool、assistant、destination 或 dependency；5xx 时报告 service failure。
45. 在相关操作验证前，绝不要声称 creation、update、attachment、detachment、provider connection 或 backend implementation 成功。
46. 当用户请求 TypeScript、Python 或 cURL 实现代码时，阅读 references/api-examples.md。
47. 在 update 或 attachment 变更前读取当前 tool 和 assistant state；占位符可用于 draft artifacts，绝不能用于实时请求。
48. 使用公开来源核对：Create Tool API、Default tools、Custom tools、MCP integration。

适用边界 · 注意事项

• 不适用于非 Vapi 工具管理，或没有 VAPI_API_KEY 且无法进行实时 Vapi API 操作的场景。
• 用户未明确授权 create、update、attach 或 detach 时，不适用于执行实时变更；此时只返回请求负载、代码或实现计划。
• 用户未明确询问时，不适用于主动推荐或创建 Code Tool（type: "code"），尤其多数账户不普遍可用。