> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thoughtly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate legacy agents to v1.8 Agent Builder

> Step-by-step guide for rebuilding legacy v1 free-form Thoughtly agents in the v1.8 node-based Agent Builder with parity for prompts, actions, and flows.

export const NextSection = ({title, icon, href, description}) => <div>
		<br />
		<Card title={title} icon={icon} href={href} horizontal="true">
			{description}
		</Card>
	</div>;

<Warning>
  **v1 agents were retired on February 16, 2026.** v1 agents are no longer supported. If you haven't migrated yet, follow this guide to rebuild your agent in v1.8 as soon as possible.
</Warning>

This guide walks you through rebuilding a legacy **v1 "free-form"** agent in the **v1.8 [Agent Builder](/agents/overview)**.

***

## 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](/agents/nodes#start-node), [Speak](/agents/nodes#speak-node), [Transfer](/agents/nodes#transfer-node), [End](/agents/nodes#end-node).
* **Speak** is split into two variants:
  * **Message** (fixed wording, can be verbatim).
  * **Prompt** (adaptive instructions, like a mini playbook).
* [Outcomes](/agents/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](/agents/variables) capture structured data *right after the caller replies and before outcomes evaluate* so outcomes can branch on fresh values.
* [Actions](/agents/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**](/agents/nodes#start-node)                                                          | Start is spoken exactly as written; great for consent/compliance lines.                                       |
| Mixed "message/prompt" block              | [**Speak -> Message**](/agents/nodes#speak-node) or [**Speak -> Prompt**](/agents/nodes#speak-node) | Use **Message + Repeat verbatim** for exact lines; use **Prompt** for dynamic responses.                      |
| Rule-heavy branching                      | [**Outcomes**](/agents/outcomes)                                                                    | Use **rule-based outcomes** for deterministic branching; **prompt-based outcomes** for intent classification. |
| "Ask question + parse answer" via rules   | [**Variables**](/agents/variables)                                                                  | Variables extract before outcomes; define clear extraction instructions.                                      |
| "Jump anywhere", use rules for navigation | **Explicit node connections + loops** via [Outcomes](/agents/outcomes#loops-special-use-case)       | Use outcomes + loop patterns for retries/clarification.                                                       |
| Knowledge stuffed in prompt/rules         | [**Genius knowledge base**](/genius/getting-started) + [attach to agent](/genius/agent-binding)     | 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](/agents/nodes#start-node) or Speak -> Message in [Speak nodes](/agents/nodes#speak-node).
* Your **major branches** (happy path, objections, voicemail/no-answer, escalation) mapped to [Outcomes](/agents/outcomes).
* What data you capture, **if any** (name, email, intent, budget, eligibility) as [Variables](/agents/variables).
* Which integrations you hit, **if any** (CRM lookup, scheduler, webhook, ticketing) as [Actions](/agents/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)](/agents/nodes#start-node) and then flows through numbered nodes (step 1, 2, 3). These step numbers show up during [Testing](/agents/testing) and can be referenced later.

Recommended skeleton:

1. **Start**: tight opener (+ verbatim compliance line if needed).
2. **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](/agents/nodes#speak-node).
3. Branch to a few "big rocks" (for example Qualified / Not qualified / Objection / Transfer) using [Outcomes](/agents/outcomes).
4. **End** nodes for each major ending state (success, voicemail, no-match) using [End nodes](/agents/nodes#end-node).

***

### Step 3: Convert v1 "rules" into outcomes (your new routing layer)

[Outcomes](/agents/outcomes) decide **where the conversation goes after a node**.

Use this rule of thumb:

* **[Prompt-based outcomes](/agents/outcomes#prompt-based-outcomes-ai)**: when you need natural-language classification ("is this an objection?", "are they interested?", "did they ask pricing?").
* **[Rule-based outcomes](/agents/outcomes#rule-based-outcomes-deterministic)**: when you have **Variables** or [Action](/agents/actions) 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](/agents/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](/agents/outcomes#loops-special-use-case).

***

### Step 4: Replace "parsing via rules" with variables

[Variables](/agents/variables) are how you capture structured data for:

* branching in [Outcomes](/agents/outcomes),
* inputs to [Actions](/agents/actions),
* post-call workflows in [Automations](/automations/getting-started).

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](/agents/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](/agents/actions) framework**, with explicit Speak nodes, [Variables](/agents/variables), Actions, and [Outcomes](/agents/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)](/resources/agent-scheduling)**

For action details, see **[Calendly](/integrations/scheduling/calendly)** and **[Cal.com](/integrations/scheduling/cal-com)**.

<Warning>
  **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.
</Warning>

***

### 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](/genius/getting-started):

* Keep content in **Q\&A format** (faster retrieval, better matching).
* Attach the Genius knowledge base to the agent via [Settings -> Genius tab](/agents/settings#genius-tab) or the [Genius binding guide](/genius/agent-binding).

***

### Step 7: Recreate global behavior in Settings (do not bury routing here)

Use [Settings -> Advanced prompt](/agents/settings#advanced-settings) for persona, tone, and guardrails -- **not navigation logic**.

Also migrate/tune:

* **Voice and Language** in [Settings](/agents/settings#main-settings).
* **Presence tuning** (silence timeout; adjust endpointing, sensitivity, retries) in [Settings -> Presence tab](/agents/settings#presence-tab).
* **Voicemail** (keep the message short, avoid sensitive info) in [Settings -> Voicemail](/agents/settings#voicemail).

***

### Step 8: Test like the v1.8 docs recommend (text first, then voice)

Use both built-in testing modes:

* **[Test Agent (text chat)](/agents/testing#test-agent-text-chat)**: fastest for checking outcomes, variables, and action flags.
* **[Call Me (real call)](/agents/testing#call-me-real-call)**: validate TTS, barge-in, endpointing/latency, transfers, and action timing.

***

### Step 9: Cutover (deployment + phone number assignment)

When you are ready to replace v1:

* Assign the appropriate phone number profiles (inbound/outbound/SMS) to the new v1.8 agent. See [Deployment](/agents/deployment) and [Phone Number Configuration](/phone-number/configuration).

***

## Common migration pitfalls (and how to avoid them)

* **Using Prompt when wording must be exact** -> use **Message + Repeat verbatim** (or [Start](/agents/nodes#start-node)).
* **Branching after an Action with prompt-based outcomes** -> use **rule-based outcomes** that check [Action](/agents/actions) flags/results.
* **Vague variable extraction instructions** -> use explicit constraints + "do not invent values" in [Variables](/agents/variables).
* **Special characters being spoken aloud** -> add the "no special characters" instruction to the [Advanced prompt](/agents/settings#advanced-settings) (global fix).
* **Relying on legacy post-call** -> migrate workflows to [Automations](/automations/getting-started) (recommended by docs).

## See also

* [Nodes](/agents/nodes) - Start, Speak, Transfer, End.
* [Outcomes](/agents/outcomes) - routing and loop patterns.
* [Variables](/agents/variables) - extraction and validation.
* [Actions](/agents/actions) - mid-call integrations.
* [Settings](/agents/settings) - voice, presence, and advanced prompt.
* [Testing](/agents/testing) - Test Agent and Call Me.
* [Deployment](/agents/deployment) - go live with phone numbers.
* [Genius](/genius/getting-started) - knowledge base setup.

<NextSection title="Nodes and their Types" icon="diagram-nested" href="/agents/nodes" description="Learn how each node shapes your conversation flow ->" />