Skip to main content
Your prompt is the main thing that decides how your agent behaves on a call. This page explains what happens to the prompt before the model reads it, then gives practical advice that follows from it. It applies to a single prompt agent’s Agent instructions and a flow agent’s System prompt. A flow’s step prompts follow the same rendering rules.

How Hamsa uses your prompt

When a call starts, Hamsa prepares the prompt in this order:
  1. Variables and Jinja are filled in. Every {{ }}, {% %} and {# #} part is rendered with the call’s values. This happens once, at the start of the call.
  2. The prompt enhancer adds its sections, unless it is set to Disabled: speaking rules, and an instruction to speak the voice’s dialect.
  3. On every turn, the model also gets the current date and time in the agent’s time zone, plus short notes such as the caller’s detected gender when that setting is on. These notes are not saved in the conversation history.
The model then reads the prompt, the conversation so far, and the descriptions of the tools it may call, and writes a reply. The reply is spoken by the agent’s voice, so everything the model writes is heard by the caller.

What the prompt enhancer adds

Set the enhancer under the instructions (single prompt) or in System prompt (flow). It is Basic for new agents.
The Prompt enhancer list under Agent instructions, showing Disabled, Basic (selected) and AdvancedThe Prompt enhancer list under Agent instructions, showing Disabled, Basic (selected) and Advanced
What this means for your prompt:
  • With Basic or Advanced, don’t repeat these rules, and don’t write rules that contradict them (for example “list the options as bullet points”). Spend your words on your business.
  • With Disabled, you are responsible for everything the enhancer would have said. At least tell the model to reply in plain spoken sentences, to say numbers as words, and which language and dialect to speak.

Structure that works

A prompt the model can follow on a live call is short, concrete and ordered. One structure that works:
  • Headings help you, not only the model. With two or more headings, the editor shows an Outline to jump between sections.
  • Say when to use each tool. The model picks tools from their descriptions and your instructions. Name the tool and the moment (“before you offer a time”), and say what to do when it fails.
  • Keep facts the agent needs on every call in the prompt; put long reference material in the knowledge base. The whole prompt is sent on every turn, and the word and token count under the field shows what that costs.
  • Tell the agent how to end. A single prompt agent only hangs up on its own when Smart call end is on, and its condition is the Smart call end prompt. A flow agent ends at an End call step. See Call behavior settings.

Write for the ear

The caller hears every word the model writes, through a text-to-speech voice.
  • Ask one question at a time, and keep turns short. Long turns are hard to follow on the phone.
  • Spell out how to say things that are easy to get wrong: prices (“25 dinars”), codes, product names. For a word the voice keeps mispronouncing, add it to a pronunciation dictionary instead of working around it in the prompt.
  • Ask the agent to confirm what it heard for anything that matters, such as numbers, dates and names. Callers’ words come through speech recognition and can be misheard.
  • Write example phrases in the language and dialect the agent speaks. The dialect instruction tells the model which dialect to use; examples show it the tone.

Use variables safely

Variables let one prompt adapt to each call: Hello {{ customer_name }}. Values come from the call itself (system variables), from the request that starts the call (dynamic variables), from the agent’s environment, or from the conversation. See Variables and Jinja syntax. Three rules explain almost every surprise: Every value is text. A dynamic variable sent as 5 arrives as the text "5". A comparison between text and a number fails, so convert first:
The same goes for yes or no values. "false" is text, and any non-empty text counts as true, so compare it:
Values that look like a JSON object or list ({"plan": "gold"}) are read as objects, so {{ account.plan }} works. A missing variable renders as empty. Hello {{ customer_name }}, becomes Hello , when no name was passed. Give a fallback that also covers an empty value:
An error drops every Jinja part. If any part of the template can’t render (a syntax error, an unknown filter, comparing text with a number), the model gets the prompt with all {{ }}, {% %} and {# #} parts removed. Your conditional sections disappear silently and the call goes on. Preview the template in the Jinja2 template editor before you publish, with test data in the same form your calls send. When you branch on the kind of call, match the exact values:

Dates and times

Time variables use the agent’s Timezone from Call settings. Set it to your business’s time zone; see Call behavior settings.
  • Variables in the prompt are filled in once, when the call starts. In a long call, {{ current_time }} in the prompt still shows the start time.
  • The model also gets a fresh “Current date and time” line on every turn, so for “what time is it now” questions you don’t need a variable at all. Use the variables when the prompt itself needs the date, for example {% if current_weekday == "Friday" %}We are closed today.{% endif %}.
  • current_time is a sentence, not a number, so you can’t compare it with > or <.
For every system variable and its exact format, see System variables.

Arabic and dialects

  • The agent speaks the dialect of its voice. To change the dialect, pick a voice in that dialect. See Voice, language and dialect.
  • With the enhancer on, Hamsa adds a line such as “Always speak in Jordanian dialect of Arabic”, so you don’t need to.
  • With User gender detection on, the model is told each turn whether it is speaking to a man or a woman and, with the enhancer on, how to use the matching Arabic forms. You don’t need gender rules in the prompt. See Call behavior settings.
  • With the Language/dialect switcher on, the dialect instruction is rewritten when the agent switches, and {{ agent_dialect }} and {{ agent_language }} follow the switch.

Test the prompt

1

Preview the template

If the prompt uses Jinja, open the Jinja2 template editor and preview it with realistic test data, including a missing value and an empty one.
The Preview tab of the prompt editor, with Test data (JSON) and the rendered Preview outputThe Preview tab of the prompt editor, with Test data (JSON) and the rendered Preview output
2

Call the agent

Click Test and make a Browser call. Try the happy path, then the cases your rules cover: an off-topic question, a request for a person, a misheard number.
The Browser call dialog asking for values for the dynamic variables customer_name, loyalty_tier and member_since before the call startsThe Browser call dialog asking for values for the dynamic variables customer_name, loyalty_tier and member_since before the call starts
3

Read the call

Open the call in the Conversation log and read the transcript. Fix the prompt where the agent hesitated or broke a rule, then test again.

Good to know

  • There is no maximum prompt length, but every word is sent on every turn.
  • Dynamic variables need a value in the test dialog before a browser call starts.
  • A Jinja error never puts raw template code in front of the model or the caller; it removes the Jinja parts instead.

Jinja syntax

Supported syntax, filters and macros.

System variables

Names and exact formats.

Single prompt agents

Where the prompt lives and how to edit it.

Test your agent

Browser calls, phone calls and test values.