Vapi スクワッド作成

複数の特化したアシスタントをコンテキスト保持型ハンドオフで調整するスクワッドを作成します。複雑なワークフローを、相互に通話を転送できるフォーカスしたアシスタントに分割します。

セットアップ: VAPI_API_KEY が設定されていることを確認してください。必要に応じて setup-api-key スキルを参照してください。

スクワッドの利点

大きなプロンプトを持つ単一のアシスタントは、ハルシネーション率の上昇、コストの増加、レイテンシーの増加につながります。スクワッドは特定の役割を持つフォーカスしたアシスタントを作成することでこれを解決します:

• トリアージ → 予約 → 確認
• セールス → 技術サポート → 請求
• 受付 → 部門スペシャリスト

クイックスタート

cURL

curl -X POST https://api.vapi.ai/squad \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Squad",
    "members": [
      {
        "assistant": {
          "name": "Receptionist",
          "firstMessage": "Hello! How can I direct your call today?",
          "model": {
            "provider": "openai",
            "model": "gpt-4.1",
            "messages": [
              {
                "role": "system",
                "content": "You are a receptionist. Determine if the caller needs sales or support, then transfer them to the right department."
              }
            ],
            "tools": [
              {
                "type": "handoff",
                "destinations": [
                  {
                    "type": "assistant",
                    "assistantId": "sales-assistant-id",
                    "description": "Transfer when the caller asks about pricing, plans, or wants to purchase"
                  },
                  {
                    "type": "assistant",
                    "assistantId": "support-assistant-id",
                    "description": "Transfer when the caller has a technical issue or needs help"
                  }
                ]
              }
            ]
          },
          "voice": { "provider": "vapi", "voiceId": "Lily" },
          "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" }
        }
      },
      {
        "assistantId": "sales-assistant-id"
      },
      {
        "assistantId": "support-assistant-id"
      }
    ]
  }'

TypeScript (Server SDK)

import { VapiClient } from "@vapi-ai/server-sdk";

const vapi = new VapiClient({ token: process.env.VAPI_API_KEY! });

const squad = await vapi.squads.create({
  name: "Support Squad",
  members: [
    {
      assistant: {
        name: "Receptionist",
        firstMessage: "Hello! How can I direct your call today?",
        model: {
          provider: "openai",
          model: "gpt-4.1",
          messages: [
            {
              role: "system",
              content:
                "You are a receptionist. Determine if the caller needs sales or support, then transfer them.",
            },
          ],
          tools: [
            {
              type: "handoff",
              destinations: [
                {
                  type: "assistant",
                  assistantId: "sales-assistant-id",
                  description: "Transfer for pricing and purchasing questions",
                },
                {
                  type: "assistant",
                  assistantId: "support-assistant-id",
                  description: "Transfer for technical issues",
                },
              ],
            },
          ],
        },
        voice: { provider: "vapi", voiceId: "Lily" },
        transcriber: { provider: "deepgram", model: "nova-3", language: "en" },
      },
    },
    { assistantId: "sales-assistant-id" },
    { assistantId: "support-assistant-id" },
  ],
});

console.log("Squad created:", squad.id);

スクワッド構造

メンバー

配列の最初のメンバーが通話を開始します。各メンバーは以下のいずれかです:

• トランジェント — assistant: { ... } でインラインで定義
• パーシステント — 保存されたアシスタントを assistantId: "..." で参照

{
  "members": [
    { "assistant": { "name": "Inline Assistant", "..." : "..." } },
    { "assistantId": "saved-assistant-id" }
  ]
}

ハンドオフツール

ハンドオフツールはアシスタント間での転送方法を定義します:

{
  "type": "handoff",
  "destinations": [
    {
      "type": "assistant",
      "assistantId": "target-assistant-id",
      "description": "転送するタイミングの明確な説明。トリガー条件について具体的に説明してください。"
    }
  ],
  "function": {
    "name": "handoff_to_sales"
  }
}

アシスタントオーバーライド

元の設定を変更することなく、スクワッドコンテキスト内で保存されたアシスタント設定をオーバーライドします:

{
  "assistantId": "saved-assistant-id",
  "assistantOverrides": {
    "voice": { "provider": "vapi", "voiceId": "Elliot" },
    "firstMessage": "Overridden greeting for this squad"
  }
}

オーバーライド経由でツールを追加

保存されたアシスタントにスクワッド固有のツールを追加します:

{
  "assistantId": "saved-assistant-id",
  "assistantOverrides": {
    "tools:append": [
      {
        "type": "handoff",
        "destinations": [
          {
            "type": "assistant",
            "assistantId": "another-assistant-id",
            "description": "Transfer when customer needs billing help"
          }
        ],
        "function": { "name": "handoff_to_billing" }
      }
    ]
  }
}

メンバーオーバーライド

すべてのメンバーに同時に設定を適用します:

{
  "members": [
    { "assistant": { "name": "Agent A", "..." : "..." } },
    { "assistantId": "agent-b-id" }
  ],
  "memberOverrides": {
    "voice": { "provider": "vapi", "voiceId": "Elliot" },
    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" }
  }
}

通話でのスクワッドの使用

スクワッドを使用したアウトバウンド通話

curl -X POST https://api.vapi.ai/call \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "squadId": "your-squad-id",
    "phoneNumberId": "your-phone-number-id",
    "customer": {
      "number": "+11234567890"
    }
  }'

通話内でのトランジェントスクワッド

{
  "squad": {
    "members": [
      { "assistant": { "..." : "..." } },
      { "assistantId": "..." }
    ]
  },
  "phoneNumberId": "phone-number-id",
  "customer": { "number": "+11234567890" }
}

一般的なパターン

クリニックトリアージ → スケジューリング

{
  "name": "Clinic Squad",
  "members": [
    {
      "assistant": {
        "name": "Triage Nurse",
        "firstMessage": "Hello, this is the clinic. How can I help you today?",
        "model": {
          "provider": "openai",
          "model": "gpt-4.1",
          "messages": [
            {
              "role": "system",
              "content": "You are a clinic triage assistant. Assess the caller's needs: if they need an appointment, transfer to scheduling. If it's urgent, transfer to the nurse line."
            }
          ],
          "tools": [
            {
              "type": "handoff",
              "destinations": [
                {
                  "type": "assistant",
                  "assistantId": "scheduling-assistant-id",
                  "description": "Transfer when caller wants to book, reschedule, or cancel an appointment"
                },
                {
                  "type": "assistant",
                  "assistantId": "nurse-assistant-id",
                  "description": "Transfer for urgent medical questions or symptoms"
                }
              ]
            }
          ]
        },
        "voice": { "provider": "vapi", "voiceId": "Lily" }
      }
    },
    { "assistantId": "scheduling-assistant-id" },
    { "assistantId": "nurse-assistant-id" }
  ]
}

Eコマース: セールス → サポート → 返品

{
  "name": "E-commerce Squad",
  "members": [
    {
      "assistant": {
        "name": "Sales Agent",
        "firstMessage": "Welcome to our store! Are you looking to make a purchase today?",
        "model": {
          "provider": "openai",
          "model": "gpt-4.1",
          "messages": [
            { "role": "system", "content": "You are a sales assistant. Help customers find products and make purchases. Transfer to support for order issues or returns." }
          ],
          "tools": [
            {
              "type": "handoff",
              "destinations": [
                { "type": "assistant", "assistantId": "support-id", "description": "Transfer for order status, shipping, or account issues" },
                { "type": "assistant", "assistantId": "returns-id", "description": "Transfer for returns, refunds, or exchanges" }
              ]
            }
          ]
        }
      }
    },
    { "assistantId": "support-id" },
    { "assistantId": "returns-id" }
  ]
}

ベストプラクティス

1. アシスタントをフォーカスさせる — 各アシスタントは最大1～3のゴールを持つべき
2. スクワッドサイズを最小化する — 明確な機能的境界がある場合のみ分割
3. 具体的なハンドオフ説明を記述する — LLMはこれらを使用して転送時期を決定
4. システムプロンプトにハンドオフを記載する — 各アシスタントにどの部門が存在するかを伝える
5. メンバーオーバーライドを使用する — スクワッド全体で一貫したボイスとトランスクライバー設定を適用

スクワッドの管理

# スクワッドをリストアップ
curl https://api.vapi.ai/squad -H "Authorization: Bearer $VAPI_API_KEY"

# スクワッドを取得
curl https://api.vapi.ai/squad/{id} -H "Authorization: Bearer $VAPI_API_KEY"

# スクワッドを更新
curl -X PATCH https://api.vapi.ai/squad/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Squad Name"}'

# スクワッドを削除
curl -X DELETE https://api.vapi.ai/squad/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY"

リファレンス

• Vapi Squads Docs — 公式ドキュメント
• Squad Examples — その他のパターン
• Handoff Configuration — 詳細なハンドオフガイド

その他のリソース

このスキルリポジトリには、Vapi ドキュメント MCP サーバー (vapi-docs) が含まれており、AI エージェントに完全な Vapi ナレッジベースへのアクセス権を与えます。searchDocs ツールを使用して、このスキルでカバーされていない詳細な設定、トラブルシューティング、SDK の詳細などを検索してください。

自動設定: これらのスキルをクローンまたはインストールした場合、MCP サーバーは .mcp.json (Claude Code)、.cursor/mcp.json (Cursor)、または .vscode/mcp.json (VS Code Copilot) 経由で既に設定されています。

手動セットアップ: エージェントが設定を自動検出しない場合は、以下を実行してください:

claude mcp add vapi-docs -- npx -y mcp-remote https://docs.vapi.ai/_mcp/server

すべてのサポート対象エージェント全体での完全なセットアップ手順については、README を参照してください。