create-squad

Vapi Squad の作成

複数の専門性に特化したアシスタントによって設計が改善される場合にのみ、Squad を使用してください。ユーザーから Vapi のライブ変更を明示的に依頼されない限り、ペイロードまたは実装計画をデフォルトとしてください。

Squad を使用するかどうかの判断

1 つの特化したプロンプトと互換性のある 1 組のツールでユースケースに確実に対応できる場合は、アシスタントを 1 つにすることを優先してください。次のような明確な境界がある場合は、Squad を使用してください。

• ドメインやペルソナが異なる；
• ツールや認証情報へのアクセスが異なる；
• 意図的にコンテキストを分離する；
• 専門家を個別に保守する。

会話の手順ごとにアシスタントを作成しないでください。関連する手順は 1 つのメンバーにまとめ、引き継ぎの境界ごとに、それがもたらすレイテンシーと運用コストに見合う価値があることを確認してください。

安全性と情報源に関するルール

• Squad、メンバー、引き継ぎ、コンテキスト、バージョンの各フィールドは、最新の公開されている Squads のドキュメント、Handoff ツールガイド、および OpenAPI スキーマに照らして検証してください。
• アシスタント 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 モデルでは、現在の公開ガイダンスにより、移行先ごとに引き継ぎツールを1つ作成することが推奨されています。Anthropic モデルでは、移行先を複数指定した1つのツールがサポートされており、推奨されています。

4. 必要な場合に限り、公開コンテキスト制御を設定します。

   • 現在のスキーマでサポートされている場合は、引き継ぎ先に contextEngineeringPlan として all、lastNMessages、userAndAssistantMessages、previousAssistantMessages、または none を使用します。
   • 下流で必要となる特定の構造化値に限り、variableExtractionPlan.schema を使用します。値を捏造したり、実際に引き継ぎが行われる前に抽出が実行されたと主張したりしないでください。
   • ユースケースで分離が必要な場合は、機密性の高いツールの結果を下流のコンテキストに含めないでください。

5. Squad を作成して検証します。

   • 明示された順序で、検証済みのアシスタント ID から members を構築します。
   • ユーザーが不変の固定を希望する場合に限り、公開アシスタント API が返したバージョンを assistantVersion に設定できます。最新バージョンに追従する場合は省略します。
   • 本番環境に影響する作成や更新の前に、メンバーの順序、引き継ぎ、対象を要約して明示的な確認を得ます。ただし、ユーザーの現在の指示がその変更を今すぐ実施することを明確に許可している場合を除きます。
   • ライブ作成の明示的な意図がある場合に限り、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 リファレンス