> ## Documentation Index > Fetch the complete documentation index at: https://docs.callers.ai/llms.txt > Use this file to discover all available pages before exploring further. # Prompting voice agents > Write scripts, instructions, and scenarios that sound natural on the phone: short turns, one question at a time, and clear guardrails. A voice agent is only as good as what you write for it. Text that reads well on screen often sounds stiff, long, or confusing when spoken. This guide shows how to write steps, instructions, and scenarios that work for speech, using the tools built into the Callers script editor. ## How Callers reads what you write Your agent combines several sources each time it speaks. Knowing which source does what helps you put each piece of content in the right place. | Source | Where you edit it | Use it for | | - | - | - | | **Script steps** | Script tab, inside each block | What the agent says, in order. The main path of the conversation. | | **Inline instructions** | Inside a step, with the **Instructions** tag | Hidden guidance the contact never hears: tone, conditions, constraints. | | **Scenarios** | Scenarios tab | Answers to questions and objections that can come up at any point. | | **Agent Instructions** | Settings → General Info → **Agent Instructions** | Rules that apply to the whole conversation: persona, tone, what never to do. | | **Knowledge base** | Knowledge (Resources) → connect to the agent | Facts the agent looks up when asked: policies, product details, FAQs. | | **Guardrails** | Guardrails page and agent settings | Hard limits checked before or while the agent speaks. | > [!TIP] > > Put each fact or rule in exactly one place. If the same price appears in a step, in Agent Instructions, and in the knowledge base, the agent may quote different versions on different calls. ## Write for the ear ### Keep turns short Aim for one to three short sentences per step. On a call, a contact cannot skim or scroll back. A long turn invites interruptions and makes the agent sound like a recording. ### Ask one question at a time End most steps with a single, specific question. Two questions in one turn usually get one answer, and the agent then has to guess which one was answered. ### End steps with a question A step that ends on a statement leaves dead air. The contact waits for the agent, the agent waits for the contact, and after a while the agent breaks the silence. Close with a short check such as "Does that work for you?" unless the step ends the call. ### Prefer specific choices over open questions "Would Tuesday morning or Thursday afternoon work better?" is easier to answer on the phone than "When would you like to meet?" and gives the agent a clean answer to act on. ### Bad and better phrasing **Long turns** **Before** > Hi `{{first_name}}`, I'm calling from Acme Insurance because we noticed that your policy is coming up for renewal next month, and we wanted to let you know about some new coverage options and discounts we're offering this year, which could save you money. Do you have a few minutes, and would you also like to hear about our home bundle? **After** > Hi `{{first_name}}`, this is Sam from Acme Insurance. Your policy renews next month. Do you have two minutes to go over your options? **Two questions** **Before** > What's your current provider and how much are you paying each month? **After** (two steps) > Who's your current provider? > And roughly how much do you pay each month? **Open-ended** **Before** > When would be a good time for a call with our specialist? **After** > I can book you with a specialist. Does tomorrow morning or tomorrow afternoon work better? **Links** **Before** > You can sign up at [https://www.acme.com/signup?ref=phone](https://www.acme.com/signup?ref=phone). **After** > I'll text you a link to sign up right after this call. Is this the best number for that? Then add an **SMS** step that sends the link. ## Numbers, dates, emails, and links Spoken formats differ from written ones. Write content the way you want it heard, then confirm on a test call. | Content | Guidance | Example | | - | - | - | | Prices and amounts | Round where you can. Say the currency. | "about forty dollars a month" instead of "\$39.99/mo" | | Dates | Use the day and month in words. Avoid numeric formats such as 03/04, which are ambiguous across regions. | "Tuesday, March 4th" | | Times | Say the time and part of day. Add the time zone if the contact may be elsewhere. | "two thirty in the afternoon, Eastern time" | | Phone numbers and codes | Ask the agent to read them in small groups and confirm. | Add an instruction: "Read the code in groups of three digits." | | Email addresses | Don't read long addresses aloud. If you must collect one, ask the contact to spell it and read it back. | "Could you spell that for me?" | | URLs | Never read a URL aloud. Send it by SMS, WhatsApp, or email instead. | See the **Links** tab above. | | Acronyms and brand names | If the voice mispronounces them, add an entry to a pronunciation dictionary rather than misspelling the word in the script. | See [Pronunciation dictionary](https://docs.callers.ai/documentation/voice/pronunciation-dictionary.md). | > [!TIP] > > For words the agent mishears (product names, surnames, jargon), add them to the [speech recognition vocabulary](https://docs.callers.ai/documentation/voice/speech-recognition-vocabulary.md). For words it mispronounces, use the [pronunciation dictionary](https://docs.callers.ai/documentation/voice/pronunciation-dictionary.md). ## Use variables to personalize Insert variables such as `{{first_name}}` or `{{renewal_date}}` into steps, instructions, and scenarios with the **Variables** tag. Values come from your contact upload, the API `data` field, or a pre-conversation action. * Map every variable to a column or field. A variable with no value is spoken as nothing, which can leave a sentence broken. * Write sentences that still make sense if an optional variable is empty, or mark the variable as required. * Format values in your data the way you want them spoken. A date stored as `2026-11-03` is harder to say naturally than `November 3rd`. If you can't change the data, add an instruction such as "Say the renewal date as a month and day." See [Variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md) for built-in variables and transcript variables. ## Script steps or instructions? Each step can contain spoken text, inline instructions, or both. Decide who writes the words for each step. > **Scripted step** > > You write the exact words. Use it for disclosures, legal lines, prices, and anything approved word for word. > **Instruction-driven step** > > You describe what to say and the agent composes it. Use it when the line depends on data or on what the contact just said. To add an inline instruction, choose the **Instructions** tag while editing a step, type the guidance, and press Enter to end the instruction. **Avoid giving two sources for the same line.** If a step has a full sentence and an instruction that also says what to say, the agent may say both, merge them, or pick a different one on each call. **Conflicting** > Great, I can see your balance now. > *Instruction:* Tell the customer their balance and due date, then ask if they want it by SMS. **Instruction-driven** > *Instruction:* Tell the customer their outstanding balance and next due date from the account lookup. Then ask whether they'd like the details by SMS. **Scripted with a behavioral rule** > This call is recorded for quality purposes. Can you confirm the last four digits of your account number? > *Instruction:* Don't continue until the caller confirms. If they decline, offer to transfer them to a person. A behavioral instruction (tone, pacing, a constraint, when to escalate) can sit next to scripted text. A quick test: delete the instruction. If the step still has something complete to say, the instruction is behavioral and can stay. > [!NOTE] > > Use instructions for nuance, not for branching. If the conversation should go in clearly different directions depending on the answer, create a subflow for each answer in the script editor instead of an "if… otherwise…" instruction. ## Scenarios versus script steps Script steps cover the path you expect. Scenarios cover what can come up at any time: questions, objections, and edge cases. When a scenario fires, the agent handles it and then returns to where it was in the script. | Put it in a script step when… | Put it in a scenario when… | | - | - | | It happens in a fixed order on most calls | It can come up at any point, or not at all | | It's part of reaching the goal | It answers a question or objection | | You need the contact's answer to continue | The agent should return to the script afterward | Tips for scenarios: * Title each scenario by the **trigger** (what the contact says), not by the response. "Contact asks about pricing" works better than "Explain pricing." * Start with a direct answer, then hand back with a short question. * Keep each scenario self-contained, because the script resumes afterward. * For long or changing facts, connect a knowledge base and keep the scenario short. See [Scenarios](https://docs.callers.ai/documentation/build-your-agent/agent-scenarios.md). ## Knowledge base or instructions? | Use the knowledge base for | Use instructions for | | - | - | | Facts the agent looks up when asked: policies, product specs, opening hours, FAQs | How the agent behaves: tone, persona, what to avoid, when to escalate | | Content that changes or is long | Short rules that apply on every call | | Material shared by several agents | Rules specific to one agent or one step | Keep knowledge bases focused. Several small, topical knowledge bases retrieve more precisely than one large document. Use clear headings and avoid repeating the same fact in several files. See [Knowledge base](https://docs.callers.ai/documentation/using-callers/knowledge-base.md). ## Agent Instructions and guardrails **Agent Instructions** apply to every step and scenario. A good block covers: * **Persona**: name, company, role, and tone. * **Response style**: short answers, one question per turn, lead with the answer. * **Prohibited behavior**: for example, never read URLs aloud, never promise outcomes, never quote prices that aren't in the knowledge base. * **Escalation**: when to transfer to a person. Keep this block short and don't restate what the script already says. Long, repetitive instructions reduce how closely the agent follows them. For rules that must never be broken, add a [guardrail](https://docs.callers.ai/documentation/build-your-agent/instructions-and-guardrails.md). Guardrails are checked separately from the prompt and can end the conversation, transfer to a person, or regenerate the response. ## Control pacing and interruptions Writing is half of it; timing is the other half. These settings let you tune how the agent delivers what you wrote. | Setting | Where | When to use it | | - | - | - | | **Patience Level** | Agent settings, and per step | How long the agent waits after the contact stops talking. Faster for quick back-and-forth, slower when contacts need time to think or to read out a number. | | **Speak with no interruptions** | Step settings | The agent finishes the step even if the contact talks. Use for disclosures and legally required lines. | | **Only on first play** | Step settings, under **Speak with no interruptions** | Protects the line the first time it plays and allows interruptions if the step repeats. | | **Keypad input** | Agent settings and step settings | Collect digits such as account numbers or menu choices more reliably than speech. Tell the contact exactly which key to press. | > [!WARNING] > > Use uninterruptible steps sparingly. A contact who can't interrupt may talk over the agent or hang up. Keep these steps short. See [Conversation dynamics](https://docs.callers.ai/documentation/voice/conversation-dynamics.md) for patience, interruptions, and no-response settings. ## Test and iterate Prompting is iterative. Plan several rounds of test calls before you launch. **1. Test the happy path** Place a **Test Call** or **Web Call** from the agent header and follow the main path. Listen for long turns, awkward phrasing, and moments where the agent waits too long or too little. **2. Test the edges** Interrupt the agent, ask off-script questions, give unclear answers, stay silent, and say "not interested." Check that the right scenarios fire. **3. Test in the target language** If the agent speaks another language or dialect, test in that language. Pronunciation and phrasing problems rarely show up in translation. **4. Read the transcript and listen to the recording** Transcripts show what was said. Recordings show pacing, interruptions, and pronunciation. Use both. **5. Change one thing at a time** Edit one step or setting, test again, and compare. Changing many things at once makes it hard to see what helped. **6. Review real calls after launch** Use [Insights mode](https://docs.callers.ai/documentation/using-callers/agent-insights.md) to find steps where contacts hang up or interrupt, then rewrite those steps first. ## Checklist > [!TIP] > > Each step is one to three short sentences and ends with one question (unless it ends the call). > [!TIP] > > No URLs, long email addresses, or ambiguous numeric dates are spoken. > [!TIP] > > Every variable has a value source, and sentences still work if optional values are empty. > [!TIP] > > Each step has one source for its words: scripted text or an instruction, not both. > [!TIP] > > Scenarios are titled by trigger and cover your most common questions and objections. > [!TIP] > > Facts live in the knowledge base; behavior lives in instructions; hard limits live in guardrails. > [!TIP] > > Disclosures use **Speak with no interruptions** and are kept short. > [!TIP] > > You've tested interruptions, silence, off-script questions, and the target language. ## Related > **[Steps](https://docs.callers.ai/documentation/build-your-agent/customizing-steps.md)** > > Step types and per-step settings. > **[Instructions and guardrails](https://docs.callers.ai/documentation/build-your-agent/instructions-and-guardrails.md)** > > Agent-wide rules and hard limits. > **[Latency and conversation quality](https://docs.callers.ai/documentation/best-practices/latency-and-conversation-quality.md)** > > Make the agent feel responsive. > **[Testing your agent](https://docs.callers.ai/documentation/build-your-agent/testing-your-agent.md)** > > Test calls, chats, and emails. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.