Prompt-based or node-based voice agent: how to choose

Decide who owns the next step

In a prompt-based agent, one set of instructions tells the model what to ask and do next. It can still have tools and server-side validation. It gets fragile when business rules exist only as prose that the model has to remember on every turn.

In a node-based agent, the call moves through a graph. Each node is one step with its own instructions, and each transition out of it has a condition. The model speaks naturally and interprets answers inside the current step. These are standard state-machine ideas: an event changes state, and a guard decides whether a transition is allowed. Stately’s transition and guard docs explain them well.

A practical decision table

Situation	Start with	Why
Open questions about a product	One prompt, plus validated tools	The caller may take a useful route you didn’t plan
A short intake of a few facts	One prompt, with variables in and analysis out	You may not need a graph yet
Booking or changing something in another system	A workflow around the action	Availability, confirmation and retries need an owner
Several phases, each with its own rules	Nodes	Each step gets clear entry and exit conditions
Instructions that won’t fit in one prompt	Nodes	Only the current node’s instructions are in play
You need to know which step each call reached	Nodes	The outcome records the nodes visited

We have no evidence for a universal prompt length or node count at which to switch. Add structure when you can name a failure it would prevent, and test that it does.

How do Mirai’s node-based agents run?

A flow is one field on the agent, flow, available on every tier for phone calls, browser calls and campaigns. Node-based calls are billed like any other call: from ₹1 a minute at volume (T1, with a ₹1,00,000 monthly commitment) to ₹5 a minute pay as you go (T5). From the node-based agents docs:

1. The call opens on the start node, whose greeting is spoken as written, with variables filled in.
2. The model follows the current node’s prompt, after the global node’s shared prompt if the node includes it.
3. Each transition is offered to the model as a function: its label is the name and its condition is the description. When the model decides the condition is met, it calls the function and the call moves on.
4. The history carries across nodes. Moving replaces the instructions, and the model still knows everything said so far.
5. An end node gets one reply, then the call hangs up.
6. A node with extraction turned on extracts its variables in the background as the call leaves it, so it never delays a reply.

A graph has 2 to 20 nodes and up to 40 transitions, and each node prompt can be up to 12,000 characters. You can draft a flow from a one-line brief or from recordings of real calls in Agent Studio, then edit it. Every save creates an immutable agent revision, and a running campaign keeps the revision it was created with.

After a call, data.call.flow in the call.processed webhook reports the final_node, the nodes_visited in order, the extracted variables and how the flow ended.

Walk through an appointment example

Picture a fictional appointment assistant:

Collect preference → Look up availability → Offer a slot
       ↑                                      ↓
       └──────── Caller correction ──── Confirm selection
                                              ↓
                                      Create appointment
                                              ↓
                                        Report result

Make cancel and hand-off reachable from every step. In Mirai today, hand-off means the agent tells the caller the team will call back, because warm transfer to a person is not available yet. A correction after the availability lookup should invalidate the old result. A correction after the appointment exists needs a change or cancellation path, so it never creates a second appointment by accident.

For each node, write down what is already known, what is still missing, which tools it offers (up to 10 on-call tools per node in Mirai) and which conditions leave it. Put the persona, language and reply-length rules in the global node once. The model doesn’t need the whole rescheduling manual while it asks which day suits the caller.

Enforce prerequisites outside the prompt

Before create_appointment runs, your server should check that the slot came from a current availability result, that the caller confirmed that slot, and that the confirmation belongs to the current state. A model-supplied confirmed: true is not enough. Your application needs a confirmation it can audit, tied to the slot offered and the caller’s turn.

Store an idempotency key for the operation. If the booking system times out after accepting a request, check its status before you retry. Repeating “never book twice” in the prompt cannot dedupe a network retry.

These rules belong in a prompt-based agent’s tools too. Nodes make the rules and recovery paths easier to find; drawing boxes does not enforce them.

Write transitions the model can choose between

The docs’ design tips are worth following: one job per node, name the transition function in the node prompt (“If they confirm, call confirmed_identity”), tell the model to move without speaking first so the next node decides what is said, and make the conditions of sibling transitions mutually exclusive. When two could both be true, the model has to guess.

Don’t turn a node into a rigid script. A caller may answer two questions at once, ask why you need something, or interrupt to correct a date. Extract everything they said, validate it, and ask only for what is still missing.

Test conversation repair as well as the happy path

The downloadable workshop and evaluation cases include 12 authored scenarios: ambiguous consent, changing an earlier answer, stale tool results, duplicate events, interruption and hand-off. They are a starter test set, not measured results.

Run the same cases against both designs. Record task completion, wrong actions, repeated questions, turns needed to recover from a correction, and latency. Look at the failures before you add more nodes. If the main problem is contradictory instructions, fix the prompt first with the prompt repair guide. To place test calls from code, see the Python phone-call guide.