> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squawkvoice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompting Guide

> Best practices for crafting effective system prompts for voice AI agents

# 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.

<Columns cols={3}>
  <Card title="Why It Matters" icon="circle-check">
    Well-engineered prompts boost task-completion rates, reduce hallucinations, and create smoother customer experiences.
  </Card>

  <Card title="Who Should Read" icon="users">
    Conversation designers and AI developers responsible for agent behavior and quality.
  </Card>

  <Card title="Key Outcome" icon="bullseye">
    After this guide you’ll be able to craft modular prompts and iterate on them systematically.
  </Card>
</Columns>

## 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.

<Note>
  Prompts are living documents—rewrite them every time analytics show a new failure mode.
</Note>

## Recommended Prompt Skeleton

```text theme={null}
[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

| Issue                  | Likely Cause                         | Fix                                                     |
| ---------------------- | ------------------------------------ | ------------------------------------------------------- |
| Agent rambles          | No length limits or turn-taking cues | Add explicit word or sentence caps and `<wait>` markers |
| Robotic numbers        | Raw digits in prompt                 | Spell out numbers (e.g. "twenty-four")                  |
| Loops on same question | Missing conditional exit             | Add 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

* [LearnPrompting.org](https://learnprompting.org) – Open-source prompt engineering curriculum
* [OpenAI Prompt Engineering](https://platform.openai.com/docs/guides/gpt) – Official guidelines
* [Prompting Guide (Hume)](https://dev.hume.ai/docs/empathic-voice-interface-evi/prompting) – Voice-specific techniques

<Note>
  Have questions or want to showcase a great prompt? Join our community Discord or email [support@squawkvoice.ai](mailto:support@squawkvoice.ai).
</Note>