|
| 1 | +# Vapi Workflows → Squads Migration Guide |
| 2 | + |
| 3 | +A self-contained reference for migrating a Vapi **Workflow** to a **Squad** before Workflows is retired on **August 18, 2026**. |
| 4 | + |
| 5 | +**How to use this file:** Attach it to an AI coding assistant (Claude Code, Composer, Cursor, or any LLM) as context, along with your existing workflow's configuration (the workflow JSON, or a description of its nodes and edges). Ask the assistant to draft the equivalent Squad. The mapping table, steps, and rules below give the model everything it needs to produce a correct, focused Squad without re-reading the docs site. |
| 6 | + |
| 7 | +**Deadline:** Workflows stop running on **August 18, 2026**. From **August 19, 2026** onward, existing workflows will no longer run. Migrate before then to avoid disruption. |
| 8 | + |
| 9 | +**Canonical web version:** https://docs.vapi.ai/workflows/legacy-migration |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +## Table of contents |
| 14 | + |
| 15 | +1. [What's changing](#1-whats-changing) |
| 16 | +2. [Mental model](#2-mental-model) |
| 17 | +3. [Concept mapping (Workflows → Squads)](#3-concept-mapping-workflows--squads) |
| 18 | +4. [Rules an agent should follow](#4-rules-an-agent-should-follow) |
| 19 | +5. [Migration steps](#5-migration-steps) |
| 20 | +6. [Squad configuration reference](#6-squad-configuration-reference) |
| 21 | +7. [Variable extraction](#7-variable-extraction) |
| 22 | +8. [Validation checklist](#8-validation-checklist) |
| 23 | +9. [FAQs](#9-faqs) |
| 24 | +10. [Resources](#10-resources) |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +## 1. What's changing |
| 29 | + |
| 30 | +- Workflows will be retired by **August 18, 2026**. From **August 19, 2026** onward, existing workflows will no longer run. |
| 31 | +- Workflows are no longer recommended for new builds. Use **Assistants** for most cases, or **Squads** for multi-assistant setups. |
| 32 | +- **Squads** is the recommended replacement for Workflows. |
| 33 | +- If you are no longer using Workflows, no action is required. |
| 34 | + |
| 35 | +**Why the change:** current AI systems aren't reliable as fully autonomous graph-walking agents — they struggle to simultaneously hold the current node's instructions and reason about every possible next step and its trigger conditions. The Squads pattern (specialized assistants that hand off to each other) has consistently produced better results. |
| 36 | + |
| 37 | +--- |
| 38 | + |
| 39 | +## 2. Mental model |
| 40 | + |
| 41 | +Instead of a visual graph of nodes and edges, a Squad is a set of specialized **assistants** that **hand off** to each other during one continuous conversation. Each assistant owns one focused part of the conversation, with clear handoff conditions in between. Conversation context is preserved across handoffs. |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## 3. Concept mapping (Workflows → Squads) |
| 46 | + |
| 47 | +| Workflows | Squads | |
| 48 | +| --- | --- | |
| 49 | +| Conversation Node | Squad member (assistant with its own prompt, voice, model, and tools) | |
| 50 | +| Edge condition | Handoff tool with a description of when to transfer | |
| 51 | +| Global Node | Assistant with a broad handoff condition (e.g. "user wants to speak to a human" or "user says hotword") | |
| 52 | +| Extract Variables | Variable extraction in the Handoff tool, passed across the full Squad | |
| 53 | +| API Request Node | Custom or API Request tool attached to a Squad member | |
| 54 | +| Transfer Call Node | Transfer call tool attached to a Squad member | |
| 55 | +| Start Node | First member in the Squad `members` array | |
| 56 | + |
| 57 | +--- |
| 58 | + |
| 59 | +## 4. Rules an agent should follow |
| 60 | + |
| 61 | +These are the most important judgment rules — apply them before generating any Squad: |
| 62 | + |
| 63 | +1. **Do NOT do a 1:1 node-to-assistant mapping.** Workflows often have dozens of nodes (e.g. IVR menus). A 1:1 migration creates too many assistants and is hard to maintain. |
| 64 | +2. **Bundle as much as possible into a single assistant.** Squads work best for **linear, unidirectional** flows. Start with one assistant and only split when there is a clear functional boundary. |
| 65 | +3. **Avoid cyclical handoffs.** If two stages would hand off back and forth repeatedly within one conversation, consolidate them into a single assistant. Frequent cyclical handoffs add latency and can introduce hallucinations. |
| 66 | + - Good fit for separate assistants: a predictable one-directional path like `triage → voicemail → SDR`. |
| 67 | + - Bad fit (consolidate instead): a pair like `SDR ↔ FAQ` that would bounce back and forth many times in a single call. |
| 68 | +4. **Keep each assistant focused.** One clear responsibility, a short prompt, 1–3 goals maximum. Attach only the tools that stage needs. |
| 69 | +5. **One handoff tool per transition.** Replace each edge with a handoff tool on the source assistant, with a plain-language description of when to hand off. |
| 70 | +6. **The first member is the entry point** (equivalent to the Start Node). |
| 71 | + |
| 72 | +--- |
| 73 | + |
| 74 | +## 5. Migration steps |
| 75 | + |
| 76 | +### Step 1 — Map the existing workflow |
| 77 | + |
| 78 | +Document what the workflow does before building anything: |
| 79 | + |
| 80 | +- List each node and its purpose. |
| 81 | +- Note the condition on each edge. |
| 82 | +- Identify every extracted variable and where it's used downstream. |
| 83 | +- Note any API calls or transfers to phone numbers. |
| 84 | + |
| 85 | +### Step 2 — Decide on assistants (consolidate aggressively) |
| 86 | + |
| 87 | +Apply the rules in section 4. Group related nodes into a small number of well-defined **stages** (e.g. `intake → triage → scheduling → human handoff`), then create **one assistant per stage**. Bundle stages that would hand off cyclically into one assistant. |
| 88 | + |
| 89 | +For each assistant: give it a clear responsibility, a focused prompt (1–3 goals), and only the tools it needs (API requests, transfers, etc.). |
| 90 | + |
| 91 | +Stage-based example: https://docs.vapi.ai/squads/examples/clinic-triage-scheduling-handoff-tool |
| 92 | + |
| 93 | +### Step 3 — Add handoff tools (replace edges) |
| 94 | + |
| 95 | +For each transition between stages, add a [Handoff tool](https://docs.vapi.ai/squads/handoff) on the source assistant: |
| 96 | + |
| 97 | +- Set the destination to the next assistant (or a phone number for transfers). |
| 98 | +- Write a clear description of **when** to hand off — this replaces the edge condition. |
| 99 | +- For AI-based conditions (e.g. "user wants to talk about pricing"), describe the condition in plain language. |
| 100 | +- For logical conditions (e.g. `{{ customer_tier == "VIP" }}`), extract the value first (see Step 4), then reference it in the handoff tool description. |
| 101 | + |
| 102 | +### Step 4 — Handle variable extraction |
| 103 | + |
| 104 | +Configure variable extraction in each handoff so key data passes to the next assistant. Variables extracted mid-conversation are available across the full Squad. See section 7 for the important caveats. |
| 105 | + |
| 106 | +### Step 5 — Assemble the Squad |
| 107 | + |
| 108 | +- The first member in the `members` array is the entry point. |
| 109 | +- Use `memberOverrides` to standardize settings across **all** members (e.g. the same voice throughout). To override a **single** member, use `assistantOverrides` on that member. |
| 110 | + |
| 111 | +See section 6 for config. |
| 112 | + |
| 113 | +### Step 6 — Test |
| 114 | + |
| 115 | +Use the built-in calling feature to test all conversation paths before going live. Check: |
| 116 | + |
| 117 | +- Handoff conditions trigger at the right time. |
| 118 | +- Variables pass correctly between assistants. |
| 119 | +- Edge cases: confused users, unexpected inputs, human-escalation paths. |
| 120 | + |
| 121 | +--- |
| 122 | + |
| 123 | +## 6. Squad configuration reference |
| 124 | + |
| 125 | +Minimal Squad with a squad-wide voice override (`memberOverrides`): |
| 126 | + |
| 127 | +```json |
| 128 | +{ |
| 129 | + "squad": { |
| 130 | + "members": [ |
| 131 | + { "assistantId": "your-first-assistant-id" }, |
| 132 | + { "assistantId": "your-second-assistant-id" } |
| 133 | + ], |
| 134 | + "memberOverrides": { |
| 135 | + "voice": { |
| 136 | + "provider": "vapi", |
| 137 | + "version": 2, |
| 138 | + "voiceId": "Elliot" |
| 139 | + } |
| 140 | + } |
| 141 | + } |
| 142 | +} |
| 143 | +``` |
| 144 | + |
| 145 | +- `members` — ordered array; index 0 is the entry point (Start Node equivalent). Each member is either `{ "assistantId": "..." }` (saved assistant) or `{ "assistant": { ... } }` (transient, inline assistant). |
| 146 | +- `memberOverrides` — overrides applied to **all** members without modifying the underlying assistants. Use for squad-wide settings like voice. |
| 147 | +- `assistantOverrides` — set **on an individual member** to override just that one assistant. |
| 148 | + |
| 149 | +Using Workflows via API? Replace `workflowId` with `squadId` in your call configuration. Squads API reference: https://docs.vapi.ai/api-reference/squads/create |
| 150 | + |
| 151 | +--- |
| 152 | + |
| 153 | +## 7. Variable extraction |
| 154 | + |
| 155 | +Configure variable extraction in each [Handoff tool](https://docs.vapi.ai/squads/handoff#variable-extraction) to pass data to the next assistant. |
| 156 | + |
| 157 | +**How it differs from Workflows:** Squads extract variables with an LLM at handoff time (a schema-driven extraction against the conversation transcript), then pass them to the next assistant. This is **best-effort, not deterministic**: |
| 158 | + |
| 159 | +- If a value isn't clearly present in the conversation, or a transient model error occurs, extraction can return empty — and the handoff still proceeds. |
| 160 | +- Define clear extraction schemas, and **test that business-critical variables are reliably captured** before depending on them downstream. |
| 161 | +- For strictly deterministic values, capture them via a tool or API response rather than relying on transcript extraction. |
| 162 | + |
| 163 | +Control what conversation context carries across a handoff with context engineering: https://docs.vapi.ai/squads/handoff#context-engineering |
| 164 | + |
| 165 | +--- |
| 166 | + |
| 167 | +## 8. Validation checklist |
| 168 | + |
| 169 | +Before going live, verify: |
| 170 | + |
| 171 | +- [ ] Each Conversation Node's logic is captured (stages consolidated where appropriate). |
| 172 | +- [ ] Assistants are kept to the minimum needed; no cyclical handoff pairs remain split. |
| 173 | +- [ ] Every handoff condition triggers at the right time. |
| 174 | +- [ ] Variable extraction passes the right data between assistants. |
| 175 | +- [ ] Tools, API requests, and transfers are attached to the correct assistant. |
| 176 | +- [ ] Business-critical variables are reliably extracted (tested, not assumed). |
| 177 | +- [ ] Test calls cover **all** conversation paths, including edge cases. |
| 178 | +- [ ] API integrations send `squadId` instead of `workflowId`. |
| 179 | + |
| 180 | +--- |
| 181 | + |
| 182 | +## 9. FAQs |
| 183 | + |
| 184 | +**Why is Workflows being retired?** Squads consistently produces better results for customers. Rather than maintaining two parallel products, Vapi is going all-in on Squads. |
| 185 | + |
| 186 | +**Will my workflows stop working immediately on the deprecation date?** Yes. After August 18, 2026, existing workflows will no longer run. Complete your migration before then. |
| 187 | + |
| 188 | +**Do I need to rebuild everything from scratch?** No — the concepts map closely. Each Conversation Node becomes a Squad member and each edge becomes a Handoff tool. The main work is rewriting prompts to be more focused and configuring handoff tools with clear transfer conditions. |
| 189 | + |
| 190 | +**What if I need deterministic routing?** For strict logical conditions (e.g. `{{ customer_tier == "VIP" }}`), extract the relevant variable first and reference it in the handoff tool description. For edge cases, contact support@vapi.ai. |
| 191 | + |
| 192 | +**What happens to my workflow data?** Historical call data remains accessible in your call logs. Workflows-specific post-call data (nodes traversed, extracted variables from Workflow runs) remains viewable for existing calls. |
| 193 | + |
| 194 | +**I'm using Workflows via API — do I need to change my integration?** Yes. Switch from passing `workflowId` to passing `squadId`. See https://docs.vapi.ai/api-reference/squads/create |
| 195 | + |
| 196 | +**Can I get help migrating?** Contact support@vapi.ai. High-volume users can arrange a walkthrough. Vapi also added a **Composer skill** that auto-drafts a Squad from your existing workflow — open Composer in your dashboard and ask "help me migrate my workflows to squads." It's a best-effort starting point; always review and test before going live. |
| 197 | + |
| 198 | +--- |
| 199 | + |
| 200 | +## 10. Resources |
| 201 | + |
| 202 | +- Migration guide (web): https://docs.vapi.ai/workflows/legacy-migration |
| 203 | +- Squads overview: https://docs.vapi.ai/squads |
| 204 | +- Squads quickstart: https://docs.vapi.ai/squads-example |
| 205 | +- Handoff tool: https://docs.vapi.ai/squads/handoff |
| 206 | +- Variable extraction: https://docs.vapi.ai/squads/handoff#variable-extraction |
| 207 | +- Context engineering: https://docs.vapi.ai/squads/handoff#context-engineering |
| 208 | +- Squads API reference: https://docs.vapi.ai/api-reference/squads/create |
| 209 | +- Clinic triage & scheduling example: https://docs.vapi.ai/squads/examples/clinic-triage-scheduling-handoff-tool |
0 commit comments