Skip to main content

Guided agents best practices

A guided agent is only as good as the way you've broken the work down. The builder makes it easy to wire nodes together - these practices keep the result predictable, debuggable, and safe to publish. Read them after you've built your first flow on the flow canvas and configured a Conversational Agent node.

Choose guided when the steps must be consistent​

The first decision is whether the use case even wants a guided agent. Use this table.

Build a…When the work is…Examples
Conversational agentOpen-ended - the answer is worked out per message from your knowledge, and the path varies user to user.Troubleshooting, support, diagnosing errors, guiding someone to a resolution step by step.
Guided agentMulti-step and must run the same way every time - every run should be consistent and auditable, with nothing skipped.Order returns, loan applications, KYC checks, booking an appointment.

If you can't predict the order of steps, you want a conversational agent. If skipping a step is a compliance or correctness problem - collecting consent, verifying identity, confirming an amount before a charge - you want a guided agent so the sequence is enforced, not left to the model's judgement.

Tip - start conversational, graduate to guided. If a conversational agent keeps getting one multi-step journey wrong (it asks for things out of order, or finishes without confirming), that's the signal to rebuild that journey as a guided agent. You don't have to convert the whole bot.

One node, one job​

Each Conversational Agent node should do exactly one thing and then exit. "Collect the order ID", "Check return eligibility", "Book the pickup slot" - three nodes, not one node trying to do all three.

Why this matters:

  • Adherence. A node with a single, scoped goal follows its instructions far more reliably than one juggling several.
  • Debuggability. When a run goes wrong, a narrow node tells you exactly which step failed. A do-everything node leaves you guessing.
  • Reuse of exits. Distinct jobs produce distinct outcomes, which gives you clean exit labels to branch on (see below).

A good test: if you can't name a node in three or four words ("Collect order ID"), it's probably doing too much. Split it.

Note: "One job" is about the node's goal, not its turn count. A single node may take several turns with the user to finish its one job (ask, re-ask on bad input, confirm) - that's fine. What you're avoiding is one node owning multiple unrelated jobs.

Write sharp exit labels and descriptions​

A node's Exits are the outcomes it can finish on. Each exit is a short label chip plus a natural-language description, and each exit is what you wire a branch from. Good exits are the backbone of a reliable flow.

  • Label = the outcome, in a word or two. eligible, not_eligible, slot_booked, max_retry. The label is what shows on the node's output handle and what you connect on the canvas, so keep it short and meaningful at a glance.
  • Description = when this exit fires, in plain language. This is how the agent decides which exit to take, so be specific: "if the item is within the 30-day window and unopened" beats "eligible". For a retry exit, describe the give-up condition: "when the user can't provide a valid order ID after 3 attempts".
  • Cover the unhappy paths. Don't only model success. Add exits for the user refusing, an item being out of policy, or the agent running out of retries - otherwise the flow has nowhere to go when reality doesn't cooperate. The runtime also surfaces an on_error path for unexpected failures; wire it somewhere graceful (a handoff, an apology, a retry), don't leave it dangling.

Tip - match exits to branches. Every exit you define should map to a distinct downstream behaviour. If two exits always go to the same next node, they probably should be one exit. If one exit needs to fork based on a value, that decision belongs in the next node's instructions and its exits, not crammed into this one.

Wire every exit​

An exit with nothing connected to it is a dead end: when the agent finishes on that outcome, the run has nowhere to go. Before you publish, walk every node and confirm each exit handle - including max_retry and on_error - connects to a next node (or to a deliberate end of the flow).

Practical habit: build the happy path end-to-end first, then go back and wire each node's failure and retry exits. Common destinations for the unhappy paths:

  • An Execute Workflow node that logs the drop-off or files a ticket.
  • A Transfer to Agent node that hands the user to a human when the flow can't resolve it.
  • Back to an earlier node to re-collect input (a back-edge to a different node - for example, "amount wrong" routing from a confirm node back to the collect node).

Use the canvas auto-layout and minimap to scan for orphaned handles, and run the flow in Execute to catch any branch that silently terminates.

Keep each node's instructions scoped​

A node's Instructions are its goal and prompt - the rich-text editor in the right column of the node config. Write them for the one job the node owns, and nothing else.

  • State the goal, the inputs to collect, and the finish condition. "Collect the order ID. Validate it's an 8-digit number. When you have a valid ID, finish on collected." Leave routing decisions to the exits.
  • Don't restate the whole journey in every node. The flow's structure carries the sequence; each node only needs to know its own step. Repeating the end-to-end process in node after node makes them drift and contradict each other.
  • Reference capabilities by @-mention. If the node uses a tool or rich-media item (for example a "Quick Replies" chip), @-mention it inside the instructions so the reference stays linked even if the target is renamed.
  • Use the node's capabilities for what they're for. Put data the step needs to remember into Variables (the flow's local memory), put actions into Tools, and keep the First response toggle off unless the node genuinely needs a canned opener - by default the node acts per its instructions without a scripted opening line.

Note: Scoped instructions and the "one node, one job" rule reinforce each other. If a node's instructions are getting long and start branching ("if X do this, else do that"), that's usually a sign the node should be two nodes with an exit between them.

Use guided agents as tools from conversational agents​

Guided agents are automatically available as tools to your conversational agents - there's no toggle to enable. This is the recommended way to combine the two styles: let a conversational agent handle the open-ended conversation, and call a guided agent when the user reaches a step that must run deterministically.

A typical pattern:

  • A conversational support agent diagnoses a problem in free-form conversation.
  • When the resolution is "process a return", it invokes the order-return guided agent, which runs the fixed collect → check → book sequence.
  • When the guided agent finishes, control returns to the conversational agent to wrap up.

This keeps each style doing what it's best at: conversation where the path varies, guided where the steps can't. See Conversational agents and the Configuration guide for how the conversational side routes work, and routing logic for making the handoff deterministic when you need it.

Test before you publish​

A guided agent has no Live/Draft status - when you Publish, it's live. So validate it first, the same way you would any agent.

  • Run it on the canvas. Use the Execute tab to walk the flow turn by turn, and the Logs tab to see which node fired, which exit it took, and what each variable held. This is the fastest way to catch a mis-wired branch or an exit description that's firing on the wrong condition.
  • Test the unhappy paths, not just the happy one. Feed it bad input, refusals, and out-of-policy cases. Confirm max_retry and on_error lead somewhere graceful. Most guided-agent bugs live in the branches you didn't think to exercise.
  • Add test cases in the Trust Centre. For repeatable, multi-turn coverage - and to keep the flow honest as you change it - build test cases in the Testing Lab. Run them before every publish.

Tip - debug from the Logs tab. When a run does something unexpected, the Logs tab tells you the exact node and exit, so you can fix the right node's instructions or exit description instead of guessing. Treat a surprising exit choice as a prompt to sharpen that exit's description.

A few things to keep in mind​

These are builder-level realities to design around, not bugs:

  • Each node mints its own agent. A Conversational Agent node's configuration is local to that node - you don't share one agent across multiple nodes. If two steps need the same behaviour, configure both nodes (or factor the shared logic into a workflow you call from each via an Execute Workflow node).
  • Branch on outcomes, not on raw values inside one node. Decisions belong in exits. If you find a node trying to decide between many downstream paths, give it more exits or split it.
  • Name the flow uniquely. Two guided agents can't share a name.
Last updated on