Agent Node

An agent node is a single step of the conversation. It has a prompt describing what to achieve at this point, and one or more outgoing edges describing the reasons to move somewhere else. Most agents are a chain of them.

Why several nodes instead of one long prompt

You could write the whole call as one prompt. Every voice platform lets you, and it is the wrong shape for anything past a demo.

A prompt you can change safely

Fixing how the agent handles a price objection means editing the node that handles price objections, not re-reading a page of instructions and hoping the edit did not disturb something else.

A call you can read afterwards

The run record shows which node the conversation was on at each turn. “It went wrong” becomes “it went wrong on Qualify Budget”, which is a debuggable statement.

Tools that are scoped

Tools attach per node. A refund tool is reachable while discussing a refund and nowhere else — which is a control, not a convenience.

A shorter prompt at every turn

The model is only ever given the instructions for where it actually is. Shorter prompts are faster, cheaper, and followed more reliably.

The rule of thumb: a node is one thing you would tick off a checklist. “Find out what they want”, “check availability”, “confirm the booking” are three nodes. “Handle the call” is not a node.

Fields

namestringdefault: Agent

Short label, e.g. Qualify Budget. It appears on the canvas, in the run record, and in the transition tools the model sees — so a descriptive name genuinely helps the model reason about where it is.

promptstringrequired

What the agent should do at this step. Supports {{template_variables}} from extraction, the initial context, and pre-call fetch.

allow_interruptbooleandefault: true

Whether the caller can talk over the agent. On by default, because being unable to interrupt a voice agent is the single most common complaint about them. Turn it off only for a node that reads a disclosure.

add_global_promptbooleandefault: true

Prepend the Global node’s prompt at runtime. Leave it on unless this node deliberately breaks character.

extraction_enabledbooleandefault: false

Run an extraction pass over this node’s exchange and write the results into gathered_context.

extraction_promptstring

Overall guidance for the extraction pass.

extraction_variablesobject[]

Each entry is a name, a type, and a hint describing what to capture.

tool_uuidsstring[]

Tools callable from this node.

document_uuidsstring[]

Knowledge Base documents readable from this node.

Writing the prompt

A node prompt is an instruction for one step, not a description of the agent. The persona, the tone and the rules belong in the Global node — repeating them here makes them harder to change and gives the model more to hold at once.

A node prompt that works

Find out which dentist the caller wants and roughly when.

Ask for the dentist first. If they have no preference, say who is available
this week and let them choose. Then ask for a day and a rough time of day —
morning or afternoon is enough at this stage, do not push for an exact time.

Do not confirm anything yet. Confirmation happens at the next step.

Three things that make it work: it says what to achieve, it says what not to do, and it says where the conversation is going next so the model does not try to finish the whole call here.

Caution

Do not put the transition condition in the prompt. “When they’ve given you a time, move to confirmation” belongs on the edge, not in the node. Written in the prompt, the model may narrate the transition or attempt it at the wrong moment; written on the edge, it is a decision the runtime makes.

Edges out

Every outgoing edge carries a plain-English condition. The model evaluates them against the conversation so far and picks one.

"the caller has given a dentist and a preferred day"     → Confirm booking
"the caller says none of the times work"                 → Offer callback
"the caller wants to speak to a person"                  → Transfer

Write them as observable facts about the conversation, not as instructions. “the caller has confirmed” is checkable. “proceed to booking” is not — it tells the model what to do rather than when.

Note

When the decision is about a value rather than a judgement — an amount, a count, a language already chosen — use a Branch node instead. order_value > 50000 is not something a model should be asked to re-derive from the transcript.

Extraction

Switching on Enable Variable Extraction runs a second model pass over this node’s exchange and writes named values into gathered_context, where a Webhook, a Branch or a later prompt can read them.

Declare one variable per thing you want, with a hint:

Name	Type	Hint
preferred_dentist	string	Which dentist the caller asked for, if any
preferred_day	string	The day they suggested, as they said it
is_new_patient	boolean	Whether this is their first visit

Extraction is per node and off by default, which is deliberate: it is an extra model call, and running one on every node of a long call is a cost you did not intend to take.

Rules

• At least one incoming edge — an agent node the conversation cannot reach is a validation error, not a draft.
• Any number of outgoing edges. A node with none is a dead end; use an End Call node if that is what you meant.

See also

Global node

Where the persona and the rules go, once.

Branch node

Routing on a value instead of asking the model.

Context and variables

How initial and gathered context flow through a call.

Tools

Letting a node act, not just talk.