Squads

Introduction to Squads (Multi-Assistant Conversations)

Use Squads to handle complex workflows and tasks.

Squads let you break complex workflows into multiple specialized assistants that hand off to each other during a conversation. Each assistant in a Squad handles a specific part of your workflow; for example, one assistant for lead qualification that transfers to another for appointment booking.

Why use Squads? Large, all-in-one assistants with lengthy prompts and extensive context lead to:

  • Higher hallucination rates - Models lose focus with too many and potentially conflicting instructions
  • Increased costs - Longer prompts consume more tokens per request
  • Greater latency - Processing large contexts takes more time and will increase the latency of your assistant.

Squads solve this by splitting complex prompts into focused assistants with specific tools and clear goals, while maintaining full conversation context across handoffs.

View all configurable properties in the API Reference.

Usage

To use Squads, you can create a squad when starting a call and specify members as a list of assistants and destinations. Assistants can be either persistent or transient.

The first member is the assistant that will start the call.

We recommend using Handoff Tools to specify which destinations the current assistant can handoff too, and when to handoff to each assistant. Each assistant within the squad can use its saved handoff tools as well as handoff tools from Assistant Overrides (see below).

1{
2    "squad": {
3        "members": [
4            {
5                "assistantId": "information-gathering-assistant-id",
6            },
7            {
8                "assistant": {
9                    "name": "Appointment Booking",
10                    "model": {
11                        "provider": "openai",
12                        "model": "gpt-4o",
13                        "toolIds": ["handoff-tool-id"],
14                        "tools": [
15                            {
16                                "type": "handoff",
17                                "destinations": [
18                                    {
19                                        "type": "assistant",
20                                        "assistantId": "assistant-123",
21                                        "description": "Call this tool when the customer wants to talk about pricing"
22                                    }
23                                ],
24                                "function": {
25                                    "name": "handoff_to_assistant_123"
26                                }
27                            }
28                        ]
29                    },
30                },
31            }
32        ]
33    }
34}

Overrides

Assistant Overrides

To override the configuration of a saved assistant without modifying the underlying assistant, use the assistantsOverrides to alter individual assistants. For example, if you have assistants in a squad with different voices, you can use assistantOverrides to make sure all of the assistants are using the same voice without changing the assistant (in case it’s being used in another squad).

1{
2    "squad": {
3        "members": [
4            {
5                "assistant": {
6                    "name": "Appointment Booking",
7                    "voice": {
8                        "provider": "vapi",
9                        "voiceId": "Elliot",
10                    },
11                },
12            },
13            {
14                "assistantId": "saved-assistant-id",
15                "assistantOverrides": {
16                    "voice": {
17                        "provider": "vapi",
18                        "voiceId": "Elliot",
19                    },
20                }
21            },
22        ]
23    }
24}

You may also define inline tools via assistantOverrides through the tools:append array, so that the assistant will only handoff if it is a part of this squad.

1{
2    "squad": {
3        "members": [
4            {
5                "assistant": {
6                    "name": "Appointment Booking",
7                    "voice": {
8                        "provider": "vapi",
9                        "voiceId": "Elliot",
10                    },
11                },
12            },
13            {
14                "assistantId": "saved-assistant-id",
15                "assistantOverrides": {
16                    "tools:append": [
17                        {
18                            "type": "handoff",
19                            "destinations": [
20                                {
21                                    "type": "assistant",
22                                    "assistantId": "assistant-123",
23                                    "description": "Call this tool when the customer wants to talk about pricing"
24                                }
25                            ],
26                            "function": {
27                                "name": "handoff_to_assistant_123"
28                            }
29                        }
30                    ]
31                }
32            },
33        ]
34    }
35}

Member Overrides

To override the configuration of all assistants in a squad without modifying the underlying assistants, use the memberOverrides.

Note: This is squadOverrides for the assistant-request webhook response.

1{
2    "squad": {
3        "members": [
4            {
5                "assistant": {
6                    "name": "Appointment Booking",
7                    "voice": {
8                        "provider": "vapi",
9                        "voiceId": "Elliot",
10                    },
11                },
12            },
13            {
14                "assistantId": "saved-assistant-id",
15            },
16        ],
17        "memberOverrides": {
18            "voice": {
19                "provider": "vapi",
20                "voiceId": "Elliot",
21            },
22        }
23    }
24}

Best Practices

Keep assistants focused - Each assistant should have a single, well-defined responsibility with 1-3 goals maximum. Assign only the tools needed for that specific task.

Minimize squad size - Try to reduce the number of squad members. Only split into separate assistants when there’s a clear functional boundary (lead qualification → sales → booking).

Define clear handoff conditions - Write specific handoff descriptions that state exact trigger conditions and what information to collect before transferring. Make sure to specify this in the assistant’s prompt and/or tool description.

Engineer context carefully - Use context engineering to control what conversation history is passed between assistants. As the context grows throughout the call, you may want to limit message history to reduce tokens, improve performance, and prevent context poisoning. Utilize variable extraction to save information and generate summaries during a handoff to pass to other assistants.