Writing the system prompt

The prompt is where nearly all agent behaviour comes from. It's also where nearly all agent problems come from. Time spent here pays back more than anywhere else in the product.

This page is the hand-written path: what a voice prompt has to contain and why. If you'd rather be interviewed than start from a blank box, the prompt wizard asks you through six focus areas and assembles a 17-section prompt you can then edit here — and the prompt test lets you rehearse either kind against a real agent before it takes calls.

Where to edit it

1. Open the dashboard.
2. Left sidebar → Configure → Agents.
3. Open the agent.
4. Top tab → Agent Overview.
5. Edit the System prompt block (keep First message separate — that is the spoken greeting).
6. Save changes / Close and save.
7. Top tab → Test → Start test call after every meaningful rewrite.

Voice prompts are not chat prompts

If you've written prompts for a text assistant, most of it transfers. Four things don't:

1. Everything you write will be spoken aloud. No markdown, no bullet points, no headings. A model that replies with a numbered list produces an agent that reads "one. Check the valve. two. Turn off the water" — which sounds broken.

2. Short is not a style preference, it's a requirement. Nobody listens to a paragraph on the phone. One or two sentences per turn. If there's more to say, say some and ask if they want the rest.

3. The agent reads a transcript, not audio. Everything arrives with transcription artefacts — homophones, spoken punctuation (fayaz at gmail dot com), numbers as words (two thirty), and occasional words nobody said. Your prompt has to expect this.

4. Nothing can be re-read. A caller can't scroll back. Say important things once, clearly, and confirm anything that matters.

A structure that works

Five sections, in this order. The order matters — the model weights early instructions more heavily.

IDENTITY
You are Sam, the phone assistant for Northwind Plumbing.
You are speaking with a customer on the phone.

WHAT YOU DO
- Book plumbing appointments
- Answer questions about pricing, service areas and opening hours
- Take a message when a human needs to call back

WHAT YOU DON'T DO
- Give plumbing advice or diagnose problems over the phone
- Quote exact prices for work not on the price list
- Discuss anything unrelated to Northwind Plumbing
If asked, say plainly that you can't help with that, then offer
to take a message.

HOW YOU SPEAK
- One or two sentences per reply. This is a phone call.
- No lists, no formatting. Everything you say is read aloud.
- Confirm dates, times, addresses and phone numbers by repeating
  them back before acting.

ENDING THE CALL
When the caller's need is met and they have nothing else, say a
short goodbye and end the call. Don't wait to be dismissed.

That's a complete, working prompt. Start here and add only what a real call proves you need.

The five sections

Identity

Who the agent is and what situation it's in. One or two lines.

Include that it's a phone call — it changes how the model writes. Models produce noticeably more speakable text when told they're speaking.

What you do

An explicit, short list. Not aspirational — things the agent can genuinely accomplish with the tools and knowledge you've given it.

Don't promise what it can't do

Listing "process refunds" when no refund tool exists produces an agent that confidently tells callers their refund is processed. Every capability you list must map to a tool, the knowledge base, or something it can simply say.

What you don't do

The section people skip, and the one that prevents the worst failures. Be specific — "don't give medical advice" beats "be careful".

Always say what to do instead. "Say you can't help and offer to take a message" produces a graceful decline; a bare prohibition produces an agent that stalls.

How you speak

Length, format, and the confirmation rules. The confirmation rule is the important one:

Confirm dates, times, addresses and phone numbers by repeating
them back before acting.

This exists because of transcription errors. fifteen and fifty are one bad frame apart. Reading values back catches it while it's still cheap.

Ending the call

Agents that won't hang up are a common complaint, and it's always this section missing. Say explicitly that the agent should close the call when the need is met, without being asked.

Variables

Use placeholders for anything that changes per call:

You are calling {{customer_name}} about their appointment on
{{appointment_date}}.

One agent, many calls, no duplication. Define the placeholders in the prompt editor, and provide values when the call is placed.

Things that come up

It says too much

Almost always the prompt permitting it. Add an explicit limit, and reduce the token budget on Agent Overview — a large budget is room to ramble.

Never speak for more than two sentences without pausing for the
caller to respond.

It answers questions nobody asked

A specific failure worth naming: the agent invents the caller's next line and answers it. Add:

Say one thing, then stop and wait. Never write the caller's side
of the conversation.

It acts on something the caller didn't say

Transcription can produce a plausible sentence from noise. For anything irreversible — ending the call, booking, transferring — require confirmation:

Before ending the call, transferring, or booking anything, confirm
with the caller in your own words and wait for a clear yes.

It guesses instead of admitting a gap

If you don't know something or can't find it, say so plainly and
offer a next step. Never guess at prices, availability or policy.

It ignores one rule in a long prompt

Usually a model capability issue rather than a wording issue. Try a stronger model on Agent Overview before rewriting. Repeating an instruction the model is already skipping rarely helps.

Prompt or knowledge base?

A common confusion, with a clean rule:

Put in the prompt	Put in the knowledge base
Who the agent is	Your price list
What it does and refuses	Opening hours and locations
How it speaks	Policies, terms, FAQs
When to use which tool	Product specifications
Rules that apply to every call	Facts referenced occasionally

Rule of thumb: behaviour goes in the prompt, facts go in the knowledge base. Facts in a prompt are expensive on every single turn and go stale silently.

How to iterate

1. Start with the five-section skeleton above.
2. Test the main case, one out-of-scope case, and hanging up.
3. Place a real call — real audio produces problems the Test tab won't.
4. Read the transcript under Conversations. Note what the agent heard.
5. Change one thing.
6. Repeat.

Changing several things at once means you learn nothing from the result. Almost every "the agent did something bizarre" turns out, in the transcript, to be the agent responding sensibly to something it misheard.

Next

• Tools — giving it things to do
• Knowledge base — giving it things to know
• Testing your agent