An AloAi Voice Agent follows its instructions on every call. The instructions shape the agent’s tone, how it interprets what callers say, and how it responds, while a few separate settings control how the call opens and closes.
This article covers the instructions box on the Configure tab and the tools around it: Improve, Agent Handbook, Insert variable, and Expand. It also covers who speaks first, the greeting and goodbye messages, and the Dynamic Variables panel.
To get there, open the Agents menu and click the agent’s name. The agent opens on the Configure tab, with the instructions box on the left.
Open the agent from the Agents list.
The instructions box on the Configure tab.
Writing the agent’s instructions
The instructions box is on the left side of the Configure tab, under the model, voice, transcriber, and language selectors. Use it for a universal prompt for your agent, such as its role, conversational style, and objective.
The instructions box and the toolbar above it.
If you created the agent with Guided Agent Setup, the box already contains instructions written from your setup answers. You can edit them like any other text. See Creating an AloAi Voice Agent.
Clear instructions keep the agent consistent and let it follow your business logic in both simple and complex conversations. When you write or edit instructions, include:
The tone the agent should use.
Keywords or phrases to prioritize or avoid.
Routing or escalation logic, such as when to transfer a call.
Guidance for questions the agent cannot answer.
The toolbar at the top of the box formats your text: bold, underline, italic, strikethrough, heading, subscript, superscript, quote, bulleted and numbered lists, inline code, code block, and link, plus undo and redo.
Click Save at the top of the agent screen to keep your changes. A notification confirms the result.
Editing in the expanded editor
For long instructions, click Expand above the box to open a full-screen editor. The editor has two tabs:
The Expand button above the instructions box.
Plain text shows the instructions exactly as they are stored.
Visual shows the instructions as formatted text, so headings, lists, and code blocks are easy to scan.
Variables such as {{FirstName}} display exactly as written in both tabs. Switching tabs keeps your unsaved edits. Save your changes before you close the editor, because closing without saving discards them.
The expanded editor also has Insert variable and Save.
The expanded editor with the Plain text and Visual tabs.
Improving your instructions
Click Improve above the instructions box to get suggested edits. Improve offers three reviews. It never changes your instructions on its own: each suggestion is shown as a before and after comparison, and you apply or dismiss it. Applying a suggestion updates the text in the box. Save the agent afterward.
To return to the three reviews at any time, select All improvements. Edits you already applied are kept.
The Improve instructions window.
Check for clarity
Check for clarity reviews the text currently in the box, including unsaved edits, and finds wording the agent may misread. It does not need a test call, so you can run it before your first call.
Each finding shows a category label, such as a conflicting rule or a missing fallback, a severity of HIGH, MEDIUM, or LOW, a short title, the BEFORE text from your instructions, and the proposed AFTER text. HIGH findings are listed first.
If there is nothing to raise, the review says so. The option is unavailable when the instructions are empty.
Check my last calls & improve
Check my last calls & improve reads the agent’s four most recent test calls and proposes fixes based on what happened on them. It reads test calls only, not calls with your real contacts. If there are fewer than four test calls, it reads the ones that exist and tells you how many.
Choose a focus. The review shows up to three findings. Each one describes what callers experienced and cites at least one transcript turn or function call from the test calls.
Review the fixes for that focus, and apply or dismiss each one. Select Other findings to go back to the list without losing the analysis.
If the agent has no test calls yet, this option is unavailable and shows "Run a test call first."
Restructure sections
Restructure sections reorganizes your instructions into six numbered sections, always in this order: Objective, Persona, Conversation Steps, Objections, Functions, and Considerations.
Each section is built only from text already in your instructions. The review does not write new instructions:
Text that fits none of the sections is listed separately as unassigned, with a note on where it might belong, such as the agent’s Knowledge Base. Nothing is dropped without being shown to you.
A section with no matching text is shown empty, with a note naming what is missing.
If your instructions already follow the six sections, the review says so instead of reorganizing them.
Variables and function references keep their exact formatting.
You can edit a proposed section before you apply it, apply one section at a time, or select Apply all sections to rebuild the instructions in one step. A preview shows what will change before any apply takes effect.
Each time you save the agent, a version is recorded, so you can read earlier instructions in the agent’s version history. See Testing and reviewing your agent.
Applying Agent Handbook behaviors
The Agent Handbook is a library of pre-built behaviors. When you turn on a behavior, its guidance is added to the agent’s instructions automatically on every call, so you do not need to write it yourself or edit the prompt to add or remove it.
To apply behaviors:
Click Agent Handbook above the instructions box.
Turn on the behaviors you want. Each one shows an example and a token estimate, so you can review its effect on the prompt before saving.
Save your changes.
Behaviors are grouped into three tabs.
The Agent Handbook with the Default Tone options.
Personality & Tone
The Personality & Tone tab has these behaviors:
Default Tone sets the agent's overall communication style. Turn it on and choose Professional, which keeps the agent clear and polite, or Professional + Conversational, which keeps a professional approach while making the conversation more casual and natural.
Natural Filler Words lets the agent use natural speech fillers, such as "you know," so responses sound less scripted. Example: "So yeah, let me just pull that up for you real quick."
High Empathy makes conversations calmer in tough moments. The agent acknowledges the caller's concern, makes them feel heard, reassures them briefly, then moves into solving. Example: "I'm so sorry this happened, as I understand how frustrating this can be. Let's get it sorted now."
Accuracy & Format
The Accuracy & Format tab has these behaviors:
Echo Verification has the agent repeat important details, such as names, phone numbers, email addresses, and addresses, and ask the caller to confirm. Example: "To confirm: your phone number is (415) 555-0199. Yes or no?"
NATO Phonetic Alphabet has the agent spell out emails, names, streets, account IDs, and similar details using phonetic examples, such as "A as in Alpha," then confirm the full spelling. Example: "Is that B as in Bravo? Great, B-7-K-2, correct?"
Speech Normalization has the agent read numbers, dates, and money in a natural spoken form. Example: "Your total is twenty-four dollars and twelve cents."
Smart Matching (ASR/LLM Bridge) helps the agent recognize that two answers mean the same thing even when the caller words or pronounces them slightly differently.
Trust & Safety
The Trust & Safety tab has these behaviors:
AI Disclosure When Asked has the agent say it is a virtual agent when a caller asks whether they are speaking with a person, and never pretend to be a person. Example: "Yes, I'm an AI assistant here to help."
Scope Boundaries keeps the agent within your prompt and available tools. For a request outside its scope, the agent says so and redirects safely instead of inventing details or committing to unsupported actions. Example: "I can't do that directly, but I can check the status or connect you to an agent."
Personality & Tone selections cannot weaken or override Trust & Safety behaviors. Place a test call to hear the result before you rely on a new combination of behaviors.
Who speaks first
Who speaks first is set by the agent’s call direction, so the editor does not show this control:
Inbound agents greet the caller when the call connects.
Outbound agents wait for the contact to speak before responding.
On outbound agents, AI starts speaking after silence appears below the instructions box. Turn it on to have the agent start speaking after the contact is silent for a set duration. It is off by default. On inbound agents, Pause Before Speaking on the Welcome message row sets how long the agent waits before it starts speaking. The default is 0.0 seconds.
If an outbound agent has AI starts speaking after silence turned off and no End call after silence set in Call Settings, the editor shows a warning: if no one speaks, the agent waits in silence until the call times out, which can take several minutes. Turn on either setting to prevent this. For End call after silence, see Call settings and advanced call handling.
AI starts speaking after silence and the silence warning.
Greeting and goodbye messages
The welcome message is the first thing the caller hears. It works the same way for inbound and outbound agents.
Under Welcome message, choose Dynamic (AI generated) (default) or Static (custom message). With Dynamic (AI generated), the agent writes its own opening for each call. With Static (custom message), the agent says the message you type word for word, which is useful when a name or disclosure has to be exact. You can add variables to a static message with Insert variable, such as the contact’s first name.
Welcome message types.
The Goodbye message is the sign-off the agent says when it ends the call. It does not play when the caller hangs up first. Choose one:
Default: inbound agents say “Thank you for calling! Have a wonderful day. Goodbye!” and outbound agents say “Thank you and have a wonderful day.” This option is selected when you create an agent.
Skip (no goodbye message): the agent ends the call without a sign-off.
Custom message: the agent says the message you type.
Static welcome messages and custom goodbye messages are limited to 450 characters each, and messages over the limit are not saved.
The Welcome message and Goodbye message fields.
Using dynamic variables
Dynamic variables let the agent pull live values into its instructions and messages instead of fixed text. There are three types:
Contact fields pull information stored on the contact in Aloware, such as first name, last name, email, and city.
System variables pull data the agent needs during the call, such as the current time, current hour, and current calendar.
Default dynamic variables are fallback values you set in the Dynamic Variables panel. Click Set Up, then + New key value pair, and enter a name and a value. A fallback is used only when a variable is not provided at call time. For example, set FirstName to John, and {{FirstName}} becomes "Hi John" when a contact has no first name. If a name matches an existing contact field, the contact's real value takes priority.
The Default Dynamic Variables window.
To add a variable to the instructions, click Insert variable and select a variable. The list includes your custom contact fields alongside the standard variables. Selecting a custom contact field inserts its {{field_key}} token, which resolves to the contact’s value at call time.
The Insert variable list.
To see how variables resolve before a live call, run a test as a real or mock contact. See Testing and reviewing your agent.