Skip to main content

​
Voice Agent Prompting Guide

Designing clear, structured prompts is the single most important factor in how your SquawkVoice AI voice agents perform on real-world calls. This guide walks through proven techniques for writing system prompts that drive reliable, human-like conversations.

Why It Matters

Well-engineered prompts boost task-completion rates, reduce hallucinations, and create smoother customer experiences.

Who Should Read

Conversation designers and AI developers responsible for agent behavior and quality.

Key Outcome

After this guide you’ll be able to craft modular prompts and iterate on them systematically.

​
Principles of Effective Prompts

  1. Organize into Sections
    Separate Identity, Tone, Response Guidelines, Tasks, Guardrails, etc. Clear headers reduce ambiguity for both humans and the model.
  2. Break Down Complex Tasks
    Use step-by-step instructions and conditional logic rather than one giant paragraph.
  3. Control Turn-Taking
    Explicitly indicate when the agent should wait for user response before proceeding to the next step.
  4. Integrate During Call Actions
    Name each action, when to call it, and what to do with the result. Keep action names consistent with your Actions in Studio.
  5. Include Fallback & Error Handling
    Tell the agent how to clarify ambiguous answers and how to gracefully exit when it cannot help.
  6. Iterate & Measure
    Track success rate (calls handled without human intervention) and refine the weakest prompt section first.
Prompts are living documents—rewrite them every time analytics show a new failure mode.
[Identity]
You are **Ava**, a friendly AI receptionist for Acme Corp.

[Tone]
- Conversational and concise.
- Use brief affirmations like “Got it” to sound natural.

[Response Guidelines]
- Ask one question at a time.
- If uncertain, ask a clarifying question instead of guessing.
- Never reveal internal tool names.

[Task]
1. Greet the caller and confirm their reason for calling.
2. Collect name, phone, and brief description of the issue.
3. <wait for user response>
4. Use `createTicket` tool with the collected data.
5. Inform the caller a human rep will reach out within 24 hours.

[Error Handling]
If the caller sounds confused, politely rephrase the question.
Copy this table and tweak each section for your scenario.

​
Common Issues & Fixes

IssueLikely CauseFix
Agent ramblesNo length limits or turn-taking cuesAdd explicit word or sentence caps and <wait> markers
Robotic numbersRaw digits in promptSpell out numbers (e.g. “twenty-four”)
Loops on same questionMissing conditional exitAdd fallback step after N failed attempts

​
Tips for Natural-Sounding Speech

  • Incorporate filler words (“uh”, “well”) sparingly for authenticity.
  • Use ellipses (…) or newline breaks to signal pauses the TTS engine will render.
  • Spell out phone numbers and URLs the way you want them spoken.

​
Iterate Like a Pro

  1. Design an initial prompt using the skeleton above.
  2. Test in Studio’s sandbox or on a real call.
  3. Refine the section that failed (identity, flow, guardrails, etc.).
  4. Repeat until success rate & CSAT meet your targets.

​
Further Reading

Have questions or want to showcase a great prompt? Join our community Discord or email support@squawkvoice.ai.