Agent Logic: rules, conditions, and guardrails¶

Last reviewed: 2026-10-13

Choose a shared Safety profile to add Llama Guard or NeMo to a response guard. Tool settings also offer input and result checks. See Llama Guard and NeMo safety profiles for setup, testing and voice limitations.

When you turn off default visual guidance for a subagent, your procedure controls what happens after a button click or upload. The action and its values still reach the agent; the platform will not force it to show another screen after each action. Custom visual guidance follows the same rule. Keep any required next screen in your procedure.

For caller-supplied facts such as a surname or birthdate, enable extraction on the variable and bind the tool input to that variable. Declaring the variable alone does not enable extraction. The runtime briefly waits for the latest extracted answer before using the binding, including a caller's correction; it refuses the action if that answer is still unresolved.

Agent Logic lets you combine plain-language instructions with behavior that always happens — no coding required. Use it when a business rule is too important to leave to the model's judgment: "never quote a rate", "refunds require verified identity", "greet gold members differently".

Tools can also have execution checks configured in the agent configuration: payment records can require a matching successful payment, and repeated write requests can reuse their original result within the current session. These checks apply during both real conversations and tests using mock responses. Repairing missing tool inputs rechecks the current conditions before running the action. Protection across reconnects also requires support in the destination service. These are configuration options; no additional visual control is added.

For handoff fields extracted by a prompt, a developer can configure tool_logic.end_session.merge_bind.params to combine the model's object with verified application data. Verified fields take precedence. Ordinary bind replaces the entire parameter and hides it from the model, so use merge_bind when the prompt must add fields. Map each new field explicitly in the conversation-end workflow before expecting it to appear in Salesforce. Use builtin_tool_configs.end_session.params_fields to describe each extracted string field in the tool contract, and tell the prompt when to populate it.

Variables¶

Everything you insert renders as a colored chip — sky variables, blue tools, violet subagents, teal components, green RUN / blue SET actions, and amber IF/ELSE — so a prompt reads as prose plus logic, with no template syntax on screen (the raw text is still what's stored; select across a chip to hand-edit it).

Variables create themselves: reference {{name}} in any prompt (or inside an If/Else condition) and the name is in scope — it starts empty until a rule or a tool capture sets it. The Variables panel in the inspector’s Behavior tab lists everything currently in scope: names referenced in prompts, platform facts like the caller's phone number, and outputs from the agent's lifecycle workflows. Every condition builder offers the same list.

Some variables come for free: enable a capability and the values it manages appear in scope automatically — Customer Authentication maintains customer_auth_status (branch on == "verified" with no setup), and having subagents gives you current_topic. The Variables panel labels these platform (auto).

Multimodal components can fill variables too. Insert a component into the prompt, then click its component pill and use Map answers to variables to copy a submitted field or tapped choice into a variable (for example, $.data.email → customer_email). The mapping stays with that component, and rules, IF/ELSE sections, and tool gates react as soon as the customer answers on screen.

Need a variable that nothing references yet — say isAuthenticated for an IF condition? Create it on the spot: every condition builder's variable picker ends with ＋ New variable…, and the Behavior → Variables panel has an Add variable button. Both open the same small form: a name (typed naturally — isAuthenticated becomes is_authenticated), a type, a description the AI reads, and either a starting default or a link to a live platform fact — for example link it to customer_auth_status and it always shows the caller's real verification state. Linked variables are read-only.

Conditional prompt sections (If / Else)¶

In the prompt editor, type {{ (or @) and pick If / Else section — the condition builder opens right away: pick a variable, an operator, and a value, chaining rows with AND/OR (power users can switch to the Expression tab, e.g. customer_tier == "gold" and not escalated). The value can be typed text, a number, another variable (including platform ones like the current date/time), True/False, Blank, or a raw expression — and the is blank / is not blank operators need no value at all (they're true for a variable nothing has set yet or one that was set to empty). When you save, the cursor lands inside the IF branch — type what the agent should do there; each empty branch shows a hint until you do. Cancel on a freshly inserted section removes it; cancel while editing an existing one leaves it unchanged.

The section renders as amber IF / ELSE / END IF pills; the text inside each branch only reaches the AI when the condition holds, and it updates live as variables change during the call. Click any IF pill to edit its condition later (an unset one reads set condition…), and click ＋ ELSE IF to add another branch with its own condition.

Actions and assignments inside the prompt (Run / Set)¶

The prompt can do things while it is being prepared, not just say things. Type {{ and pick:

• Run an action — runs a tool before the agent speaks and saves parts of its result into variables. Pick the tool, fill its inputs (reference variables by name, or type literal text), and map result fields to variables (e.g. $.data.hotel_code → hotel_code).
• Set a variable — assigns a value on the spot (e.g. greeted = True, or num_turns + 1 — simple +/- arithmetic works).

You can also insert a value inline by typing {{= variable_or_expression}}.

Statements run top to bottom, so a line can use what the lines above set: an If/Else section below a Run sees the variables it just saved. The statements themselves are never shown to the AI — only their effects are. They render as green RUN and blue SET pills; click a pill to edit it in the same dialog, and click an inline = pill to edit its text directly.

Every chip is clickable. Click a blue tool chip to open its settings — when it's available, inputs you want pinned or driven by a variable (so the model never fills them), result fields to save into variables, and an optional While the tool is running sentence — or to convert the mention into a Run action. These settings apply to every use of the tool on this stage; when you need different inputs at a specific point in the prompt, that's what a Run action is. The platform speaks that status sentence only after the tool is allowed and just before it starts; the agent then responds again with the actual result. Click a teal component chip to configure it: map its on-screen answers into variables (components that declare their answers show them as one-click chips — e.g. a confirm button's appointment_id), and pin props — force a prop to a fixed value or a live variable instead of letting the model choose it (e.g. pin customerName to the customer_name variable so every render shows the verified name).

Voice note: with a chat agent, a separate TTS voice, or OpenAI Realtime, statements re-run before every agent turn, so the prompt always reflects the latest values. Nova Sonic evaluates its prompt at each caller and agent turn boundary and when variables change. Other native S2S voices may only evaluate it at session start — the publish check will remind you.

The same behavior applies to If/Else prompt sections and variables inserted in the prompt. If the rendered instructions change, Nova prepares a replacement session in the background and switches after the current response and tool work finish. The call, conversation history, variables, and completed actions carry over. Unchanged instructions do not restart the session.

You do not need to enable a setting. There may be a short handoff delay; an answer already in progress can finish using its original instructions. If the replacement cannot be prepared, the current session continues and the refresh is retried.

Saving facts the customer tells you¶

Declare a variable with a good description (see Variables above) and the agent automatically gets a set_variables action: when the customer gives a matching piece of information ("my account number is…"), the model saves it. Rules and tool gates can use the value immediately; If/Else prompt sections reach the model according to the provider's refresh timing above. Only variables you declared (and that aren't linked) can be written this way.

Subagents¶

A subagent is a named specialist the conversation can route to — same voice, memory, and model, but its own complete instructions: while a subagent is active, its prompt replaces the main one (the conversation, everything the customer said, and all variables carry over). The tab strip above the prompt (Main | Returns | Billing | +) is where they live: click + to add one, click a tab to edit it — its name, when to use (the model reads this when deciding to route), its conditions, and its full prompt, in the same editor as the main prompt (If/Else, actions, variables all work inside it). You can branch on the active one anywhere (current_topic == "returns").

Each subagent moves control one of two ways:

• Refer (the default) — control returns when the task completes. The agent hands back automatically (or when the optional Return when condition holds). Use it for tasks inside a bigger conversation: a return, an address change, a verification step.
• Transfer — a full handover. The conversation stays with the subagent until something routes it elsewhere; it never bounces back on its own. Use it when the customer's need has genuinely changed lanes.

Enter only when blocks routing until a condition holds (e.g. billing requires auth_status == "verified"). To escalate out entirely, use the built-in End Session or External Consult capabilities.

You can also work without leaving the text: type @ and pick a subagent to reference it, type @a-new-name and choose ＋ New subagent to create one on the spot, or click any subagent pill — each opens that subagent's tab. Routing happens by a rule's Route to a subagent action (deterministic) or by the model choosing for itself.

Agents on the canvas show a compact summary badge (3 subagents · 5 tools) instead of the old inline subagent boxes — the structure is edited here, in the prompt.

Tools ("Actions")¶

The Actions strip at the bottom of the prompt editor lists the tools this stage can call. Tools that come from a capability (Payments, Customer Authentication, External Consult) don't appear here — they're managed on their capability card. ＋ Add searches the tool library or creates a new inline Python / API / Knowledge tool on the spot; the funnel icon on a chip sets Available when — a condition that must hold before the model is allowed to use that tool (e.g. refunds require auth_status == "verified"); ✕ removes it. In the Run an action dialog, a tool's declared inputs pre-fill the inputs table (leave a row blank to skip it) and its known outputs appear as one-click capture suggestions. Inserting a tool from the @ dropdown adds it automatically. Deep tool settings (operation filters, parameter overrides) live under the Advanced section.

Visual components need no extra tools: mention a component in the prompt and the agent can show it, and the customer's on-screen answers flow back through Map answers to variables (click the component's pill).

The insert menu¶

Type @ or {{ on an empty spot and you get categories — Variable, Tool, Run an action, Set a variable, If/Else, Subagent, Component. Pick one to drill into that list (with ← Back), all inside the same dropdown. Start typing instead and it filters across everything at once. Cancelling a dialog opened from a fresh insert removes the placeholder.

Rules¶

In a stage's Behavior tab, open the Advanced section below Subagents — it nests Rules and Response guards, and shows counts when the stage already has some. Add rules that fire at specific moments: when the conversation starts, when the customer sends a message, after a tool returns, when a variable changes, or after each agent turn. Each rule has an optional condition and one or more actions — set a variable, run a tool, add an instruction for the AI, end the conversation, or escalate to a human.

Response guards¶

Guards check what the agent is about to say before the customer hears it. Three check styles: text patterns (regular expressions), an expression (the outgoing text is agent_response), or an AI judge you describe in plain language. On a violation the agent can say a replacement, redact the matched text, or silently regenerate the answer under a corrective instruction.

Keep silent¶

Choose Keep silent when a matching response should produce no speech or replacement message. This also drops the rest of that response. It does not end the call, cancel a submitted action, or prevent an answer to the next caller turn. For example, an authored waiting response can remain silent while the caller finds a patient's name.

Voice note: with a separate TTS voice (including an S2S model set to text output), guards run fully before anything is spoken. With a native S2S voice (e.g. Nova Sonic) the audio is generated directly, so guards run against the live transcript — either audit (no added delay; a violating sentence is cut off mid-playback and corrected) or hold (the first sentence of each answer is held until it passes). For strict compliance rules, prefer the separate-TTS setup — the publish check will suggest it. Keep silent cannot retract audio that already played in native S2S audit mode.

Tool rules¶

A tool can carry its own logic (currently authored via Generate with AI or the management API): make it available only while a condition holds ("refunds require auth_status == "verified""), pin parameters the AI must never choose, and capture fields from its result straight into variables.

Require a closing summary¶

In the stage's code configuration, set builtin_tool_configs.end_session.require_summary to true when every agent-selected ending needs a written recap. An empty summary keeps the session open briefly while the agent corrects its end-tool arguments. Describe the expected recap in your closing prompt; the setting checks that a nonempty summary exists, while tests assess its accuracy. A caller disconnect or runtime timeout still ends the session normally.

If a subagent returns automatically on a completion rule, let Main handle the next response. Avoid also telling the subagent to request a second return after that same completion.