Writing prompts for a voice

Instructions guide the model; the voice speaks its replies and the configured greeting. Write instructions that produce clear spoken replies, including when a task or another agent takes over. On this page:

Write speech, not text - the voice reads your formatting
Never write a specimen value - the worst failure here
Say the format, do not show it - put it in the type
Saying a value and confirming one - two different lines
Name only the values this prompt needs - every placeholder is a grant
Set the spoken language in every role - each prompt that can speak
Avoid repeated waiting lines - one announce: per wait
Give every realism rule a budget - how often, not just how
Tell the model to vary - openers callers notice
Keep the rules load bearing - prompt rule, or code guard

Write speech, not text

The voice reads your formatting. Asterisks, bullet points, headings and emoji all get pronounced or produce strange pauses. So the model’s output has to be plain spoken sentences, and the way to get that is to say so:

instructions.md

A text to speech voice reads out everything you write, exactly as you write it.
So write speech, not text.

- Whole sentences in ordinary capitalization. No markdown, no asterisks, no
  bullet points, no headings, no emoji, no symbols: the voice reads them out
  loud.
- Never send a bare fragment. A number or an amount sits inside a sentence.
- Capitals are read letter by letter, so use them only when that is what you
  want, like ATM.
- One or two short sentences a turn, one question at a time.

Two of those are less obvious than they look. Capitals really are spelled out, so a prompt that writes a service name in caps gets it spelled. And a bare fragment is the most common failure in practice: a model answering “what time” with “11:30.” gives the voice nothing to work with, where “Friday at 11:30 AM works.” reads naturally.

Never write a specimen value

This is the rule with the worst failure, and it looks harmless. A prompt that explains how to format a phone number and shows an example number to make the grouping clear has put a number in front of the model. A model cannot tell an example value from a real one. Before any tool has run, that example is the only number the model holds, and it may read it out to the caller as theirs. A caller who hears a confident readback says yes to it.

A model cannot tell an illustration from a value it is holding. Describe the shape in words instead of showing one.

Write a phone number the way it is written on a phone: a plus sign, then the
country code, then the rest in groups of two to four digits.

This is also the one way around confirm:. The compiler keeps an unconfirmed value out of every prompt except the step that asks the caller to agree to it, and a number typed in as an example is not a value the compiler can see. The protection is real and a hardcoded example defeats it. The same applies to any identifier a caller might mistake for their own: account numbers, booking references, addresses, dates of birth.

Say the format, do not show it

A typed value has one correct spelling and the model needs to know it. Put the format in the field’s description, where it travels with the value into every schema the model sees:

state.py

class State(BaseModel):
    scheduled_time: time | None = Field(
        None, description="The time the caller agreed to, on the 24-hour clock, like 09:30 or 17:45."
    )

Pydantic checks the value where it is saved, but the model only learns the spelling from your description. Without it, a model sends the spelling its own prompt requires out loud. A task told to say times as “11:30 AM” to the caller will send "11:30 AM" to a field that wants 11:30. The finish call is refused, the model corrects itself on the next request, and the caller hears a pause for no reason.

Say the format once, in the type. A prompt that repeats it can drift from the validator, and then the two tell the model different things.

Saying a value and confirming one

Ordinary speech carries a value once. Confirming it is the moment the caller has to hear every character. Those are two lines, and a prompt that writes one of them gets one shape used for both.

instructions.md

Say an email address the ordinary way, all one piece, when you first mention
it. When you read one back to confirm it, delimit the part before the at sign
so each character is heard on its own, then say the at sign and the domain as
ordinary words. Say a reference number normally, and confirm it in the groups
it is written in. Wait for a yes before acting on a confirmed value, and
confirm it again after any correction.

The rule is delimiting, not spelling. Never write “spell it letter by letter”: that makes the model do its own preprocessing, and it loses to the voice’s. A B C is the instruction. A phone number is the exception: it stays in its written form even when it is confirmed, because commas inside a run of digits break it.

Name only the values this prompt needs

Saved values reach a prompt only through placeholders you write. Keep those references close to the instruction that uses them:

Move appointment {{state.appointment_id}} to {{state.appointment_date}} at
{{state.appointment_time}}.

Choose who confirms success. A simple pattern is for the task to finish immediately after the tool succeeds and for the owner to confirm once:

tasks/booking.md

After the booking tool reports success, finish with the saved appointment.
Let the owner confirm it to the caller.

instructions.md

Latest saved appointment: {{state.appointment}}
When the booking task completes, confirm this appointment once in plain speech.

The owner needs the placeholder because a task’s private conversation does not return with its completion status. Do not add saved values just because they exist. Every placeholder is an intentional context grant to that prompt.

Set the spoken language in every role

Set the listening and speaking model language, then put the desired language in every agent and task prompt that can speak:

Speak English throughout the call, including phone-number readback and
confirmation. Use short spoken sentences without Markdown formatting.

The speech model’s language: en setting does not by itself tell the thinking model which language to write. A phone number’s country code should not decide the conversation language. A receiving task or agent has its own instructions, so it needs the language rule too.

Avoid repeated waiting lines

Tools, tasks, and handoffs can have an optional announce: line. Omit it when there is no useful wait to explain. If you use one, tell the model to let that line cover the wait and avoid another “let me check” before or after it. Check adjacent steps as well. A tool announcement followed by a task announcement can sound like repetition even when each is short.

Give every realism rule a budget

Filler words, restarts and hesitations make an agent sound human in the right quantity, and obviously synthetic in any other. A rule that says how to do one and not how often gets it on every turn. So write the frequency into the rule, and show plain speech as the good line:

instructions.md

Most turns carry no filler at all. Plain, direct speech is the default, and
several turns in a row without any is right. At most one filler in a turn,
never two in a sentence, and never a run like "yeah, um, so". Once or twice in
a whole call, a better phrasing can land mid sentence: drop the first one and
carry on, without apologising. Every other turn comes out whole.

An example outweighs the sentence under it. A prompt showing “Yeah, um, so, I can do that.” as the good line produces that opener nearly every turn, whatever a caveat below it says. Demote the stacked form to the bad example instead.

Tell the model to vary, and it will

Repetition is the thing callers notice first and the easiest to fix. A prompt that only says what to do produces the same opener every turn.

Vary your opener, and never open two turns in a row the same way. "Right, ...",
"Okay, so ...", "Mhm, ...", "Ah, ...", or no opener at all.

For a missed reply, ask plainly: “I missed that, could you say it again?” Use a waiting line only when it helps the caller understand a noticeable pause. What to leave out: apologies for the process, thanking the caller for their patience, and “I completely understand”. They read as polite and land as filler.

Keep the rules load bearing

A prompt grows every time something goes wrong on a call, and an agent whose prompt has accumulated forty rules starts obeying the wrong ones. One package’s prompts reached seven hundred lines and the agent’s behaviour got worse, not better, because the two rules that mattered were buried in thirty that recorded past incidents. When you fix something with a prompt rule, check whether it can be a code guard instead. A duplicate entry, a missing field, a value in the wrong format: those are guards. They run every time, and they cost no tokens on any turn. Keep the rule in the prompt when it is genuinely a judgment call, and delete the archaeology.

Get started

Build the agent

Best practices

Run and observe

Optimization

Deploy

Phone calls

Targets and models

Configuration files

CLI

Community

Releases

Writing prompts for a voice

Write speech, not text

Never write a specimen value

Say the format, do not show it

Saying a value and confirming one

Name only the values this prompt needs

Set the spoken language in every role

Avoid repeated waiting lines

Give every realism rule a budget

Tell the model to vary, and it will

Keep the rules load bearing

Where the mechanics live

Designing declared state

Choosing a voice

​Write speech, not text

​Never write a specimen value

​Say the format, do not show it

​Saying a value and confirming one

​Name only the values this prompt needs

​Set the spoken language in every role

​Avoid repeated waiting lines

​Give every realism rule a budget

​Tell the model to vary, and it will

​Keep the rules load bearing

​Where the mechanics live

Designing declared state

Choosing a voice

Write speech, not text

Never write a specimen value

Say the format, do not show it

Saying a value and confirming one

Name only the values this prompt needs

Set the spoken language in every role

Avoid repeated waiting lines

Give every realism rule a budget

Tell the model to vary, and it will

Keep the rules load bearing

Where the mechanics live