> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Single prompt agents

> Set up a single prompt agent: the greeting, the agent instructions, Jinja templates, word and token counts, tools, and the sections of the Configuration panel.

A single prompt agent runs the whole call from one set of instructions. The model reads your instructions, listens to the caller, and decides what to say and which tools to use. This page walks through the single prompt editor: the greeting, the instructions, and the settings beside them.

If your call needs fixed stages, rules the model must not bend, or API calls at set points, build a [flow agent](https://docs.tryhamsa.com/agents/flow/overview.md) instead.

## The editor at a glance

Open an agent from **Agents list** to get the editor. On the left are two cards:

* **Greeting message**: what the agent says first.
* **Agent instructions**: the prompt the model follows for the whole call, with **Enhanced turn taking** and **Prompt enhancer** under it.

On the right is the **Configuration** panel. On a narrow screen it sits under the prompt; open it with **Configuration** in the header.

| Section | What it holds | Read more |
| - | - | - |
| **Voice settings** | Voice, expressiveness, speech recognition model, voice dictionaries | [Voice, language and dialect](https://docs.tryhamsa.com/agents/settings/voice-and-language.md) |
| **LLM configuration** | Provider, model, temperature | [Choose the model](https://docs.tryhamsa.com/agents/settings/model.md) |
| **Noise cancellation** | Noise filtering for the caller's audio | [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#noise-cancellation) |
| **Knowledge base** | The items the agent can search, and **Agentic RAG** | [Knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/overview.md) |
| **Tools** | The APIs, MCP servers and web tools the agent can call | [Add tools](#add-tools) |
| **Variables** | System, dynamic and environment variables | [Variables](https://docs.tryhamsa.com/agents/variables/overview.md) |
| **Outcome** | The data extracted from each call | [Call details](https://docs.tryhamsa.com/agents/monitor/call-details.md) |
| **Phone number** | The numbers that reach this agent | [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md) |
| **Call settings** | Turn taking, interruptions, silence, call length, sounds, time zone | [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md) |
| **Call webhook** | Where Hamsa sends the call data when a call ends | [Webhooks](https://docs.tryhamsa.com/agents/connect/webhooks.md) |
| **Policies & guardrails** | Rules the agent follows and checks it can't skip | [Policies & guardrails](https://docs.tryhamsa.com/agents/safety/policies-and-guardrails.md) |
| **Functions & macros** | JavaScript and Jinja helpers | [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md) |

![The single prompt editor: the Greeting message and Agent instructions cards on the left, and the Configuration panel on the right listing Voice settings, LLM configuration, Noise cancellation, Knowledge base, Tools, Variables, Outcome, Phone number, Call settings, Call webhook, Policies & guardrails and Functions & macros](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/single-prompt-editor-light.webp)

## Write the greeting

The greeting is the agent's first line. Pick how it's made with the tabs on the **Greeting message** card.

![The Greeting message card with the Static message and Prompt tabs, the greeting text and its 81/191 character count](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/greeting-message-light.webp)

| Tab | What happens on the call |
| - | - |
| **Static message** | The agent says the text exactly as written. |
| **Prompt** | The text is an instruction. The model writes the first line from it, with your agent instructions in view. Use this when the greeting should depend on who is calling. |

* The greeting is required and can be up to 191 characters on both tabs.
* Both tabs accept variables, for example `Hello {{ customer_name }}, this is Sara from Acme.` Variables are filled in before the agent speaks.
* The caller can't interrupt the greeting.
* If **Wait for user to speak first** is set to wait, the greeting plays after the caller's first words instead of an answer to them. See [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#start-of-the-call).

## Write the agent instructions

**Agent instructions** is the prompt the model follows for the whole call. It is required and has no length limit. For what to put in it, see [Write a prompt that works on calls](https://docs.tryhamsa.com/agents/build/write-a-prompt.md).

Under the text you see a count, for example "420 words · about 560 tokens". The token count is an estimate of what the prompt costs on every turn; the model counts its own way. The whole prompt is sent with every reply, so a longer prompt costs more on every turn of every call.

When the prompt has two or more Markdown headings (`#`, `##` or `###`), an **Outline** menu appears next to the count. Use it to jump to a section.

### Insert variables

Type `{{` to get suggestions, or click **Insert variable** in the field (Cmd+K on Mac, Ctrl+K on Windows). The list shows system, dynamic and environment variables. A name the agent doesn't know is marked in the text so you can add it as a dynamic variable. See [Variables](https://docs.tryhamsa.com/agents/variables/overview.md).

### Use the Jinja2 template editor for Jinja

For conditions, loops and filters, open the **Jinja2 template editor** with the code button in the field. Once the prompt contains a `{% %}` block or a `{# #}` comment, the field shows a read-only preview, and you edit it in the prompt editor.

![The prompt editor with the template on the left, line numbers and Jinja highlighting, the Variables tab listing system variables on the right, and Save template at the bottom](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/hamsa-prompt-editor-light.webp)

**1. Open the prompt editor**

Click the code button in **Agent instructions**, or click the read-only preview.

**2. Edit the template**

Write in the editor on the left. The status line tells you whether the syntax is valid and points at the line of any error.

**3. Preview it**

Open the **Preview** tab and click **Preview**. The preview fills variables from **Test data (JSON)**, which you can edit, or from the values of your last completed call.

**4. Save**

Click **Save template** (Cmd+S on Mac, Ctrl+S on Windows).

![The prompt editor with a Jinja template on the left and the Preview tab on the right: Test data (JSON) above and the rendered Preview output below, with a Valid template status line](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/hamsa-prompt-editor-preview-light.webp)

The **Help** tab has a Jinja quick reference. The preview uses sample data, so a call can render differently when real values arrive. For the syntax Hamsa supports, see [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md).

### Prompt enhancer and enhanced turn taking

Two settings sit under the instructions:

* **Prompt enhancer** (**Disabled**, **Basic**, **Advanced**; default **Basic**) adds Hamsa's own speaking rules and the dialect instruction to your prompt. See [What the prompt enhancer adds](https://docs.tryhamsa.com/agents/build/write-a-prompt.md#what-the-prompt-enhancer-adds).
* **Enhanced turn taking** improves how the agent hears numbers and short "mm-hm" sounds. See [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#turn-taking-and-interruptions).

## Add tools

Tools let the agent act during the call: look up an order, book a slot, ask your website to do something.

**1. Open the Tools section**

In **Configuration**, open **Tools** and click **Select tools**.

**2. Find the tools**

Search, or filter by type (**API request**, **MCP server**, **Web tool**), status or collection. API tools can also be filtered by method, such as GET or POST. Tools that run in the background carry an **Async** tag.

**3. Pick them**

Select the tools this agent may use, then close the list.

![Select tools in the Configuration panel: search, type, status and collection filters, method chips, and six API tools with lookup\_order and create\_return selected](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/select-tools-light.webp)

The model decides when to call each tool from the tool's description and your instructions, so say in the prompt when each one should be used. Tools are created in **APIs & MCPs**; see [Tools](https://docs.tryhamsa.com/agents/tools/overview.md).

Besides your tools, a single prompt agent can have three built-in abilities, each switched on in its own setting:

| Ability | Turn it on in | What the agent can do |
| - | - | - |
| Search the knowledge base when it decides to | **Knowledge base** > **Agentic RAG** | Look things up in your knowledge base items. With it off, Hamsa searches on each caller turn instead. |
| Switch language or dialect | **Call settings** > **Language/dialect switcher** | Change dialect when the caller asks or speaks another one. |
| End the call | **Call settings** > **Smart call end** | Say goodbye and hang up when the conversation is done. |

A single prompt agent has no transfer tool. The only transfer it can make is at the maximum call length (see [End the call](https://docs.tryhamsa.com/agents/settings/call-behavior.md#end-the-call)). For transfers during the conversation, use a flow agent's [Transfer call step](https://docs.tryhamsa.com/agents/flow/steps/transfer-call.md).

## Save, test and publish

* Your edits autosave to your own draft. The header shows **Save draft**, **Saving draft…** and **Draft saved**.
* Click **Test** to call the agent with **Browser call**, **Phone call** or **Chat**. Testing is off while there are unsaved changes. See [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md).
* Callers only hear a published version. To see what changed against the live version and publish, see [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md).

![The Test menu open in the editor header, with Browser call, Phone call, Chat and Test values](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/start/test-menu-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=9ecca138f493734824a87d0bfb9f6f4d)

## How it works on a call

1. When the call starts, Hamsa fills the variables in your instructions and adds what the prompt enhancer adds.
2. The agent says the greeting (or waits for the caller, if set to).
3. On each turn, the model reads the instructions, the conversation so far and the current date and time, then replies or calls a tool.
4. The call ends when the caller hangs up, when the agent uses smart call end, or when the maximum call length is reached. With **Smart call end** off, the agent never hangs up on its own before the limit.

## Good to know

* The greeting is capped at 191 characters. Put anything longer in the instructions and use a **Prompt** greeting.
* Time variables in the instructions are filled in once, at the start of the call. The model still gets the current time on every turn. See [Write a prompt that works on calls](https://docs.tryhamsa.com/agents/build/write-a-prompt.md#dates-and-times).
* If a Jinja part of the instructions fails on a call, the agent gets the text with all Jinja parts removed, not the raw template. Preview before you publish.
* The **Configuration** panel switches to **Live call logs** during a browser test call.

## Related

> [card] [Write a prompt that works on calls](https://docs.tryhamsa.com/agents/build/write-a-prompt.md)
>
> How the runtime uses your prompt, and what to write.

> [card] [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md)
>
> Turn taking, silence, call length and sounds.

> [card] [Variables](https://docs.tryhamsa.com/agents/variables/overview.md)
>
> The values you can use in the greeting and instructions.

> [card] [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md)
>
> Call the agent before you publish.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.