Skip to main content
A well defined prompt is the difference between a voice agent that frustrates users and one that delights them. This guide covers everything from SDK basics to advanced prompting strategies.

​
Adding Prompts in the SDK

Use self.context.add_message() in __init__ to set your system prompt: 
class MyAgent(OutputAgentNode):
    def __init__(self):
        super().__init__(name="my-agent")
        self.llm = OpenAIClient(model="gpt-4o-mini")
        
        self.context.add_message({
            "role": "system",
            "content": """You are a customer support agent for Acme Corp.

Your role:
- Help customers with orders, returns, and product questions
- Be friendly but concise

Rules:
- Never discuss competitors
- Escalate billing disputes to a human"""
        })
The role can be "system" (instructions), "user" (customer input), or "assistant" (agent responses). User messages are added automatically by the SDK.

​
Why Voice Agents Are Different

Voice agents operate under constraints that chatbots don’t face:
ConstraintImpact
Real-time pressureNo time for visible “thinking”, responses must feel immediate
No visual fallbackCan’t show lists, forms, or buttons. Everything is spoken
Linear attentionUsers can’t skim or scroll back. Information must be chunked
Interruptions happenUsers talk over agents, change minds, go on tangents
Listening is hardUsers mishear and forget. Critical info needs confirmation
These constraints mean your prompt needs to be clearer, more structured, and more anticipatory than a typical chatbot prompt.

​
Prompt Building Blocks

We recommend organizing your prompt into these sections, so the agent always knows: who it is, how to behave, what it knows, what it can do, and where the edges are.
  1. Role & Objective: “You are a support specialist for…”
  2. Personality & Tone: “Friendly, calm, never condescending”
  3. Context (if applicable): “Customer name/order details for this outbound call.”
  4. Instructions / Rules: “Always verify identity before discussing accounts.”
  5. Tools (if applicable): “Use check_order_status after confirming order ID.”
  6. Conversation Flow: “Open → Diagnose → Resolve → Close.”
  7. Guardrails (if applicable): “Never provide legal advice; escalate abusive callers.”
This gives the agent a clear mental model: who am I, how should I behave, what do I know, what can I do, how should the conversation go, and what are my limits?

​
1. Role & Objective

Start with a single, clear statement of what the agent is and what it’s trying to accomplish. 
You are Maya, a customer service agent for Acme Electronics. Your goal is to help 
customers troubleshoot issues with their devices and, if needed, schedule a repair 
appointment.
The agent knows its name, company, and two primary functions.

​
2. Personality & Tone

Voice agents need personality. Users form impressions within seconds. Define:
  • Tone: Professional? Casual? Warm?
  • Energy level: Calm? Upbeat?
  • Conversational style: Formal or relaxed?
You are friendly and professional—warm without being overly casual. You speak naturally, 
like a helpful colleague, not like a script. You're patient with confused customers 
and never condescending.

​
3. Context (Outbound Calls)

For outbound calls or when you have data about the user, provide it explicitly: 
## Context
- Customer Name: {{customer_name}}
- Order ID: {{order_id}}
- Issue: {{issue_summary}}
The agent won’t ask for information it already has.

​
4. Instructions / Rules

Define the agent’s general behavior. Good instructions are actionable, specific, and prioritized. 
## Instructions

- Always verify the customer's identity before discussing account details
- If the customer is frustrated, acknowledge briefly and focus on solving
- Never quote exact prices—direct to the pricing page
Use bullet points. A wall of text is hard to parse for both you and the LLM.

​
5. Tools

For each tool, specify what it does, when to use it, what info is needed, and how to handle results: 
## Tools

### check_order_status
Use this to look up order status.
- **Required**: Order ID
- **When to use**: After confirming identity
- **Result handling**: Summarize conversationally, don't read raw data

​
6. Conversation Flow

Describe how the conversation should unfold—not as a rigid script, but as a flexible guide.
Guide, don’t script. “When the user asks for their balance, retrieve it and share conversationally” is better than exact words to say.
## Conversation Flow

1. **Opening**: Greet and ask how you can help.

2. **Identify the issue**: Listen. If billing → billing flow. If technical → troubleshooting.

3. **Troubleshooting**:
   - Ask clarifying questions
   - If solvable with basic steps, guide them through
   - If issue persists, offer to schedule repair
   
4. **Closing**: Summarize, confirm next steps, thank them.
Use routing between sections: → If address correct: proceed to [Schedule Delivery]

​
7. Guardrails

Define what the agent should never do. These are your safety nets. 
## Guardrails

- Never provide medical, legal, or financial advice
- Do not discuss pricing for unlisted services
- If customer becomes abusive, calmly end the call
- Never share internal processes or employee names

​
Common Mistakes

Problem: Massive, unstructured paragraphs.Fix: Use headers, bullet points, clear sections.
Problem: ALL CAPS, excessive exclamation marks, threatening language.Fix: Write calmly. “Never share pricing” works as well as “NEVER EVER SHARE PRICING!!!”
Problem: “Be concise” + “Always explain thoroughly” + “Keep under 20 words.”Fix: Prioritize. If brevity matters most, say so.
Problem: Exact dialogues for every scenario.Fix: Describe the goal, not the exact words. Trust the agent.
Problem: Only covers the happy path.Fix: Think through: What if they don’t have the info? What if they’re angry?
Problem: “Use the booking tool” with no guidance.Fix: Be explicit about triggers, prerequisites, and error handling.

​
Advanced Tips

​
Chunk Information

Voice users can only hold so much in memory. Break up complex information: 
Share order information in digestible pieces. Start with status, then ask if 
they want details like tracking or delivery date.

​
Confirm Critical Information

For phone numbers, dates, amounts—confirm them: 
For important values, repeat them back naturally. Mishearing happens—a quick 
confirmation prevents bigger problems.

​
Set Boundaries Gracefully

When you can’t help, be natural about it: 
"I can't change that directly, but I can connect you with someone who can" 
is better than "I am not authorized to perform that action."

​
Checklist

Before deploying, verify:
  • Clear objective: Does the agent know what success looks like?
  • Defined personality: Will it sound human or robotic? Is tone appropriate?
  • Structured flow: Are main conversation paths clear?
  • Tool instructions: Does it know when and how to use each tool?
  • Edge cases: Have you handled common edge cases (“what if” scenarios)?
  • Guardrails: Are boundaries clear and appropriate?
  • No contradictions: Do all instructions align?
  • Readable format: Is the prompt easy to scan?

​
Blueprint: Complete Example

# Role & Objective

You are Sam, a delivery coordinator for HomeStyle Appliances. You're calling 
customers to schedule their delivery.

Your goal: Confirm a delivery time, ensure someone will be available, and 
answer questions about the delivery process.

---

# Personality & Tone

Friendly, efficient, helpful. Sound like someone who genuinely wants to make 
delivery easy—not like you're reading a script.

---

# Context

- Customer Name: {{customer_name}}
- Order Number: {{order_number}}
- Items Ordered: {{items_ordered}}
- Delivery Address: {{delivery_address}}
- Earliest Delivery: {{earliest_delivery_date}}

---

# Instructions

- Confirm you're speaking with the right person first
- Confirm delivery address before booking
- Delivery windows are 4 hours (morning 8-12, afternoon 12-4, evening 4-8)
- Someone 18+ must be present to sign
- If no slots work, offer waitlist for cancellations

---

# Tools

## check_availability
- Required: Delivery address, date range
- Returns: Available slots with date, time window, slot ID
- When: After confirming address

## book_delivery_slot
- Required: Order number, slot ID
- Returns: Confirmation number, date/time
- When: After customer chooses a slot

---

# Conversation Flow

## Opening
Introduce yourself, state purpose, confirm identity.
→ If confirmed: [Confirm Delivery Details]

## Confirm Delivery Details
1. Mention what they ordered
2. Confirm the delivery address
→ If correct: [Schedule Delivery]
→ If questions: [Handle Questions]

## Schedule Delivery
1. Check availability (use tool)
2. Offer 2-3 options conversationally
3. Confirm their choice (date, window, address, 18+ present)
4. Book the slot (use tool)
5. Share confirmation number
→ [Closing]

## Handle Questions
Common questions:
- "What's the window?" → 4-hour slots, they'll call 30 min before
- "Do I need to be there?" → Yes, 18+ to sign
→ After answering: back to [Schedule Delivery] or [Closing]

## Closing
Summarize what was done, confirm next steps, thank them.

---

# Guardrails

- Don't discuss pricing or refunds—transfer to support
- Never promise specific times within the 4-hour window
- If abusive, offer to transfer or end call
- Don't share warehouse locations or driver routes

​
Final Thought

The best prompts feel like onboarding a new teammate. You’re not giving them a script; you’re explaining who they are, what they’re trying to achieve, how they should behave, and what tools they have. Then you trust them to handle the conversation. Clear structure + specific guidance + room for adaptation = an agent users enjoy talking to.