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. Say it in plain words, such as “Wait for the caller’s answer before continuing.”
  4. Integrate In-conversation Actions
    Name each action, when to call it, and what to do with the result. Keep action names consistent with your In-conversation Actions in Studio. The easiest way is to insert them from the {{ picker, as described in Reference Actions in Your Guidelines.
  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.
Copy this skeleton and tweak each section for your scenario.
Write turn-taking cues and other instructions as plain sentences, not as angle-bracket tags. The Guidelines editor doesn’t keep tags such as <wait> or <role>: when you paste them in, the tags are removed and only the text between them is kept, and a < or > you type yourself is saved as the text &lt; or &gt;.

Reference Actions in Your Guidelines

In the Guidelines editor (open your agent’s Guidelines card), type {{ to open a picker with your variables and an ACTIONS group. Use its search box to narrow the list. Choose an action and Studio inserts a highlighted reference such as {{action.createTicket}}. To use a variable instead, pick it from the same list (see Writing Guidelines).
  • What the picker offers: your agent’s In-conversation Actions, plus two built-in actions: end_conversation, which ends the conversation, and intent_to_transfer, which hands the conversation to a person. Pre- and Post-conversation Actions aren’t listed, because the agent doesn’t call them during the conversation.
  • Renames are safe: a reference follows the action, so if you rename the action, the reference shows the new name. An action name typed as plain text doesn’t follow a rename.
  • On a call or in chat: the reference is replaced with the action’s name, so Use {{action.createTicket}} with the details you collected. reaches the agent as “Use createTicket with the details you collected.” If you delete an action, remove its reference from your Guidelines. A reference to an action that no longer exists is left blank.
  • On email: a reference is left blank, because the action’s name isn’t filled in on email replies. Your Guidelines are shared across channels, so if your agent also answers email, write the action’s name as plain text in the sentence, as in “Use createTicket with the details you collected.”
  • Open an action: hold Ctrl (Cmd on Mac) and click a reference to open that action. The two built-in actions don’t open.
See In-conversation Actions for how to create actions and for the rules on action names.

Common Issues & Fixes

Tips for Natural-Sounding Speech

  • Incorporate filler words (“uh”, “well”) sparingly for authenticity.
  • Use ellipses (…) to hint at a pause. Line breaks don’t add a pause, because each one is read as a single space.
  • 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 with Talk (a test call from your browser) or Chat (a test chat) on the agent’s page, or on a real call. Talk and Chat always use your latest edits, while a real call uses the published version once the agent has one.
  3. Refine the section that failed (identity, flow, guardrails, etc.).
  4. Publish the refined prompt once it tests well, if the agent has been published, so real calls get it. An agent you haven’t published already runs your latest edits on real calls. See Publishing Your Agent.
  5. 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.