> This page is for Voice AI Platform.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.hams.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hams.ai/_mcp/server.

# Agent settings

> Every panel on an agent — what it controls, what the values mean, and which ones matter.

Whichever type you build, an agent's settings are grouped into the same panels. A chat agent shows
fewer of them: **Speech Settings**, **Call Setting** and **User Turns** exist only where there is a
phone line. A Single Prompt
agent shows them down the right-hand side; a Conversation Flow keeps them under **Global Settings**;
a squad keeps them under **Squad Overrides**, where they apply to every member at once.

Most agents need only a few of them. This page covers all of them, roughly in the order you would
reach for them.

## Tools

The actions the agent can take beyond talking — looking a customer up, booking a slot, writing a
record back.

Tools are built once in **Tools** in the sidebar and then selected here, so the same tool can serve
several agents. An agent with no tools can only answer from its prompt, and cannot reach its [knowledge bases](/platform/agents/knowledge) at all.

The model decides when to call a tool from the tool's name and description, so both are functional
text, not labels. Describe *when* the tool should be used, not just what it is.

See [Tools](/platform/agents/tools) for the five kinds of tool and how to build each one.

## Predefined Functions

Two behaviours that would otherwise need a tool of your own.

| Function        | What it does                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| **End Call**    | Lets the agent hang up when the conversation wraps up, the caller says goodbye, or they ask to hang up |
| **Call Rating** | Asks the caller to rate the call from 1 to 5 before it ends, and collects the rating in conversation   |

Turn **End Call** on for almost every voice agent. Without it the agent waits for the caller to hang
up, which leaves calls open and inflates their duration.

## Advanced Settings

How the model generates text. The defaults are sensible; change these only with a reason.

| Setting                   | Range                | What it does                                       |
| ------------------------- | -------------------- | -------------------------------------------------- |
| **Temperature**           | 0.0–2.0              | Higher is more varied, lower is more predictable   |
| **Frequency Penalty**     | −2.0–2.0             | Positive values make the agent repeat itself less  |
| **Presence Penalty**      | −2.0–2.0             | Positive values push the agent toward new topics   |
| **Seed**                  | ≥ 0                  | Same seed and same settings produce similar output |
| **Max Completion Tokens** | ≥ 1                  | Caps the length of a single reply                  |
| **Service Tier**          | auto, flex, priority | Trades latency against throughput                  |

For voice, keep temperature low. A phone conversation rewards predictability, and a caller cannot
re-read a sentence that came out oddly.

## Speech Settings

How the voice sounds. Voice agents only.

| Setting                | What it does                                                      |
| ---------------------- | ----------------------------------------------------------------- |
| **Stability**          | How closely the voice holds to its original character             |
| **Style**              | Exaggerates the voice's style. Raising it delays the response     |
| **Speed**              | Below 1.0 slows the speech, above 1.0 speeds it up                |
| **User Speak Boost**   | Amplifies similarity to the original speaker. Delays the response |
| **Text Normalization** | How text is prepared before it is spoken                          |

Several of these trade latency for quality, and on a phone call latency is the more expensive of
the two. A pause before every reply is more noticeable to a caller than a slightly flatter voice.

Leave **Speed** at 1.0 unless callers are telling you the agent is hard to follow.

## Call Setting

How the call itself behaves. Voice agents only.

### Beginning

| Setting                   | What it does                                                           |
| ------------------------- | ---------------------------------------------------------------------- |
| **Pause before speaking** | How long the agent waits before it starts talking                      |
| **Silence timeout**       | How long a silence runs before the agent treats the caller as finished |

### Timing

| Setting                  | What it does                                                            |
| ------------------------ | ----------------------------------------------------------------------- |
| **Ring duration**        | How long the phone rings before the call counts as unanswered           |
| **Max call duration**    | The longest a call may run before it is ended automatically             |
| **Max duration message** | Optional. Played when the call reaches that limit, up to 500 characters |

Set a **Max duration message**. A call that simply cuts off at the limit reads as a dropped line.

### Background audio

An ambient sound that loops for the whole call — keyboard, people, office, or coffee shop — with an
adjustable volume.

It makes a call sound less clinical, but it also sits underneath the caller's own speech. Keep the
volume low, and leave it off if callers are in noisy places themselves.

### Voicemail detection

Detects when a voicemail system answers instead of a person, which matters for outbound calling.
The agent can then hang up, or leave a message you have written.

### Turn-taking

When the agent thinks a caller has started and finished speaking. These are the settings to reach
for when an agent interrupts people, or leaves long silences.

| Group     | What it controls                                                                                                                                      |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Start** | What counts as the caller beginning to speak — a minimum number of words, voice activity detection, or both in the order you choose                   |
| **Stop**  | What ends the caller's turn — a turn analyser, or a fixed silence timeout                                                                             |
| **Mute**  | When the caller's audio is ignored: always while the agent speaks, only during its first reply, until its first reply completes, or while a tool runs |

Mute rules combine, so more than one can apply.

Muting during tool calls is the one most agents benefit from: it stops a caller's "hello? are you
there?" from being taken as a new instruction while a lookup is running.

## User Turns

Detection of caller turns that are incomplete or unusually long, handled separately from the
turn-taking rules above. Voice agents only. Turn it on when callers tend to think aloud mid-sentence and the agent
answers too early.

## Classification

The fields pulled out of every finished conversation, so calls can be searched and counted rather
than only listened to.

Four fields are there by default:

| Field             | Type              |
| ----------------- | ----------------- |
| `call_summary`    | Text              |
| `call_successful` | Boolean           |
| `user_sentiment`  | Selector          |
| `call_tags`       | Multiple selector |

**Add Classification** adds your own, an appointment type, a product, a reason for calling. A
field is only as good as its description, which is what tells the model where to look.

Add the two or three fields you will actually filter reports by. Every extra field is another
judgement the model has to make about every call.

## Post-call Analyses

Checks run on the conversation after it ends, scoring how well the agent did rather than what the
caller wanted.

| Analysis               | What it looks for                                                  |
| ---------------------- | ------------------------------------------------------------------ |
| **Knowledge accuracy** | Whether the agent's answers matched the knowledge it was given     |
| **Hallucination**      | Whether the agent stated things it had no basis for                |
| **Out of domain**      | Whether callers asked for things the agent was not built to handle |

Each can be turned on or off, and each has a prompt that is written from the agent's own
configuration until you edit it. Out-of-domain results are the most immediately useful: they tell
you what to build next.

## Alerts

Notification when matching calls hit a threshold inside a time window, not for a single call but for
a pattern. Every rule is re-checked once a minute, and only completed calls are counted.

| Setting               | What it does                                                                |
| --------------------- | --------------------------------------------------------------------------- |
| **Severity**          | Info, Warning or Critical. A label for whoever reads it, not a routing rule |
| **Trigger Condition** | One or more conditions on a call, such as *call successful is false*        |
| **Trigger when**      | A count or a percentage of matching calls, within a window you set          |
| **Notification**      | Email and/or the agent's webhook. At least one is required                  |

For example: ten or more calls in one hour where the call was not successful.

A workspace can hold up to three alert rules, and each watches one agent, so spend them
deliberately. See [Alerts](/platform/agents/alerts) for the signals you can watch, what happens when
one fires, and how to choose thresholds.

## Webhook

Where this agent's events are delivered as they happen.

| Setting            | What it does                                                                              |
| ------------------ | ----------------------------------------------------------------------------------------- |
| **Webhook URL**    | Where events are sent                                                                     |
| **HTTP Method**    | The method used for the request                                                           |
| **Signing Secret** | 16–256 characters. Events are signed with HMAC-SHA256 so you can verify they came from us |
| **Events**         | Which events to send: call started, call ended, call analyzed                             |

Set a signing secret. Without one, your endpoint has no way to tell a real event from anything else
that finds the URL.

> **Note**
>
> A workspace can also have its own webhook, separate from this one. Where both
> are set, both receive the event, deduplicate on the call it refers to.

## Security

What is kept, what is removed, and what the agent is not allowed to do.

### Data Storage

How much of a conversation is retained: everything, everything except personal data, basic
attributes only, or nothing.

Choose the least you can work with. Transcripts are useful for improving an agent, but a transcript
you never read is only a liability.

### PII Redaction

Removes personal data from conversations automatically. Categories include phone numbers, email
addresses, postal addresses, payment card numbers, dates of birth, names, IP addresses, bank
accounts, passports and driving licences, alongside national ID and Iqama numbers.

Redaction happens before the conversation is stored, so it also applies to anything read back from
it later.

### Safety Guardrails

Blocks the agent from producing content in categories you restrict, among them hate speech,
violence, self-harm, illegal activity, profanity, and medical, financial, legal or political advice.

The advice categories are the ones most worth setting deliberately. An agent for a clinic or a bank
will be asked for advice it must not give, and a guardrail is a firmer answer than a line in a
prompt.

### Secure URLs

Adds a signature to URLs the agent produces, expiring them after 24 hours.

### Fallback Voice

A voice to fall back on if the configured one is unavailable, so a call continues rather than
failing.

### Default Dynamic Variables

Default values for the `{{ }}` variables in your prompt, used when a value is not supplied at
runtime.

Give every variable a default. A prompt that renders as *"Hello , your appointment is on "* is worse
than one that never mentioned the name at all.

## Pre-call Lookup

Data fetched about the caller before the conversation starts, so the agent opens already knowing who
it is speaking to.