Migrate a Flow to Teams

A Flow that has grown past forty nodes is usually three conversations wearing a trench coat. Splitting it into a Team gives each stage its own prompt, its own tools, and its own test suite.

When to migrate

• The canvas no longer fits on a screen — Node count past roughly forty is the practical readability ceiling.
• Different stages need different tools — Your intake stage needs a CRM and your support stage needs a knowledge base — keeping both loaded on every turn costs latency.
• Two teams own two halves — Sales owns qualification, support owns troubleshooting, and they keep colliding in the same graph.
• Callers ask open questions mid-script — Freeform members handle the long tail that a Collect node cannot.

Map nodes to members

Start by drawing boundaries on the existing canvas. Each contiguous cluster that shares a goal and a tool set becomes one Team member. Edges that cross a boundary become handoffs.

Preserve the variable bag

Team members share the same call-scoped variable bag as Flow nodes, so anything a Collect node wrote is readable by the next member. Declare the fields each member requires so a handoff fails loudly during testing rather than quietly on a live call.

team: appointment_desk
members:
  - name: router
    role: entry
    handoffs:
      - to: intake
        when: intent in ["book", "reschedule"]
      - to: support
        when: intent == "question"
  - name: intake
    requires: [caller_name, requested_window]
    handoffs:
      - to: fulfilment
        when: requested_window is set
  - name: fulfilment
    tools: [calendar.create_event, crm.upsert_contact]
    exit_tags: [booked, no_availability]

Migration steps

1. 1

   Duplicate the Flow

   Work from a copy. The live Flow keeps serving calls until the Team is proven.

2. 2

   Create the Team shell

   In Creator, New → Team. Add one empty member per cluster you identified.

3. 3

   Port one cluster at a time

   Move a cluster's local instructions into the member's prompt and reattach its tools. Publish and test after each cluster, not at the end.

4. 4

   Rebuild the routing

   Convert Intent and Branch edges into handoff conditions on the router member.

5. 5

   Copy the test suite

   Point your existing Testing Lab scenarios at the Team. Passing the same suite is the migration's definition of done.

6. 6

   Cut over

   Repoint the phone number at the Team. Keep the Flow published for a week so rollback is one click.

What changes for callers

Nothing audible, if you do it right. Handoffs are silent by default — no hold music, no reintroduction. Enable a spoken handoff line only where a human-perceptible change of role helps, such as moving from an automated intake to a specialist.

What changes for you

• Reporting gains a dimension — Call Logs now show which member handled each segment and where handoffs occurred.
• Latency profile shifts — Smaller per-member prompts usually get faster, but each handoff adds a short planning step.
• Testing gets narrower — You can test a single member in isolation instead of driving the whole graph every run.