This guide walks you through rebuilding a legacy v1 “free-form” agent in the v1.8 Agent Builder.
The migration mindset
v1 let builders “jump around” with rules and loosely structured prompts.
v1.8 is more structured:
- You build a conversation as a graph using four node types: Start, Speak, Transfer, End.
- Speak is split into two variants:
- Message (fixed wording, can be verbatim).
- Prompt (adaptive instructions, like a mini playbook).
- Outcomes decide where the conversation goes next (and are where “rules” belong now). Unlike in v1, outcomes in v1.8 agents are more strict. The agent will not jump from the first node to the last. This allows for more robust workflows while keeping flexibility.
- Variables capture structured data right after the caller replies and before outcomes evaluate so outcomes can branch on fresh values.
- Actions run integrations mid-call and change flow timing.
v1 to v1.8 mapping (quick translation table)
| v1 concept | v1.8 replacement | Notes |
|---|
| ”Opening script” | Start node | Start is spoken exactly as written; great for consent/compliance lines. |
| Mixed “message/prompt” block | Speak -> Message or Speak -> Prompt | Use Message + Repeat verbatim for exact lines; use Prompt for dynamic responses. |
| Rule-heavy branching | Outcomes | Use rule-based outcomes for deterministic branching; prompt-based outcomes for intent classification. |
| ”Ask question + parse answer” via rules | Variables | Variables extract before outcomes; define clear extraction instructions. |
| ”Jump anywhere”, use rules for navigation | Explicit node connections + loops via Outcomes | Use outcomes + loop patterns for retries/clarification. |
| Knowledge stuffed in prompt/rules | Genius knowledge base + attach to agent | Strongly prefer Q&A formatting for retrieval speed and accuracy. |
Step-by-step migration process
Step 1: Inventory your v1 agent (before you touch v1.8)
Create a quick “agent spec” from the v1 setup:
- Primary goal (qualify, schedule, support, collections, and so on).
- Required verbatim lines (consent, disclaimers, identity statements) using Start or Speak -> Message in Speak nodes.
- Your major branches (happy path, objections, voicemail/no-answer, escalation) mapped to Outcomes.
- What data you capture, if any (name, email, intent, budget, eligibility) as Variables.
- Which integrations you hit, if any (CRM lookup, scheduler, webhook, ticketing) as Actions.
This becomes your blueprint for the v1.8 flow.
Step 2: Rebuild the skeleton with nodes
In v1.8, every agent starts with Start (step 0) and then flows through numbered nodes (step 1, 2, 3). These step numbers show up during Testing and can be referenced later.
Recommended skeleton:
- Start: tight opener (+ verbatim compliance line if needed).
- Speak (Prompt): what the agent is supposed to say. Do not put too much text in a single node; if it makes sense, split it. See Speak nodes.
- Branch to a few “big rocks” (for example Qualified / Not qualified / Objection / Transfer) using Outcomes.
- End nodes for each major ending state (success, voicemail, no-match) using End nodes.
Step 3: Convert v1 “rules” into outcomes (your new routing layer)
Outcomes decide where the conversation goes after a node.
Use this rule of thumb:
- Prompt-based outcomes: when you need natural-language classification (“is this an objection?”, “are they interested?”, “did they ask pricing?”).
- Rule-based outcomes: when you have Variables or Action flags and want deterministic logic (recommended after actions).
Migration pattern (common):
- v1: “If user sounds qualified, go to scheduling; else ask more questions.”
- v1.8: Speak node -> prompt-based outcomes:
- “User said something that qualifies them” -> scheduling branch.
- “User did not say something that qualifies them” -> clarification branch.
- Default -> fallback / transfer.
OR
- v1.8: Speak node -> extract Variables -> rule-based outcomes:
qualified == true -> scheduling branch.qualified == false -> clarification branch.- Default -> fallback / transfer.
Loops are a first-class pattern for retries and clarification. Use them deliberately and cap retries. See Loops.
Step 4: Replace “parsing via rules” with variables
Variables are how you capture structured data for:
Key behavior to design around:
- Variables extract immediately after the caller reply and before outcome evaluation.
- You can choose Current speak node vs Conversation history in Variables.
- Re-visiting a node can re-extract and overwrite previous values (useful for confirmation loops).
Step 5: Migrate integrations to Actions (mid-call)
In v1, the only supported mid-call action was Calendly scheduling, and it was tightly coupled to rules and implicit flow behavior.
In v1.8, scheduling is handled through a new mid-call Actions framework, with explicit Speak nodes, Variables, Actions, and Outcomes. Because this is both the only overlapping mid-call capability between v1 and v1.8 and the most structurally different, scheduling migration is covered in a dedicated guide.
Continue here:
Scheduling in v1.8 (Agent Builder)
For action details, see Calendly and Cal.com.
Important: v1 scheduling logic cannot be ported directly. It must be rebuilt using v1.8 patterns (Variables -> Actions -> rule-based Outcomes). Attempting to replicate v1 rule-based scheduling will lead to brittle or broken flows.
Step 6: Move “knowledge inside prompts” into Genius (recommended)
If your v1 agent depended on long prompt/rules to answer FAQs, move that into Genius:
Step 7: Recreate global behavior in Settings (do not bury routing here)
Use Settings -> Advanced prompt for persona, tone, and guardrails — not navigation logic.
Also migrate/tune:
Step 8: Test like the v1.8 docs recommend (text first, then voice)
Use both built-in testing modes:
Step 9: Cutover (deployment + phone number assignment)
When you are ready to replace v1:
Common migration pitfalls (and how to avoid them)
- Using Prompt when wording must be exact -> use Message + Repeat verbatim (or Start).
- Branching after an Action with prompt-based outcomes -> use rule-based outcomes that check Action flags/results.
- Vague variable extraction instructions -> use explicit constraints + “do not invent values” in Variables.
- Special characters being spoken aloud -> add the “no special characters” instruction to the Advanced prompt (global fix).
- Relying on legacy post-call -> migrate workflows to Automations (recommended by docs).
See also
- Nodes - Start, Speak, Transfer, End.
- Outcomes - routing and loop patterns.
- Variables - extraction and validation.
- Actions - mid-call integrations.
- Settings - voice, presence, and advanced prompt.
- Testing - Test Agent and Call Me.
- Deployment - go live with phone numbers.
- Genius - knowledge base setup.
