在 Vapi 中设计、创建、更新并验证 Squad 与…

适用于判断单 assistant 还是多 assistant Squad，并配置入口成员、持久/临时成员、上下文工程、变量提取、模型特定 handoff、版本固定及安全更新。

适用场景

解决思路

1. 判断是否用 Squad：优先用一个 assistant，当单个聚焦 prompt 和一套兼容工具集能可靠处理用例时；仅当存在真实边界（不同领域/人设、不同工具或凭证访问、刻意上下文隔离、需要独立维护的专家）时才用 Squad。
2. 不要把每个对话步骤做成一个 assistant；把相关步骤留在同一个 member，并让每个 handoff 边界值得其延迟和运维成本。
3. 默认只返回 payload 或实现计划；除非用户明确要求并授权 live Vapi 变更，否则不直接 mutate。
4. 对照当前公开 Squad 文档、Handoff 工具指南和 OpenAPI schema 校验 squad、member、handoff、context、version 字段。
5. 绝不编造 assistant ID、name、tool ID、destination、version、credential、server URL 或 extracted variable。
6. 记住 prompt 文本不会创建 handoff；必须配置并挂载文档化的 handoff 工具。
7. 保持 member 顺序显式：第一个 member 启动通话。
8. 生产环境优先使用已保存的 assistants、可复用 tools 和已保存 Squad；仅当请求明确是临时或原型时才用 transient members 或 Squad。
9. 确定执行模式：用户要草稿或未明确授权 live 写入时返回 JSON/计划；只有明确意图且有 VAPI_API_KEY 时才 live create/update。
10. 定义聚焦成员：写明每个 member 的职责、tools、handoff 边界；选择 entry member 并放在第一位；通过 GET /assistant 按名称解析复用现有 assistants；缺失的先用 create-assistant 技能创建。
11. 在 destination 已存在后再创建 handoff 关系：先解析每个 destination assistant；持久跨 assistant destination 使用 type: assistant 加已验证 assistantId。
12. 为 handoff 写清晰 description，说明模型何时应 handoff、应优先收集什么。
13. 通过 POST /tool 创建可复用 handoff tools，然后用 create-tool 技能中保留配置的过程挂到源 assistants。
14. OpenAI 模型按当前公开指引每个 destination 一个 handoff tool；Anthropic 模型支持并推荐一个 tool 带多个 destinations。
15. 仅在需要时配置公开的上下文控制：在 handoff destination 上使用 contextEngineeringPlan，取值 all、lastNMessages、userAndAssistantMessages、previousAssistantMessages、none（当前 schema 支持时）。
16. 仅对下游需要的特定结构化值使用 variableExtractionPlan.schema；不要编造值，也不要在真实 handoff 前声称已提取。
17. 当用例要求隔离时，将敏感 tool 结果排除在下游上下文之外。
18. 创建并验证 Squad：用已验证 assistant IDs 按显式顺序构建 members。
19. 仅当用户要不可变 pin 时，把 assistantVersion 设为公开 assistant API 返回的版本；否则省略以跟随最新版。
20. 在生产影响的 create/update 前，复述 member 顺序、handoffs、目标并取得明确确认，除非用户当前指令已无歧义授权该精确 mutation。
21. 仅在明确 live-create 意图后发送 POST /squad。
22. 报告成功前验证返回的 Squad ID、完整 member 顺序、entry member、pins、handoff attachments。
23. 失败要如实处理：400 时先按文档修正字段位置或限制，再做至多一次有理由的重试。
24. 401 或 403 时停止并处理认证或权限问题；404 时报告缺失的 assistant、tool 或 Squad；5xx 时报告服务失败。
25. 如果流程部分成功，列出已创建的 IDs 供用户审查或清理；发生致命错误后不要继续创建依赖资源。
26. 构造持久 Squad payload 时只使用已验证 IDs：包含 name 和 members 数组；第一个 member 是入口 assistant；handoff tools 属于相关源 assistants，Squad 成员关系本身不定义所有转移。
27. 构造 handoff payload 时包含 type: handoff、function.name、destinations；每个 destination 包含 type: assistant、已验证 assistantId、description、contextEngineeringPlan、variableExtractionPlan.schema。
28. 占位符只可用于模板，绝不能进入 live 请求。
29. 需要 transient Squads、上下文转移、版本 pin、安全 Squad 更新时读 references/squad-configuration.md；需要 TypeScript、Python 或 cURL 实现代码时读 references/api-examples.md。
30. 安全更新：只把变更的顶层字段发给 PATCH /squad/{id}；名称或其他非 member 更新时省略 members。
31. 当请求变更影响 member 顺序、成员关系、版本 pin、assistant overrides 或 handoff destinations 时：先 GET /squad/{id}。
32. 复制完整有序 members 数组，以及需要同时变更时的当前 membersOverrides。
33. 只应用请求的变更，保留每个 member 的 assistantId 或 inline assistant、assistantVersion、assistantOverrides 及已存在的文档化 destination 字段。
34. 将完整合并后的 members 数组以及仅其他变更的顶层字段一起 PATCH。
35. 重新获取并验证顺序、entry member、pins、overrides、handoffs。
36. 优先查阅公开来源：Introduction to Squads、Handoff tool、Passing data between assistants、Squad API reference（docs.vapi.ai 对应页面）。

适用边界 · 注意事项

• 单个聚焦 assistant 和一套兼容工具集已能可靠处理用例时，不要创建 Squad。
• 不要为每个对话步骤创建一个 assistant；相关步骤应留在一个 member。
• 没有明确 live 写入意图或缺少 VAPI_API_KEY 时，不要执行线上创建或更新。