Vapi Squad Creation

Create squads that orchestrate multiple specialized assistants with context-preserving handoffs. Break complex workflows into focused assistants that transfer calls between each other.

Setup: Ensure VAPI_API_KEY is set. See the setup-api-key skill if needed.

Why Squads?

Single assistants with large prompts cause higher hallucination rates, increased costs, and greater latency. Squads solve this by creating focused assistants with specific roles:

• Triage → Booking → Confirmation

• Sales → Technical Support → Billing

• Receptionist → Department Specialist

Quick Start

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);

Squad Structure

Members

The first member in the array starts the call. Each member is either:

• Transient — Defined inline with assistant: { ... }

• Persistent — References a saved assistant via assistantId: "..."

{

  "members": [

    { "assistant": { "name": "Inline Assistant", "..." : "..." } },

    { "assistantId": "saved-assistant-id" }

  ]

}

Handoff Tools

Handoff tools define how assistants transfer between each other:

{

  "type": "handoff",

  "destinations": [

    {

      "type": "assistant",

      "assistantId": "target-assistant-id",

      "description": "Clear description of WHEN to transfer. Be specific about trigger conditions."

    }

  ],

  "function": {

    "name": "handoff_to_sales"

  }

}

Assistant Overrides

Override saved assistant settings within the squad context without modifying the original:

{

  "assistantId": "saved-assistant-id",

  "assistantOverrides": {

    "voice": { "provider": "vapi", "voiceId": "Elliot" },

    "firstMessage": "Overridden greeting for this squad"

  }

}

Appending Tools via Overrides

Add squad-specific tools to a saved assistant:

{

  "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" }

      }

    ]

  }

}

Member Overrides

Apply configuration to ALL members simultaneously:

{

  "members": [

    { "assistant": { "name": "Agent A", "..." : "..." } },

    { "assistantId": "agent-b-id" }

  ],

  "memberOverrides": {

    "voice": { "provider": "vapi", "voiceId": "Elliot" },

    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" }

  }

}

Using Squads in Calls

Outbound call with a squad

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"

    }

  }'

Transient squad in a call

{

  "squad": {

    "members": [

      { "assistant": { "..." : "..." } },

      { "assistantId": "..." }

    ]

  },

  "phoneNumberId": "phone-number-id",

  "customer": { "number": "+11234567890" }

}

Common Patterns

Clinic Triage → Scheduling

{

  "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-commerce: Sales → Support → Returns

{

  "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" }

  ]

}

Best Practices

• Keep assistants focused — Each assistant should have 1-3 goals maximum

• Minimize squad size — Split only when there's a clear functional boundary

• Write specific handoff descriptions — The LLM uses these to decide when to transfer

• Mention handoffs in system prompts — Tell each assistant what departments exist

• Use member overrides — Apply consistent voice and transcriber settings across the squad

Managing Squads

# List squads

curl https://api.vapi.ai/squad -H "Authorization: Bearer $VAPI_API_KEY"

# Get a squad

curl https://api.vapi.ai/squad/{id} -H "Authorization: Bearer $VAPI_API_KEY"

# Update a squad

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"}'

# Delete a squad

curl -X DELETE https://api.vapi.ai/squad/{id} \

  -H "Authorization: Bearer $VAPI_API_KEY"

References

• Vapi Squads Docs — Official documentation

• Squad Examples — More patterns

• Handoff Configuration — Detailed handoff guide

Additional Resources

This skills repository includes a Vapi documentation MCP server (vapi-docs) that gives your AI agent access to the full Vapi knowledge base. Use the searchDocs tool to look up anything beyond what this skill covers — advanced configuration, troubleshooting, SDK details, and more.

Auto-configured: If you cloned or installed these skills, the MCP server is already configured via .mcp.json (Claude Code), .cursor/mcp.json (Cursor), or .vscode/mcp.json (VS Code Copilot).

Manual setup: If your agent doesn't auto-detect the config, run:

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

See the README for full setup instructions across all supported agents.