​

Best Practices

​

Quick Reference

​

Prompt Engineering

​

Structure Your Prompt

You are a customer support agent for Acme Corp.

# Your Role
Help customers with order inquiries, product questions, and basic troubleshooting.

# Conversation Style
- Be friendly and professional
- Use clear, concise language
- Confirm understanding before acting
- Never make promises you can't keep

# Capabilities
You can:
1. Look up order status using the check_order tool
2. Answer product questions using the knowledge base
3. Transfer complex issues to human support

# Constraints
You cannot:
- Process refunds (transfer to billing)
- Change shipping addresses after dispatch
- Make exceptions to return policy

# Example Conversation
Customer: "Where is my order?"
You: "I'll check that for you. Can you provide your order number?"
Customer: "ORDER-12345"
You: [Use check_order tool] "Your order shipped yesterday and will arrive Tuesday."

You are a helpful assistant. Help users with their questions.

​

Define Clear Boundaries

• “If the customer asks for a refund over $500, say: ‘I need to transfer you to our billing team who can help with that.’”
• “For technical issues, first confirm the customer has tried basic troubleshooting before escalating.”

• “Handle customer issues appropriately.”
• “Escalate when necessary.”

​

Use Examples for Complex Behaviors

# Example 1: Happy Path
Customer: "I want to schedule a demo"
You: "Great! What day works best for you?"
Customer: "Next Tuesday"
You: [Check calendar] "I have 2pm and 4pm available. Which works better?"

# Example 2: Handling Objections
Customer: "That's too expensive"
You: "I understand. Many customers save money in the long run because [value proposition]. Would you like to see a cost breakdown?"

# Example 3: Out of Scope
Customer: "Can you fix my computer?"
You: "I specialize in scheduling and product information. For technical support, please visit support.example.com or call 1-800-TECH."

​

Optimize for Voice

# Voice Guidelines
- Keep responses under 3 sentences when possible
- Use natural speech patterns: "I'll check that for you" not "Checking now"
- Avoid spelling out words unless asked
- Use verbal confirmations: "Got it" "Perfect" "Okay"
- Pause naturally with punctuation: periods, commas

Please wait while I process your request...
[Processing]
Here is the information you requested:
• Item 1: Details
• Item 2: Details
• Item 3: Details

​

Handle Edge Cases

If the customer doesn't respond for 5 seconds:
- First time: "Are you still there?"
- Second time: "I didn't catch that. Would you like to continue?"
- Third time: "I'll end the call now. Call back anytime!"

If you can't understand the customer:
- "Sorry, I'm having trouble hearing you. Could you repeat that?"
- Don't guess - always confirm unclear information

If asked about something outside your scope:
- Acknowledge: "That's not something I handle"
- Redirect: "But I can help you with [X, Y, Z]"
- Offer transfer: "Would you like me to connect you with someone who can help?"

​

Test with Real Scenarios

1. Collect 10-20 real conversations from your domain
2. Run test calls with the same questions
3. Compare responses to human agent responses
4. Iterate on edge cases and failure patterns

​

LLM Configuration

​

Model Selection

​

Temperature Tuning

1. Use the same test conversation 5 times at each temperature (0.5, 0.7, 0.9)
2. Measure:
   • Consistency (do responses vary appropriately?)
   • Accuracy (are facts correct?)
   • Tone (does personality match your brand?)
3. Choose the lowest temperature that maintains natural conversation

​

Max Tokens Strategy

• Short answers (100-150 tokens): “Your order ships tomorrow” - Good for quick lookups
• Medium responses (200-300 tokens): Explanations with 2-3 key points - Most voice conversations
• Long responses (400-500 tokens): Detailed troubleshooting steps - Only when necessary
• Avoid 1000+ tokens: Voice users lose attention after 30-45 seconds

​

Service Tier Priority (OpenAI Only)

• Priority Tier (Toggle): When enabled, sets vendorSpecificOptions.service_tier = "priority" for lower latency and higher throughput
• Default (Priority Off): Standard latency, lower cost

​

Voice and Speech Optimization

​

TTS Provider Selection

​

Voice Speed Guidelines

​

Speech Recognition Best Practices

• Ask confirmation questions: “Did you say ECHO-1234?”
• Spell out ambiguous information: “That’s E as in Echo, C as in Charlie…”
• Use verbal checksums: “Your confirmation code is 1-2-3-4. That’s one, two, three, four.”

# In your system prompt
If you're unsure what the customer said:
- Ask for clarification: "I heard [X]. Is that correct?"
- Offer alternatives: "Did you say 'cancel' or 'change'?"
- Request spelling for important data: "Could you spell your last name?"

​

Conversation Design

​

Conversation Flow Patterns

Agent: "Hi! This is [Agent Name] from [Company]. How can I help you today?"
[Customer states intent]
Agent: "I can help with that. Let me [action]."
[Perform action with tool/lookup]
Agent: "Done! Is there anything else I can help you with?"
[If no] "Great! Have a wonderful day."

Agent: "I'll update your shipping address. What's the new address?"
Customer: [Provides address]
Agent: "Just to confirm: [repeats address]. Is that correct?"
Customer: "Yes"
Agent: [Updates address] "Perfect! Your address is updated."

Agent: "What brings you in today?"
Customer: [Describes problem]
Agent: "Got it. Have you tried [basic step]?"
[Determine complexity]
Agent: "This needs our specialist team. I'll transfer you now."

​

Turn-Taking and Interruptions

# In your prompt
- Let customers interrupt you at any time
- If interrupted, stop immediately and listen
- Don't repeat what you were saying unless asked
- Acknowledge the interruption: "Sure" or "Go ahead"

# Bad (voice only, no turn-taking)
Agent: "Your order contains item A, item B, and item C. Item A ships from warehouse 1 and should arrive Monday. Item B ships from warehouse 2 and should arrive Wednesday. Item C is backordered and will ship next week. Your total is $99.99. Shipping is free. Tracking numbers are..."

# Good (chunked with pauses)
Agent: "Your order has three items. Two ship this week, one is backordered."
[Pause for reaction]
Agent: "Would you like the tracking details?"

​

Error Recovery

Customer: [Says something unclear]
Agent: "I didn't quite catch that. Could you repeat?"
Customer: [Still unclear]
Agent: "Let me offer some options: Are you calling about [A], [B], or [C]?"

# If tool call fails
Agent: "I'm having trouble looking that up right now. Let me try a different way."
[Try alternative]
Agent: "I apologize, our system is slow today. Would you like me to email this to you instead?"

Customer: "Can you help me with [out of scope]?"
Agent: "I don't handle that, but I can transfer you to [department] who can help. Would you like that?"

​

Testing Strategies

​

Pre-Launch Testing Checklist

• Simple request with immediate answer
• Multi-step conversation (3+ turns)
• Tool/function call succeeds
• Transfer to human works
• End conversation naturally

• Silence for 10+ seconds
• Customer interrupts mid-sentence
• Background noise (music, traffic, talking)
• Customer speaks very fast or slow
• Repeated misrecognition of same word
• Request for something out of scope
• Customer is angry or frustrated
• Multiple requests in one turn
• Customer changes mind mid-conversation

• Tool call times out
• Tool returns error
• Invalid data format
• Webhook doesn’t respond
• Network interruption
• Customer hangs up mid-turn

​

Load Testing

1. Start small: 5-10 concurrent calls
2. Measure: Latency, error rate, call quality
3. Increase gradually: Double concurrency each round
4. Monitor: Watch for degradation patterns
5. Set limits: Configure concurrency caps based on results

​

A/B Testing

• Same agent, different prompts
• Same prompt, different temperatures
• Same config, different voices

• Call success rate (user achieved goal)
• Average call duration
• Tool call accuracy
• User satisfaction (if post-call analysis enabled)
• Transfer rate (lower is often better)

​

Performance Optimization

​

Latency Reduction

• LLM: gpt-4.1-mini, llama-3.1-8b-instant, grok-3-mini
• TTS: Cartesia (fastest), Dasha (fast), ElevenLabs (slower but high quality)
• ASR: Auto-selection handles this

• Shorter prompts = faster processing
• Remove redundant instructions
• Use tools instead of long context

• Max tokens: 150-300 for voice
• Concise system prompts
• Discourage verbose responses

​

Cost Optimization

• deepseek-r1 - 30x cheaper than GPT-4, similar quality
• llama-3.1-8b-instant - Very low cost per token
• gpt-4.1-nano - OpenAI’s most cost-effective

• Shorter system prompts (remove examples if not needed)
• Lower max tokens (100-200 for simple agents)
• Use tools for data lookup (don’t put data in prompt)

• Reuse common prompt segments
• Cache knowledge base embeddings
• Minimize unique per-call prompt variations

​

Quality Monitoring

• Success rate (did user achieve goal?)
• Call duration (outliers indicate issues)
• Tool call accuracy
• Number of clarification requests

• Daily/weekly call volume trends
• Error rate by error type
• User satisfaction scores (via post-call analysis)
• Transfer rate (escalations to human)

• Error rate > 5% in 1 hour
• Average call duration > 2x baseline
• Success rate < 70%
• Concurrency limit reached

​

Common Anti-Patterns

​

Overly Complex Prompts

You are a customer service representative with 15 years of experience working in telecommunications. You value customer satisfaction above all else and always go the extra mile. You should be empathetic, understanding, patient, kind, professional, courteous, and helpful. Always maintain a positive attitude even when customers are upset. Use active listening techniques. Employ de-escalation strategies when needed. Follow our 12-step customer service framework...

[Continues for 500+ lines]

You are a friendly customer support agent for TelecomCo.

Help customers with billing questions and plan changes.

Tone: Professional but conversational
Approach: Listen, confirm, act
Escalate: Billing issues over $100, technical problems

​

Ignoring Voice-Specific Design

• Verbal lists: “I have three options for you. First, second, third.”
• No visual references: “I’ll send you a link” not “Click the button below”
• Spell out important codes: “Your code is A-B-C-1-2-3. That’s Alpha Bravo Charlie one two three.”

​

Not Testing Edge Cases

• Test with real background noise
• Test with fast/slow speakers
• Test interruptions and silence
• Test unclear requests

​

Over-Engineering on Day 1

• Start with minimum viable agent (basic prompt + 1-2 tools)
• Deploy to limited beta users
• Iterate based on real conversation data
• Add complexity only when needed

​

Ignoring Metrics

• Daily review of key metrics (success rate, errors)
• Weekly review of conversation samples
• Monthly prompt optimization based on patterns
• Set up automated alerts for anomalies

​

Production Deployment Checklist

• Test with 10+ users outside your team
• Review 50+ test conversation transcripts
• Set up monitoring dashboards
• Configure error alerts
• Monitor concurrency limits (contact support if you need a higher cap)
• Test failure scenarios (timeouts, errors)
• Verify webhook endpoints are live
• Test call transfers work
• Confirm business hours are correct
• Set up post-call analysis (optional)

• Start with small percentage of traffic (10-20%)
• Monitor metrics every hour
• Have human fallback ready
• Quick prompt iteration capability
• Support team briefed on escalation

• Daily metric reviews
• Sample conversation reviews
• Collect user feedback
• Adjust prompt based on findings
• Gradually increase traffic

• Weekly performance reviews
• Monthly prompt optimization
• Quarterly voice/model updates
• Regular A/B testing

​

Next Steps

• Configuration: LLM Configuration, Voice & Speech
• Testing: Testing Overview, Dashboard Testing
• Advanced: Advanced Features, Post-Call Analysis
• Deployment: Production Checklist

​

API Cross-Refs

• POST /api/v1/agents
• PUT /api/v1/agents/
• GET /api/v1/voice
• POST /api/v1/voice/synthesize
• GET /api/v1/calls/statistics/statuses