Skip to content

Commit fc5b859

Browse files
betzlermeowbetzlermeow
committed
docs: add workflows deprecation migration guide
1 parent 48d019f commit fc5b859

File tree

1 file changed

+135
-0
lines changed

1 file changed

+135
-0
lines changed

‎fern/workflows/deprecation-migration.mdx‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Workflows deprecation migration guide
3+
subtitle: Workflows will be deprecated on May 31, 2026. Here's what changed and how to migrate to Squads.
4+
slug: workflows/deprecation-migration
5+
---
6+
7+
## Workflows are being deprecated
8+
9+
Workflows are being replaced by [Squads](/squads) — a more flexible, production-ready way to orchestrate multi-step voice AI conversations. Squads give you the same multi-turn capabilities as Workflows, but with clearer abstractions, easier debugging, and tighter integration with the rest of the Vapi platform.
10+
11+
<Note>
12+
**Action required by May 31, 2026.** After this date, Workflows will no longer be supported. Please migrate your existing Workflows to Squads before the deadline to avoid any service disruption.
13+
</Note>
14+
15+
## What this means
16+
17+
- **New Workflows** can no longer be created — use [Squads](/squads) instead for any new development
18+
- **Existing Workflows** will continue to function until May 31, 2026
19+
- **After May 31, 2026**, all remaining Workflows will stop working — you must migrate to Squads before this date
20+
- **Squads are generally available** and ready for production use today
21+
22+
## Concept mapping
23+
24+
Each Workflow concept has a direct equivalent in Squads. Use this table to understand how your existing Workflow logic maps to the new system.
25+
26+
| Workflow Concept | Squad Equivalent | Notes |
27+
|---|---|---|
28+
| Conversation Node | Squad member | Each node becomes an individual assistant (squad member) with its own system prompt and tools |
29+
| Edge condition | [Handoff tool](/squads/handoff) | Transition logic moves into the handoff tool's condition configuration |
30+
| Global Node | Assistant with broad handoff condition | Create a squad member that can be reached from any other member via handoff conditions |
31+
| Extract Variables | Variable extraction in [Handoff tool](/squads/handoff) | Data extraction is configured directly within the handoff tool definition |
32+
| API Request Node | [Function tool](/tools/function) | External API calls are handled through function tools attached to squad members |
33+
| Transfer Call Node | [Handoff tool](/squads/handoff) with phone number | Use a handoff tool configured with a destination phone number for call transfers |
34+
35+
<Note>
36+
**Squads offer more flexibility.** While Workflows used a graph-based visual editor, Squads let you define each assistant independently with its own tools, prompts, and handoff logic. This makes complex flows easier to build, test, and maintain.
37+
</Note>
38+
39+
## How to migrate
40+
41+
Follow these steps to migrate an existing Workflow to a Squad.
42+
43+
### Step 1: Map your nodes to squad members
44+
45+
Review each Conversation Node in your Workflow. Each node becomes a **squad member** — an individual assistant with its own system prompt, model, voice, and tools.
46+
47+
- Copy the system prompt from each node into a new assistant
48+
- Assign the appropriate model and voice to each assistant
49+
- Note which node is your entry point — this becomes your first squad member
50+
51+
### Step 2: Convert edges to handoff tools
52+
53+
For each edge (transition) between nodes in your Workflow:
54+
55+
1. Create a [handoff tool](/squads/handoff) on the source squad member
56+
2. Set the **destination** to the target squad member
57+
3. Define the **condition** that triggers the handoff (this replaces your edge condition logic)
58+
4. Configure any **variable extraction** needed during the handoff (this replaces Extract Variables nodes)
59+
60+
### Step 3: Replace API Request Nodes with function tools
61+
62+
For each API Request Node in your Workflow:
63+
64+
1. Create a [function tool](/tools/function) with the same endpoint configuration
65+
2. Attach the function tool to the appropriate squad member
66+
3. Update your server URL to handle the tool call and return the response
67+
68+
### Step 4: Handle call transfers
69+
70+
If your Workflow uses Transfer Call Nodes:
71+
72+
1. Create a [handoff tool](/squads/handoff) with the destination phone number
73+
2. Attach it to the squad member that initiates the transfer
74+
3. Define the condition under which the transfer should occur
75+
76+
### Step 5: Test your Squad
77+
78+
1. Create the Squad with all your configured squad members
79+
2. Test each conversation path to verify handoffs trigger correctly
80+
3. Confirm variable extraction and function tool calls work as expected
81+
4. Validate call transfers connect to the correct destinations
82+
83+
## Reference links
84+
85+
<CardGroup cols={3}>
86+
<Card
87+
title="Squads overview"
88+
icon="fa-light fa-users"
89+
href="/squads"
90+
>
91+
Learn how Squads work and how to configure multi-assistant conversations.
92+
</Card>
93+
<Card
94+
title="Handoff tool"
95+
icon="fa-light fa-hand-holding-hand"
96+
href="/squads/handoff"
97+
>
98+
Configure transitions between squad members with conditions and variable extraction.
99+
</Card>
100+
<Card
101+
title="Squads quickstart"
102+
icon="fa-light fa-bolt-lightning"
103+
href="/squads-example"
104+
>
105+
Build your first Squad with a step-by-step example.
106+
</Card>
107+
</CardGroup>
108+
109+
## FAQs
110+
111+
<AccordionGroup>
112+
<Accordion title="What happens after May 31, 2026?">
113+
After May 31, 2026, all Workflows will stop functioning. Any assistants or phone numbers still relying on Workflows will no longer work. You must migrate to Squads before this date.
114+
</Accordion>
115+
116+
<Accordion title="Can I still view my existing Workflows?">
117+
Yes. Existing Workflows remain visible and functional until May 31, 2026. However, you cannot create new Workflows — use Squads for any new development.
118+
</Accordion>
119+
120+
<Accordion title="Is there an automated migration tool?">
121+
There is no automated migration tool at this time. You'll need to manually recreate your Workflow logic using Squads. The concept mapping table above provides a direct translation for each Workflow component.
122+
</Accordion>
123+
124+
<Accordion title="Are Squads priced differently than Workflows?">
125+
Squads follow the same pricing model as other Vapi features. There are no additional charges for using Squads versus Workflows.
126+
</Accordion>
127+
128+
<Accordion title="My Workflow is complex — where do I start?">
129+
Start by mapping out your nodes and edges on paper. Convert each node to a squad member, then add handoff tools for each edge. Test one conversation path at a time. If you need help, reach out to [support@vapi.ai](mailto:support@vapi.ai).
130+
</Accordion>
131+
132+
<Accordion title="Who can I contact if I have questions?">
133+
Reach out to [support@vapi.ai](mailto:support@vapi.ai) or contact your account team if you're an Enterprise customer.
134+
</Accordion>
135+
</AccordionGroup>

0 commit comments

Comments
 (0)