# Vapi Squads — Multi-Agent Voice Routing in One Call

> Vapi Squads route calls between multiple voice agents in one call. Greeter routes to specialist, hands back to closer. Replaces mega-prompt assistants.

## Install

Copy the content below into your project:

## Quick Use

1. Have at least 2 Vapi assistants created (greeter + specialist)
2. POST a squad definition to `/squad` with assistantDestinations between members
3. Start a call with `squadId` in the call request — Vapi handles transfers automatically

---

## Intro

Vapi Squads connect multiple voice agents into a single coordinated stack — caller starts with a Greeter, who hands off mid-call to a Specialist, who routes back to a Closer. Each agent has its own system prompt, tools, and voice. Best for: voice products where a single mega-prompt becomes brittle (e.g. medical intake → triage → scheduling). Works with: Vapi platform; Squads can include Workflows or free-form assistants. Setup time: 5 minutes (define agents → wire transfers).

---

### Why split into a squad

A single prompt that says "Be a hotel concierge AND handle bookings AND transfer to maintenance AND…" produces an agent that's mediocre at everything. Squads let you write three small focused prompts:

- **Greeter** (warm, redirects fast)
- **BookingSpecialist** (knows pricing, calendar, upgrades)
- **MaintenanceTriage** (categorizes issues, transfers to humans)

Each has its own toolset and voice. The squad routes between them based on intent.

### Define a squad

```bash
curl -X POST https://api.vapi.ai/squad \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -d '{
    "name": "Acme Concierge Squad",
    "members": [
      {
        "assistantId": "greeter-id",
        "assistantDestinations": [
          { "type": "assistant", "assistantName": "BookingSpecialist", "message": "Let me transfer you to our booking specialist." },
          { "type": "assistant", "assistantName": "MaintenanceTriage", "message": "Connecting you to maintenance." }
        ]
      },
      {
        "assistantId": "booking-specialist-id",
        "assistantDestinations": [
          { "type": "assistant", "assistantName": "Greeter", "message": "Anything else I can help with?" }
        ]
      },
      {
        "assistantId": "maintenance-triage-id",
        "assistantDestinations": [
          { "type": "assistant", "assistantName": "Greeter" }
        ]
      }
    ]
  }'
```

### How transfers happen

Inside the **Greeter's** system prompt, you give the LLM tool access to a `transferCall` function with destinations declared in the squad. When the LLM detects intent, it calls the function and Vapi swaps in the next assistant — keeping the audio session alive, no re-dial.

```
Greeter: "Hi, Acme Hotels. How can I help?"
User:    "I'd like to book a room for next weekend."
Greeter: [calls transferCall(destination: "BookingSpecialist")]
         "Let me transfer you to our booking specialist."
[BookingSpecialist takes over with full conversation context]
BookingSpecialist: "Hi! I see you're looking to book for next weekend. What city?"
```

The user perceives one continuous call.

### Squad vs single assistant with tools

| Squad | Single + Tools |
|---|---|
| Each agent has independent voice / language / model | One voice for everything |
| Easy to A/B test specialists individually | Have to A/B the whole stack |
| Smaller, focused prompts | One mega-prompt |
| Best for >2-3 distinct personas | Fine for 1-2 |

---

### FAQ

**Q: Does the next assistant get the conversation history?**
A: Yes — Squad transfers preserve the full conversation context so the receiving agent doesn't ask the same questions twice. You can also pass an explicit `transferContext` if you want to summarize state in custom format.

**Q: Can a Squad include a Workflow?**
A: Yes — a Squad member can be either a free-form assistant OR a Workflow. Useful pattern: Greeter is free-form (handles small talk), BookingSpecialist is a Workflow (script-driven booking flow).

**Q: How is this different from Workflow's transfer node?**
A: Workflow's transfer is one-way (pass the call to a human or another assistant and don't come back). Squad transfers are bidirectional — the BookingSpecialist can hand back to Greeter when the booking is done. Squads are state-aware; Workflow transfers are exits.

---

## Source & Thanks

> Built by [Vapi](https://github.com/VapiAI). Commercial product with free trial.
>
> [docs.vapi.ai/squads](https://docs.vapi.ai/squads) — Official docs

---

<!-- ZH -->

## 快速使用

1. 至少创建 2 个 Vapi assistant（greeter + specialist）
2. 把 squad 定义 POST 到 `/squad`，成员之间设 assistantDestinations
3. 拨打时传 `squadId`，Vapi 自动处理切换

---

## 简介

Vapi Squads 把多个语音 agent 接成一个协调栈 —— 用户进来先碰 Greeter，通话中切给 Specialist，再交给 Closer 收尾。每个 agent 有自己的系统 prompt、工具、声音。适合单一 mega-prompt 变脆的语音产品（比如医疗问诊 → 分诊 → 预约）。Vapi 平台原生，Squad 可以包含 Workflow 或自由 assistant。装机时间 5 分钟（定义 agent → 接转接）。

---

### 为什么拆成 squad

单一 prompt 说「当酒店礼宾 AND 处理预订 AND 转给维修 AND…」做出来的 agent 各方面都平庸。Squad 让你写三个聚焦的小 prompt：

- **Greeter**（热情、转接快）
- **BookingSpecialist**（懂价格 / 日历 / 升级）
- **MaintenanceTriage**（问题分类、转真人）

各自有自己的工具集和声音。Squad 按意图在它们之间路由。

### 定义 squad

```bash
curl -X POST https://api.vapi.ai/squad \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -d '{
    "name": "Acme Concierge Squad",
    "members": [
      {
        "assistantId": "greeter-id",
        "assistantDestinations": [
          { "type": "assistant", "assistantName": "BookingSpecialist", "message": "Let me transfer you to our booking specialist." },
          { "type": "assistant", "assistantName": "MaintenanceTriage", "message": "Connecting you to maintenance." }
        ]
      },
      {
        "assistantId": "booking-specialist-id",
        "assistantDestinations": [
          { "type": "assistant", "assistantName": "Greeter", "message": "Anything else I can help with?" }
        ]
      },
      {
        "assistantId": "maintenance-triage-id",
        "assistantDestinations": [
          { "type": "assistant", "assistantName": "Greeter" }
        ]
      }
    ]
  }'
```

### 切换怎么发生

在 **Greeter** 的系统 prompt 里给 LLM 一个 `transferCall` 工具，目的地由 squad 声明。LLM 检测到意图就调这个函数，Vapi 切换到下一个 assistant —— 音频会话保持，不重新拨号。

```
Greeter: "Hi, Acme Hotels. How can I help?"
User:    "I'd like to book a room for next weekend."
Greeter: [调 transferCall(destination: "BookingSpecialist")]
         "Let me transfer you to our booking specialist."
[BookingSpecialist 接管，带完整对话上下文]
BookingSpecialist: "Hi! I see you're looking to book for next weekend. What city?"
```

用户感觉是一通连续的电话。

### Squad vs 单 assistant + 工具

| Squad | Single + Tools |
|---|---|
| 每个 agent 独立声音 / 语言 / 模型 | 一种声音覆盖所有 |
| 单独 A/B 测试某个 specialist 容易 | 必须整栈 A/B |
| 聚焦小 prompt | 一个 mega-prompt |
| >2-3 种不同人设最合适 | 1-2 种够用 |

---

### FAQ

**Q: 下一个 assistant 拿到对话历史吗？**
A: 拿到 —— Squad 切换保留完整对话上下文，接管的 agent 不会重问已经问过的问题。也能用显式的 `transferContext` 把状态按你想要的格式汇总传递。

**Q: Squad 能包含 Workflow 吗？**
A: 能 —— Squad 成员可以是自由 assistant 或 Workflow。常见组合：Greeter 自由（处理寒暄），BookingSpecialist 是 Workflow（脚本化预订流）。

**Q: 跟 Workflow 的 transfer 节点啥区别？**
A: Workflow 的 transfer 是单向（把通话交给真人或另一个 assistant 后不再回来）。Squad 切换是双向 —— BookingSpecialist 完事可以交回 Greeter。Squad 有状态感知，Workflow transfer 是退出。

---

## 来源与感谢

> Built by [Vapi](https://github.com/VapiAI). Commercial product with free trial.
>
> [docs.vapi.ai/squads](https://docs.vapi.ai/squads) — Official docs


---
Source: https://tokrepo.com/en/workflows/vapi-squads-multi-agent-voice-routing-in-one-call
Author: Vapi