create-squad

Vapi Squad 创建

仅当多个专注的助手能改进设计时才使用 Squad。除非用户明确要求实时修改 Vapi，否则默认提供 payload 或实施计划。

判断是否使用 Squad

如果一个专注的提示词和一组兼容的工具能够可靠地处理用例，优先使用一个助手。只有存在真正的边界时才使用 Squad，例如：

• 不同的领域或角色；
• 不同的工具或凭据访问权限；
• 有意隔离上下文；
• 单独维护的专业助手。

不要为每个对话步骤都创建一个助手。将相关步骤交给同一个成员处理，并确保每个交接边界都值得其带来的延迟和运维成本。

安全与来源规则

• 根据当前公开的 Squads 文档、Handoff 工具指南和 OpenAPI schema，核验 squad、member、handoff、context 和 version 字段。
• 切勿臆造 assistant ID、名称、工具 ID、目标、版本、凭据、服务器 URL 或提取的变量。
• 提示词文本不会创建交接。请配置并关联有文档说明的 handoff 工具。
• 明确指定成员顺序：第一个成员负责开始通话。
• 对于生产环境，优先使用已保存的助手、可复用工具和已保存的 Squad。仅当请求明确要求临时使用或制作原型时，才使用临时成员或 Squad。

持久化 Squad 流程

1. 确定执行模式。

   • 如果用户要求草拟方案，或未明确授权执行实时写入，则返回 JSON 或计划。
   • 仅在用户明确表示意图且已提供 VAPI_API_KEY 时，才执行实时创建或更新。

2. 定义职责明确的成员。

   • 说明每位成员的职责、工具和交接边界。
   • 选择入口成员并将其放在首位。
   • 通过 GET /assistant 按名称查找并复用现有助手；先使用 create-assistant 技能创建缺失的助手。

3. 在目标助手就绪后创建交接关系。

   • 构建持久化交接工具之前，先查找并确认每个目标助手。
   • 对于已保存的跨助手目标，使用 type: "assistant" 和已验证的 assistantId。
   • 使用清晰的描述，说明模型应在何时进行交接，以及交接前应收集哪些信息。
   • 通过 POST /tool 创建可复用的交接工具，然后按照 create-tool 技能中的保留配置流程，将其附加到源助手。
   • 对于 OpenAI 模型，目前的公开指南建议每个目标使用一个交接工具。对于 Anthropic 模型，支持并推荐使用一个工具指向多个目标。

4. 仅在需要时配置公开上下文控制。

   • 在交接目标上使用 contextEngineeringPlan：在当前架构支持的情况下，可设置为 all、lastNMessages、userAndAssistantMessages、previousAssistantMessages 或 none。
   • 仅当下游需要特定结构化值时，才使用 variableExtractionPlan.schema。不要臆造值，也不要声称在真实交接发生前已完成提取。
   • 如果用例要求隔离，请勿将敏感工具结果放入下游上下文。

5. 创建并验证 Squad。

   • 按明确顺序，使用已验证的助手 ID 构建 members。
   • 如果用户需要不可变固定版本，可选择性地将 assistantVersion 设置为公开助手 API 返回的版本。省略此字段则使用最新版本。
   • 在执行会影响生产环境的创建或更新之前，概述成员顺序、交接关系和目标，并取得明确确认；除非用户当前的指示已明确授权立即执行该项具体变更。
   • 仅在用户明确表示要实时创建后，才发送 POST /squad。
   • 在报告成功之前，验证返回的 Squad ID、完整成员顺序、入口成员、固定版本和交接工具附件。

6. 诚实处理失败。

   • 如果收到 400，应先修正文档规定的字段位置或限制，然后最多进行一次有充分理由的重试。
   • 如果收到 401 或 403，因身份验证或权限问题停止操作。如果收到 404，报告缺失的助手、工具或 Squad。如果收到 5xx，报告服务故障。
   • 如果操作序列部分成功，请列出已创建的 ID，供用户检查或清理。发生致命错误后，不要继续创建依赖资源。

持久化 Squad 负载

仅使用已验证的 ID：

{
  "name": "Support Squad",
  "members": [
    { "assistantId": "<verified-triage-assistant-id>" },
    { "assistantId": "<verified-billing-assistant-id>" },
    { "assistantId": "<verified-technical-assistant-id>" }
  ]
}

第一个成员是入口助手。交接工具应添加到相关的源助手；仅有 Squad 成员关系并不能定义所有转换。

交接负载

{
  "type": "handoff",
  "function": { "name": "handoff_to_billing" },
  "destinations": [
    {
      "type": "assistant",
      "assistantId": "<verified-billing-assistant-id>",
      "description": "The caller needs billing, invoice, or payment help.",
      "contextEngineeringPlan": {
        "type": "userAndAssistantMessages"
      },
      "variableExtractionPlan": {
        "schema": {
          "type": "object",
          "properties": {
            "accountNumber": { "type": "string" }
          }
        }
      }
    }
  ]
}

模板中可以使用占位符，但实时请求中不得使用。有关临时 Squad、上下文传递、版本固定和安全更新 Squad 的信息，请阅读 Squad Configuration。如果用户要求 TypeScript、Python 或 cURL 实现代码，请阅读 Squad API Examples。

安全更新

仅将更改过的顶层字段发送到 PATCH /squad/{id}。若仅更改名称或进行其他非成员更新，请省略 members。如果请求的更改涉及成员顺序、成员关系、版本固定、助手覆盖或交接目标：

1. GET /squad/{id}。
2. 复制完整且有序的 members 数组；如果 membersOverrides 也必须更改，则一并复制当前值。
3. 仅应用请求的更改，保留每个成员现有的 assistantId 或内联助手、assistantVersion、assistantOverrides，以及任何已记录的目标字段。
4. 提交完整合并后的 members 数组，以及其他已更改的顶层字段。
5. 重新获取并验证顺序、入口成员、版本固定、覆盖项和交接。

公开来源

• Squads 简介
• 交接工具
• 在助手之间传递数据
• Squad API 参考