Agent settings | Hams AI Docs

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 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 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 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.

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.