Conversation Flows (Flows/Playbooks)

A conversation flow is a multi-step script ("playbook") that guides your AI agent through a conversation step by step – e.g. first greet, then clarify the request, then close an appointment or an order. Use this module when your conversations should follow a fixed sequence, instead of the agent chatting freely. You can find the section in the agent editor under the "Conversation flow" card.

When the flow is switched on, the agent always knows which stage (phase) it is currently in, what it needs to achieve there – and it advances to the next stage by itself as soon as the goal is met. Technically, the agent uses a built-in tool called advance_stage for this; you do not have to configure it yourself, it happens automatically.

How to set up a flow

Step 1: Activate the flow. At the top right of the card you will see a toggle labelled "Enabled" / "Disabled". - What it does: Switches the entire playbook on or off. If it is set to "Disabled", the agent ignores all stages and replies freely (based only on persona, knowledge base and routing). - Default: Disabled (off). - Recommendation: Leave the flow off as long as you have not created any stages. Only switch it to "Enabled" once at least two meaningful stages exist – a single step adds no value.

Step 2: Add the first stage. As long as no stage exists yet, you will see the note "No stages yet" and an "Add stage" button. Click it. A new stage with the placeholder name "New stage" is created and expanded straight away so you can fill it in.

Step 3: Fill in the four fields of each stage. Each stage is expandable (click the name) and contains exactly four input fields:

• Name – the display name of the stage (e.g. "Greeting", "Clarify request", "Arrange appointment", "Closing").
• What it does: it helps you find your way around the list and is passed to the agent as the phase heading (e.g. "Phase 2/4: Clarify request").
• Default: "New stage" (English placeholder – please be sure to overwrite it).

• Recommendation: A short, unambiguous label in your business language. Required in effect; a stage without a name is shown in the list as "(no name)".

• Goal – what the agent needs to achieve in this phase.

• What it does: gives the agent the success criterion for the phase. Example placeholder: "What the agent needs to achieve in this stage".
• Default: empty.

• Recommendation: A clear, verifiable sentence, e.g. "Find out whether the guest wants a table for today or another day." Leaving it empty is allowed, but then the agent lacks direction.

• Instructions – what the agent should say or ask in this phase (multi-line text field).

• What it does: the concrete conversation guide for this phase. Placeholder: "What the agent should say/ask in this stage".
• Default: empty.

• Recommendation: Phrase the actual questions/sentences here, e.g. "Ask for the date, time and number of people. Mention that we can also note any allergies." Feel free to be detailed here – the field is multi-line and has no length limit.

• Advance when… – the condition from which the phase is considered complete (internally: success criteria).

• What it does: tells the agent when it may jump to the next phase via advance_stage. Placeholder: "e.g. user has given email AND described their use case".
• Default: empty.
• Recommendation: An unambiguous completion condition, ideally with "AND"/"OR", e.g. "Guest has given date, time AND number of people." If this field is left empty, the agent decides for itself when to advance – which is fuzzier.

Step 4: Set the order. The order of the stages is decisive – it is your script from top to bottom. Each stage carries a number on the left (1, 2, 3 …). Use the arrow buttons "Move up" and "Move down" to reposition a stage. - The agent automatically starts every new conversation in stage 1 (the topmost one). - Without an explicit goal, the agent always jumps to the next stage in the order. So make sure the order matches the natural course of the conversation.

Step 5: Add further stages. Use the "Add stage" button (now at the bottom below the list) to add further phases. Repeat step 3 for each one.

Step 6: Delete a stage. Use the bin icon on the right of the stage row to remove a stage. There is no additional confirmation prompt – the stage is gone after the click (as usual, this is only saved when you save the agent).

Step 7: Save. Save the agent as usual. Only then does the flow apply to new conversations.

How the agent "works through" the flow

• At each new conversation the agent begins in stage 1.
• With each reply the agent is told: which phase it is in (e.g. "Phase 2/4"), the Goal, the Instructions and the "Advance when…" condition.
• Once the goal is met, the agent calls advance_stage on its own and moves on one phase. This step is logged in the conversation (from which phase to which, with a reason) – you will see this later in the AI Debug section in the "Traces" and in the "Decision flow" (see the AI Debug chapter).
• If the agent is already in the last phase, it stays there ("Already at the final stage").
• The flow runs on all channels – web chat, WhatsApp, SMS, email and phone (voice). On the phone channel the same stages and the same advance_stage tool are used.

Tips & pitfalls

• Don't forget the toggle. Creating stages is not enough – without the toggle set to "Enabled", the flow is completely ignored.
• Overwrite the "New stage" placeholder. The default name is in English. Don't leave it as is, otherwise your guest will see "New stage" as the phase label.
• Order = script. Since the agent stubbornly jumps to the next stage in the list without an explicit goal, a wrong order leads to illogical conversations. Check the numbering.
• Phrase "Advance when…" concretely. Vague conditions cause the agent to advance too early or too late. The more precise (with "AND"/"OR"), the more reliable.
• Too many stages = rigid conversations. A flow with 8 tiny steps feels mechanical. Keep it as coarse as possible – usually 3 to 5 meaningful phases are enough.
• Empty fields are allowed, but fuzzy. Only Name is actually needed; Goal, Instructions and Advance when… may be left empty. But the more you leave empty, the more the agent improvises – which undermines the whole point of a playbook.
• Deletion without confirmation. The bin removes a stage immediately. Don't accidentally delete something – if you do, recreate it (there is no "Undo" function).
• The flow does not replace the knowledge base. Stages control the course of the conversation; the agent still draws the content of its answers from the persona and the knowledge base. The two complement each other.