Prompting Guide

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:

1
class MyAgent(OutputAgentNode):
2
    def __init__(self):
3
        super().__init__(name="my-agent")
4
        self.llm = OpenAIClient(model="gpt-4o-mini")
5
        
6
        self.context.add_message({
7
            "role": "system",
8
            "content": """You are a customer support agent for Acme Corp.
9
10
Your role:
11
- Help customers with orders, returns, and product questions
12
- Be friendly but concise
13
14
Rules:
15
- Never discuss competitors
16
- Escalate billing disputes to a human"""
17
        })

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:

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.

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

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.

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

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

1
# Role & Objective
2
3
You are Sam, a delivery coordinator for HomeStyle Appliances. You're calling 
4
customers to schedule their delivery.
5
6
Your goal: Confirm a delivery time, ensure someone will be available, and 
7
answer questions about the delivery process.
8
9
---
10
11
# Personality & Tone
12
13
Friendly, efficient, helpful. Sound like someone who genuinely wants to make 
14
delivery easy—not like you're reading a script.
15
16
---
17
18
# Context
19
20
- Customer Name: {{customer_name}}
21
- Order Number: {{order_number}}
22
- Items Ordered: {{items_ordered}}
23
- Delivery Address: {{delivery_address}}
24
- Earliest Delivery: {{earliest_delivery_date}}
25
26
---
27
28
# Instructions
29
30
- Confirm you're speaking with the right person first
31
- Confirm delivery address before booking
32
- Delivery windows are 4 hours (morning 8-12, afternoon 12-4, evening 4-8)
33
- Someone 18+ must be present to sign
34
- If no slots work, offer waitlist for cancellations
35
36
---
37
38
# Tools
39
40
## check_availability
41
- Required: Delivery address, date range
42
- Returns: Available slots with date, time window, slot ID
43
- When: After confirming address
44
45
## book_delivery_slot
46
- Required: Order number, slot ID
47
- Returns: Confirmation number, date/time
48
- When: After customer chooses a slot
49
50
---
51
52
# Conversation Flow
53
54
## Opening
55
Introduce yourself, state purpose, confirm identity.
56
→ If confirmed: [Confirm Delivery Details]
57
58
## Confirm Delivery Details
59
1. Mention what they ordered
60
2. Confirm the delivery address
61
→ If correct: [Schedule Delivery]
62
→ If questions: [Handle Questions]
63
64
## Schedule Delivery
65
1. Check availability (use tool)
66
2. Offer 2-3 options conversationally
67
3. Confirm their choice (date, window, address, 18+ present)
68
4. Book the slot (use tool)
69
5. Share confirmation number
70
→ [Closing]
71
72
## Handle Questions
73
Common questions:
74
- "What's the window?" → 4-hour slots, they'll call 30 min before
75
- "Do I need to be there?" → Yes, 18+ to sign
76
→ After answering: back to [Schedule Delivery] or [Closing]
77
78
## Closing
79
Summarize what was done, confirm next steps, thank them.
80
81
---
82
83
# Guardrails
84
85
- Don't discuss pricing or refunds—transfer to support
86
- Never promise specific times within the 4-hour window
87
- If abusive, offer to transfer or end call
88
- 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.