Agent node - settings
The rest of an Agent node's drawer: how it opens, what runs around each turn, which model it uses, how it takes its turns, and what it does differently per channel.
Most nodes need none of these. Reach for them when a step has a specific need.
First response
The agent's first response when control reaches it.
Off by default - the panel reads "Turn on to set the agent's opening message." Switch it on and this node opens with a message you write, the first time it speaks.
Scripted, not generated - and that's the point
No model is involved. The message is sent exactly as written, so it is instant, costs nothing, and is identical on every run.
That makes it the right choice whenever the opening line must be guaranteed rather than merely likely:
- A compliance line or disclosure that has to be word-for-word.
- A fixed menu the customer can act on immediately.
- A holding line before a slow step, so the wait doesn't start in silence.
Anything the agent should adapt to the customer belongs in the Instructions instead. This field trades flexibility for certainty - use it where certainty is what you want.
What it can send
| Kind | Use for |
|---|---|
| Text | A plain opening line. |
Text with {{variables}} | A personalised opener - the tokens are replaced with live values before sending. |
| Quick replies | A message plus tappable options, where you write both the message and the options. |
| Widget or workflow | A saved rich response as the opener. |
This is the one place variables are genuinely substituted for you. Elsewhere - in the Instructions - a
{{name}}token is passed through and the agent resolves it. Here the value is filled in before the message is sent, which is why the result is exact. A token you haven't got a value for is left as-is, so it shows up verbatim in the chat.
When it fires
The first time this node speaks - once. Coming back to the node later in the same conversation doesn't replay it.
It also interacts with one of the Behaviour toggles, which is worth knowing:
| Let the user speak first | What happens |
|---|---|
| Off (default) | The node opens with your message the moment the flow arrives. |
| On | The node stays quiet, waits for the customer, and your message goes out when it first speaks. |
After the opening message is sent, the node hands back and waits for a reply - it doesn't send the message and then immediately start reasoning.
Good use
| Pattern | Why it works |
|---|---|
| One opener at the start of a flow - "Let's get your return started." | Marks the transition once, where it reads naturally. |
| A word-for-word disclosure | Guaranteed exact. An instruction to say something is not a guarantee. |
| A fixed menu with quick replies | Same options in the same order every time, with no model call to pay for. |
Hi {{customer_name}}, I can help with order {{order_id}}. | Personal and exact, using values the flow already holds. |
| A holding line before a slow lookup | Covers latency, especially on voice. |
Problems
| Pattern | What goes wrong |
|---|---|
| An opener on every node | The conversation feels like it restarts at each step. This is the most common overuse. |
| A greeting mid-flow | The customer has been talking to you for four turns. "Hi there!" reads as not listening. |
| Referencing a variable that may be empty | The raw {{token}} is shown to the customer as-is. |
| Using it for something the agent should adapt | It can't - it's fixed text. That belongs in the Instructions. |
| Long quick-reply labels | Trimmed at 40 characters. |
| Duplicating it in the Instructions too | The customer gets told the same thing twice in a row. |
How to think about it
Use it where you need a guarantee. Instructions describe what the agent should say; First response is what gets said. If it has to be exact, this is the only field that promises that.
Once per flow, not once per node. Announce the beginning of a procedure. Don't announce each step within it.
Check it reads well as the second thing the customer hears, not the first - by the time a mid-flow node speaks, there's already a conversation in progress.
Lifecycle Hooks
When the turn ends, run a workflow - usually to fetch data and write it to a variable the agent reads on its next turn.
A way to run a workflow around a turn rather than during it. The available event today is When the turn ends.
The mental model is worth separating from Tools:
- A tool runs during the turn, because the agent decided to call it, and the agent sees the result.
- A hook runs after the turn, whether or not the agent wanted it, and the agent never sees it happen.
So hooks are for the "and also, every time, do X" work: refresh a value the next turn will need, push an update to a CRM, log a transcript.
The conversation waits for each hook to finish before continuing, so keep the workflows fast.
Run conditions
By default a hook runs after every turn - the chip reads Always. Add conditions to narrow it, and the chip switches to a count.
Each condition is a variable, an operator (is, is not, is empty, is filled in), and where relevant a value. Variables can come from memory, journey, profile, user or system scope. With more than one condition you choose whether all must be true (AND) or any (OR).
Comparisons are type-aware: a condition on a boolean matches the actual boolean, not the string "true".
Example - push to the CRM only once there's something worth pushing:
| Event | When the turn ends |
| Workflow | sync-lead-to-crm |
| Run when | all of: lead_email is filled in, crm_synced is not true |
After every turn - not once at the end
The most important thing to get right about this setting. "When the turn ends" means every turn of this node, not the moment the node finishes.
A step that has a five-turn conversation with the customer fires its hook five times. That is exactly why run conditions exist, and why a hook that writes to an external system almost always needs one.
If you want something to happen once, when the step is over, condition the hook so it can only be true once - or do the work in the next node instead.
The canonical use
The panel's own description says it: "usually to fetch data and write it to a variable the agent reads on its next turn." That loop is the pattern worth remembering:
- The customer says something.
- The turn ends; the hook runs a workflow.
- The workflow writes a variable.
- On the next turn the agent's context is rebuilt, so it now sees the new value.
That's how a node gets fresher information without the agent having to decide to go and fetch it. Compare with a tool, where the agent chooses to call and waits for the answer inside the turn.
Good use
| Pattern | Why it works |
|---|---|
| Refresh a value the next turn will need | The agent gets it for free, with no tool call and no decision to make. |
| Push to a CRM once a threshold is met, gated by conditions | Fire-and-forget side effect that doesn't belong in the conversation. |
| Log or audit a turn | Silent by nature, and wanted on every turn - the one case where "every turn" is exactly right. |
| Anything the customer should never see happening | Hooks produce no output at all. |
Problems
| Pattern | What goes wrong |
|---|---|
| Assuming it runs once per node | It runs per turn. A five-turn step sends five CRM updates. |
| A slow workflow | The conversation waits for it. The customer experiences it as the agent thinking. |
| No conditions on a side effect | "Always" is the default, and it means always. |
| Expecting it to message the customer | It can't. Nothing it does reaches the chat. |
| Relying on it having succeeded | A failing hook is logged and skipped so it can't break the turn - which also means the flow carries on as if it ran. |
| Using it to set a value the current turn needs | Too late. It runs after the agent has already replied. Use a tool. |
How to think about it
Tools are for the agent; hooks are for you. If the agent needs the answer to reply well, it's a tool. If the system needs something to happen regardless, it's a hook.
Assume it runs more often than you meant. Write the conditions first, then the workflow.
Keep it fast, because the customer is waiting. The conversation blocks on it.
Never make it load-bearing. A hook that fails is skipped silently. Anything that must happen should be visible in the flow, not tucked into a hook.
Model configuration
Which model this node runs on. Override is off by default, meaning it inherits your assistant's default model - shown in the row as e.g. Yellow AI · gpt-4_1-2025-04-14 · Default.
Turn Override on and pick an account and a model to pin this node to something else. The choice applies to this node only - every other step keeps running on the default.
When it's worth overriding
- Down, for narrow work. A node that classifies a message into three branches doesn't need your strongest model. On a high-traffic router that's a real saving with no quality cost.
- Up, for the hard step. One node that has to reason over a policy document or reconcile conflicting details can justify a stronger model while the rest of the flow stays cheap.
The failure mode to watch for
A weaker model on a node with subtly-worded branch descriptions starts choosing the wrong branch. The symptom is bad routing, which doesn't look like a model problem - it looks like your descriptions are wrong, and you can lose an afternoon rewriting them.
So change the model on its own, test the node's routing specifically, and treat any new flakiness as caused by the change until proven otherwise. Nodes with two obvious branches tolerate a smaller model well; nodes with four nuanced ones often don't.
Problems
| Pattern | What goes wrong |
|---|---|
| Choosing an account but no model (or vice versa) | The override is ignored and the node quietly stays on the default. |
| Downgrading a node with nuanced branches | Routing accuracy drops, and it presents as a prompt problem. |
| Overriding every node "to be consistent" | You've replaced one default with many settings to maintain. Override the exceptions. |
| Expecting the change in Version history | Model configuration isn't versioned, so there's no record of when it changed. |
How to think about it
Default until you have a reason. Inheriting means one place to change your mind later.
Override down on volume, up on difficulty. A high-traffic classifier is where a cheaper model pays; a single hard reasoning step is where a stronger one earns its cost.
Change one thing and test the routing. This setting's failure mode disguises itself as a prompt problem.
Behaviour
Four toggles controlling how this step takes its turns. Each applies to this node alone.
Let the user speak first
Wait for the user before the agent says anything. Off (default): the agent opens the turn as soon as the flow reaches this step.
Turn it on when the previous step already asked the question and this node exists to interpret the answer. Leaving it off there produces the classic double-question: one node asks, the next node arrives and asks again in its own words. The customer experiences it as not being listened to, and it's one of the most common flow bugs.
Leave it off (the default) when this node is the one starting the exchange.
It applies on arrival only. Once the node is in a conversation, it takes its turns normally - this doesn't make the agent quiet for the whole step.
Conversation history
On (default): the agent sees the full transcript. Off: it answers only the current message.
Turn it off for a clean, self-contained step - a classifier, a validator, a node that should judge only what was just said. It makes behaviour more repeatable and the turn cheaper.
Keep it on whenever the step depends on earlier turns: confirming details given several steps back, or interpreting a follow-up like "the second one".
Apply global conversation rules
On (default): this agent follows the shared behaviour rules from your primary agent. Off: it responds without them.
Your primary agent can define global conversation rules - shared tone and do's-and-don'ts every agent follows. Turn this off for a tightly scripted step whose exact wording those general rules would interfere with.
Turning it off here doesn't affect any other step - the rest of the flow keeps following the rules.
Exit without a reply
Suppresses any reply the agent generates on the turn it exits. Use it as a safety net: your prompt should still tell the agent not to write an exit message.
Turn it on when the next node should be the one that speaks. It stops the "Great, I'll get that sorted for you!" that an agent tends to tack on as it exits, which the next node then talks over.
As the hint says, treat it as a backstop rather than the fix. Keep "finish on the matching exit and send no further message" in the Instructions too - it's better for the agent not to write the message than to write one that gets thrown away.
Leave it off when this node is the last word on something and the next step is silent - otherwise you suppress a reply the customer needed.
Choosing the toggles
A quick way to set all four for a typical step:
| Step | Speak first | History | Global rules | Exit silently |
|---|---|---|---|---|
| Opens a phase and asks a question | Off | On | On | On |
| Interprets an answer the previous node asked for | On | On | On | On |
| Classifier judging only the latest message | Off | Off | On | On |
| Tightly scripted or regulated wording | Off | On | Off | On |
| The last step, delivering the final message | Off | On | On | Off |
Channel overrides
Tune how this agent behaves on a specific channel. Anything you don't set here uses your global settings.
Per-step voice behaviour, layered over your global voice configuration while this node is active. Every field inherits until you set it, and the drawer reads "This agent uses the global settings on every channel" until you do.
| Setting | What it's for |
|---|---|
| Let caller interrupt | Whether the caller can cut in while the agent is speaking (barge-in). |
| Boost phrases | Words or names to bias speech recognition toward while this node is active. |
| Initial silence (ms) | How long to wait for the caller to start speaking before prompting again. |
| End-of-turn silence (ms) | Silence after the caller stops before the agent responds. |
| Capture keypad (DTMF) | Accept phone-keypad digits here, with digit length, finish character, and whether a keypress interrupts the agent. |
These exist because the right values are step-specific, not call-wide. A node collecting an account number wants a longer end-of-turn silence (callers pause while reading digits off a card), keypad capture on, and barge-in off so the agent isn't cut short mid-prompt. The node that just confirms "yes or no" wants none of that.
Boost phrases are the quiet win: add your product names, plan tiers or branch names on the node that asks about them, and recognition on exactly those words improves.
Version history
Version history in the drawer header opens a panel of earlier saved versions of the agent, which you can review, compare and restore.
It covers the authored content - Goal, Instructions, capabilities, exits - so it's the right place to look when a prompt change made a step behave differently and you want to see what actually changed. Model configuration and the Behaviour toggles aren't versioned, so a routing change you can't find in the history may be one of those.
Limits at a glance
| Limit | |
|---|---|
| Goal | 500 characters |
| Outcome branches | 5 per node |
| Response exit | 1 per node |
| Writable variables | 5 per node |
| Writable variable types | text, number, yes/no, list - objects can be read only |
| Writable variable scopes | global and journey - user properties are read-only |
| Writable variables need | a description, before the toggle is available |
| Quick replies (Rich media) | attachable once per node |
| Quick-reply label | 40 characters |
| Reserved branch names | on_error, error, fallback, success, default, response, and avoid in_progress |
| Reserved tool-exit names | end, complete_goal, remember, handoff, end_call |
| Rich media on voice | not rendered at all |
Common mistakes
Leaving the Instructions empty. The node doesn't run at all - no error, no fallback. If a step appears to do nothing whatsoever, check this first.
Routing to another agent from the Instructions. @-mentioning an agent and telling this one to "route there" does nothing. Add a branch and wire it on the canvas.
Expecting on_error to catch business failures. It fires on a crashed run or a runaway loop - not on "not eligible", "the user declined", or a tool erroring. Those are branches you design.
A branch with nothing that reaches it. max_retry is the usual victim: the branch exists but no instruction tells the agent to take it, so it can never fire. Retry isn't built in - you write both halves.
Leaving a variable read-only when the step is meant to collect it. Nothing is written, nothing warns you, and the symptom appears in a later node.
Using the write toggle to capture a tool's result. That's Store output in, configured on the tool.
One branch per possible value. Exits are outcomes, not data. If the branches would all go to the same node, it's a variable.
Overlapping branch descriptions. The most common cause of a node that routes unpredictably. Two descriptions that can both be true of the same message get picked between inconsistently.
Attaching rich media and never mentioning it - or attaching quick replies without listing the options anywhere.
Designing a voice step around quick replies. They're not rendered on voice, and nothing warns you.
Assuming a turn-end hook runs once. It runs after every turn of the node.
Leaving on_error unwired. One edge, and the difference between a graceful apology and a stalled conversation.
One node doing three jobs. Check its exits: if the parts fail differently and need different recovery, split it.
Next: Recipes - two worked nodes that put these settings together.