Workflows migration guide

Step 1 — Map your existing workflow

Before building anything in Squads, document what your workflow does:

• List each node and its purpose
• Note the conditions on each edge
• Identify any variables being extracted and where they’re used downstream
• Note any API calls or transfers to phone numbers

Step 2 — Create an assistant for each Conversation Node

Do not assume a 1:1 mapping between Workflow conversation nodes and Squad members. Some workflows include dozens of nodes (e.g. IVR-style menus where each node asks a question and extracts a variable). In these cases, a 1:1 migration usually creates too many assistants and makes the system harder to maintain.

Start by bundling as much of the workflow as you can into a single assistant. Squads work best for linear, unidirectional flows where the conversation moves forward through a predictable sequence of stages. Only split work into a separate assistant when there’s a clear functional boundary and you don’t expect the conversation to bounce back and forth between the two. If two stages would repeatedly hand off to each other throughout a call, consolidate them into one assistant — frequent cyclical handoffs add latency and can introduce hallucinations.

Then:

• Group related nodes into a small number of well-defined stages (e.g. intake → triage → scheduling → human handoff)
• Create one assistant per stage with a clear responsibility and a focused prompt (1–3 goals max)
• Use Handoff tools to move between stages and extract/pass variables at the boundaries
• Attach tools (API requests, transfers, etc.) to the assistant responsible for that stage

For an example of this “stage-based” approach, see the Clinic triage & scheduling example.

Step 3 — Add Handoff tools

Replace your edge conditions with Handoff tools. For each transition:

• Create a Handoff tool on the source assistant
• Set the destination to the next assistant (or phone number for transfers)
• Write a clear description of when to hand off — this replaces your edge condition

For AI-based conditions (e.g. “user wants to talk about pricing”), write the condition in plain language in the Handoff tool description.

For logical conditions (e.g. {{ customer_tier == "VIP" }}), use variable extraction to capture the value, then reference it in the Handoff tool description.

Step 4 — Handle variable extraction

Variables extracted mid-conversation in Workflows are available across the full Squad via the Handoff tool’s variable extraction. Configure variable extraction in each Handoff to pass key data to the next assistant.

Step 5 — Set up your Squad

Group your assistants into a Squad:

• The first member in the members array is the entry point (equivalent to the Start Node)
• Use memberOverrides to standardize settings across all members if needed (e.g. the same voice throughout). To override a single member instead, use assistantOverrides on that member.

1
{
2
  "squad": {
3
    "members": [
4
      { "assistantId": "your-first-assistant-id" },
5
      { "assistantId": "your-second-assistant-id" }
6
    ],
7
    "memberOverrides": {
8
      "voice": {
9
        "provider": "vapi",
10
        "version": 2,
11
        "voiceId": "Elliot"
12
      }
13
    }
14
  }
15
}

Step 6 — Test

Use the built-in calling feature to test all conversation paths before going live. Pay particular attention to:

• Handoff conditions triggering at the right time
• Variables passing correctly between assistants
• Edge cases (confused users, unexpected inputs, human escalation paths)