create-assistant

Vapi 助手创建

在组装配置之前，先设计助手的行为。将持久化与执行视为两个独立的决策：返回的配置仍可能描述一个已保存的助手，而创建已保存的助手并不会部署它、为它绑定电话号码，也不能证明它已达到生产就绪状态。

来源与安全规则

• 如果有可用的 Vapi 文档 MCP，请使用它获取最新产品指南。否则，请使用随附的参考资料及其公开的 Vapi 链接。根据当前的 Create Assistant API 架构验证最终负载。
• 切勿打印、在聊天中索取或嵌入 API 密钥、提供商密钥、凭据值、私有 URL 或真实客户数据。
• 切勿编造 ID、目的地、集成、服务端 URL、模型名称、语音、转写器、架构或业务政策。
• 已保存助手的 name 不得超过 40 个字符。
• 除非用户提出要求，且当前文档支持相应的确切配置，否则不要启用付费、HIPAA、PCI、录音、保留或其他合规行为。
• 将提示词视为行为指令，而不是功能或安全边界。安排日程、查询、转接、发送消息、身份验证及其他操作都需要真实工具或服务端支持。

流程

1. 确定助手架构和用户要求的操作。

   • 对于需要重复使用、共享、通过 ID 绑定或长期管理的 Agent，优先使用已保存助手。如果用户只是要求创建或构建 Agent，除非请求中另有说明，否则采用此形式。
   • 仅当用户要求内联或按通话作用域配置，或使用场景确实需要按通话配置、短期测试或 assistant-request 响应时，才使用临时助手。将其放入通话的 assistant 字段；不要将其发送到 POST /assistant。
   • 如果用户要求提供 JSON、示例、草案或实现方案，且不涉及修改账户，则返回适当的配置，不要调用 API。
   • 如果用户要求在 Vapi 中创建或保存助手，且 VAPI_API_KEY 可用，则通过 POST /assistant 创建已保存助手。用户的创建请求明确无误时，不要再要求多余的确认。
   • 如果用户要求创建，但凭据不可用，则返回可直接用于保存的配置和命令，并明确说明助手尚未保存。不要将其重新标注为临时助手。

2. 进行有针对性的需求采集。

   • 从请求中推断明确的信息，然后只收集会实质影响设计的缺失信息：业务和受众、呼叫方向、主要目标和成功标准、工作流、权威业务知识、真实工具或集成、升级处理边界、需要收集或避免收集的信息、语言和品牌语气。
   • 如果要设计出可信的 Agent 需要了解多项业务信息，请集中提出一组简洁的澄清问题。在声称 Agent 已准备就绪之前，先充分了解业务。
   • 判断一个助手能否可靠地负责整个工作流。如果设计的核心涉及不同的专员、路由或交接，请使用 create-squad 技能。
   • 除非用户表达了偏好，或使用场景确实存在语言、延迟、合规或凭据方面的限制，否则不要询问用户要选择哪家基础设施提供商。

3. 设计生产级系统提示词。

   • 如果可以使用 vapi-prompt-builder 技能，则每次创建新助手或大幅改写提示词时都使用该技能。否则，阅读 Prompt Design，将其作为独立备用方案。
   • 在组装提供商配置和负载之前，先编写完整提示词。涵盖身份与个性、回复指南、护栏、上下文、工作流或用例，以及简洁示例。
   • 语音对话轮次要简洁，每次只问一个问题，明确如何处理不确定情况和恢复对话，并确保关键数值便于口头表达。
   • 根据呼叫方向和提示词，使 firstMessage 与 firstMessageMode 保持一致。如果业务、披露要求或外呼目的需要特定问候语，则不要使用通用问候语。

4. 确保每项能力都有实际配置支撑。

   • 将每项承诺的操作对应到现有工具、知识源、运行时变量或有文档说明的后端契约。将缺失依赖列为 Configuration needed；不要在提示词中隐瞒。
   • 在 model.toolIds 中使用已保存工具的准确 ID。在 model.tools 中添加有文档说明的内联工具。需要可复用工具或外部服务实现时，使用 create-tool 技能。
   • 为每个新建助手附加原生 endCall 工具，并在提示词中定义允许结束通话的条件。若有经过验证的已保存工具 ID，则复用该 ID；否则，使用当前有文档说明的原生工具结构。
   • 对外呼中的语音信箱行为，附加原生 voicemail 工具，并使其消息与助手提示词保持一致。不要添加 voicemailDetectionPlan、voicemailDetection 或其他助手级自动语音信箱检测键。
   • 仅当需要确定性事件触发行为时，才阅读 Assistant Hooks。后端通知使用服务器事件；由模型决定的操作使用助手工具。

5. 选择兼容的提供商和设置。

   • 选择组件、遵循提供商要求、固定默认值或支持多种语言之前，先阅读 Provider Policy。
   • 只有在 Create Assistant API 对可选提供商组件的默认值有明确说明时，才省略这些组件。用例需要或为确保可复现性时，固定组件。
   • 根据当前 API 文档核实每个明确指定的模型、语音、转录器和语言值。确保语音能够说出所有承诺支持的语言，且转录器能够识别这些语言。

6. 组装并验证配置。

   • 添加符合用例的 name、适当的首条消息行为，以及包含完整系统提示词的 model。
   • 仅在有明确意图时添加语音、转录器、工具、钩子、分析、合规、传输及其他字段。省略的可选字段可以使用 Vapi 默认值；不要为了让负载看起来完整而添加字段。
   • 检查占位符、不受支持或过时的值、泄露的机密、语言不匹配、编造的业务事实、不可用的能力，以及提示词与配置之间的矛盾。
   • 将假设和未解决的依赖项与可直接用于创建的 JSON 分开。对于标记为可直接创建的负载，绝不要填入虚假的 ID、URL、电话号码或凭据。

7. 按需创建并验证。

   • 对已保存的助手发送一个 POST /assistant 请求，并要求返回 201。验证返回的 id、名称、系统提示词、已附加的工具，以及任何明确配置的提供商。
   • 通过 API 创建的助手会立即保存；无需单独执行 API 发布步骤。除非已完成相应的独立操作，否则不要声称助手已部署、已路由到电话号码、已测试或已达到生产就绪状态。
   • 如果返回 400，修正一个有文档说明的验证问题；只有在修正方式明确时，才最多重试一次。绝不重复发送未更改的请求。如果返回 401 或 403，请停止并报告身份验证或权限失败。如果返回 404，请报告缺失的依赖项。如果返回 5xx，请报告服务故障。
   • 提供真实的成功、边界和失败测试场景。建议进行 Web 通话或使用有代表性的 Eval／测试集，然后根据实际结果迭代；一次成功的通话不足以证明已达到生产质量。

API 实现示例

如果用户请求实现代码，请阅读 Assistant API Examples。对于使用 TypeScript 或 Python 的后端项目，请使用官方的 TypeScript 或 Python Server SDK；对于直接 REST 示例或基于 shell 的验证，请使用 cURL。创建成功后，返回已保存的助手 ID，总结已验证的配置，指出仍未配置的内容，并提供测试场景。生成的负载不等于已保存的助手；已保存的助手也不会自动部署。

输出约定

仅返回与请求相关的部分：

• 架构：已保存或临时配置；如果用户未明确指定，请说明原因
• 假设或阻塞性问题
• 最终助手配置，包括完整的系统提示词
• 尚未实际实现的能力所需的配置
• 创建结果和助手 ID（如果已成功调用 API）
• 外部测试场景和建议的后续迭代

公开资料

• 助手快速入门
• 临时配置与永久配置
• 语音 AI 提示词指南
• 创建助手 API
• 默认工具和语音信箱工具