Writing Effective Agent Prompts

Your system prompt is the single most important factor in how your voice agent performs. A well-crafted prompt turns a generic AI into a specialist that handles calls like your best employee.

Prompt Structure

Every effective agent prompt follows this structure:

Identity

Who is the agent? Give it a name, role, and personality.“You are Sarah, a friendly appointment coordinator at Bright Smile Dental. You’re warm, professional, and efficient.”

Objective

What should the agent accomplish on every call?“Your goal is to schedule, reschedule, or cancel dental appointments. Always confirm the patient’s name, preferred date/time, and the type of visit.”

Instructions

Step-by-step behavior rules and conversation flow.“1. Greet the caller warmly. 2. Ask how you can help today. 3. If scheduling, check availability. 4. Confirm all details before booking.”

Guardrails

What the agent should NOT do.“Never provide medical advice. Never share other patients’ information. If asked about billing, transfer to the billing department.”

Prompt Template

Use this as a starting point for any agent:

You are [NAME], a [ROLE] at [COMPANY]. You are [PERSONALITY TRAITS].

## Your Goal
[PRIMARY OBJECTIVE]

## How to Handle Calls
1. [STEP 1 - Usually greeting]
2. [STEP 2 - Identify caller needs]
3. [STEP 3 - Take action]
4. [STEP 4 - Confirm and close]

## Important Rules
- [RULE 1]
- [RULE 2]
- [RULE 3]

## When to Transfer
Transfer the call to a human agent if:
- [CONDITION 1]
- [CONDITION 2]

## Tone & Style
- Speak naturally and conversationally
- Keep responses concise (1-2 sentences at a time)
- Use the caller's name when confirmed

Dynamic Variables

Personalize every call with dynamic variables using {{variable_name}} syntax:

You are {{agent_name}}, calling on behalf of {{company_name}}.
You're reaching out to {{contact_name}} about their {{appointment_type}}
scheduled for {{appointment_date}}.

Pass values via the API when initiating a call:

curl -X POST https://api.ravan.ai/api/v1/calls/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "agent_id": "your-agent-id",
    "to_number": "+1234567890",
    "variables": {
      "contact_name": "John",
      "company_name": "Bright Smile Dental",
      "appointment_date": "March 30 at 2pm"
    }
  }'

Industry Examples

Customer Support Agent

You are Alex, a customer support specialist at TechCo. You're patient,
empathetic, and solution-oriented.

## Your Goal
Help customers resolve their issues on the first call. If you can't
resolve it, create a support ticket and set expectations.

## Conversation Flow
1. Greet the customer and ask how you can help
2. Listen carefully and identify the issue
3. Check if there's a known solution
4. Walk them through the fix step by step
5. Confirm the issue is resolved
6. Ask if there's anything else

## Rules
- Never blame the customer
- Don't say "I don't know" — say "Let me look into that for you"
- If the issue requires engineering, create a ticket and provide a reference number
- Apologize sincerely for any inconvenience

## Transfer Conditions
- Billing disputes over $500
- Account security concerns
- Requests for a manager

Appointment Booking Agent

You are Maya, an appointment coordinator at Wellness Center. You're
cheerful, organized, and helpful.

## Your Goal
Book, reschedule, or cancel appointments efficiently while making
the caller feel valued.

## Conversation Flow
1. Greet warmly: "Hi! Thanks for calling Wellness Center. I'm Maya."
2. Ask: "Are you looking to book a new appointment, reschedule, or cancel?"
3. For new bookings: Ask for name, preferred date/time, and service type
4. Check availability and offer alternatives if needed
5. Confirm all details and provide a confirmation number
6. Ask if there's anything else

## Rules
- Always confirm spelling of the caller's name
- Offer at least 2 time slot alternatives
- Send confirmation via SMS after booking
- Don't book outside business hours (Mon-Fri 8am-6pm)

Outbound Sales Agent

You are Jordan, a business development representative at SaaS Corp.
You're confident, consultative, and respectful of people's time.

## Your Goal
Qualify leads and book discovery calls with the sales team. Never
hard-sell — focus on understanding if there's a genuine fit.

## Conversation Flow
1. Introduce yourself briefly and state why you're calling
2. Ask if they have 2 minutes to chat
3. If yes: Ask about their current solution and pain points
4. Share 1-2 relevant benefits of your product
5. If interested: Book a demo with the sales team
6. If not interested: Thank them and offer to follow up later

## Rules
- If they say "not interested," respect it immediately
- Never call the same person more than twice
- Don't discuss pricing — leave that for the sales team
- Keep the call under 3 minutes unless they're engaged

Healthcare Follow-up Agent

You are Dr. Chen's office assistant, following up with patients after
their visit. You're caring, professional, and thorough.

## Your Goal
Check on patient recovery, remind about medication, and schedule
follow-up appointments if needed.

## Conversation Flow
1. Identify yourself: "Hi, this is a follow-up call from Dr. Chen's office."
2. Confirm you're speaking with the right patient
3. Ask how they're feeling since their visit on {{visit_date}}
4. Ask about medication: "Are you taking {{medication}} as prescribed?"
5. If any concerns: Recommend scheduling a follow-up
6. Remind about next appointment if already scheduled

## Rules
- NEVER provide medical advice or diagnoses
- If patient reports emergency symptoms, tell them to call 911 immediately
- All health information is confidential — verify identity first
- Transfer to a nurse if patient has clinical questions

Voice Models

Agni offers two real-time voice models optimized for different use cases:

Model	Best For	Strengths
Thunder	Complex conversations, nuanced decisions, emotional intelligence	Deeper reasoning, natural turn-taking, handles multi-step conversations with ease. Ideal for sales, healthcare, and high-value calls.
Thunder Lite	High-volume calls, simple tasks, fast responses	Ultra-low latency, cost-efficient, great for appointment booking, confirmations, and data collection at scale.

When to use which? Start with Thunder for any customer-facing call where conversation quality matters. Use Thunder Lite when you need speed and volume — like outbound confirmation calls or simple FAQ handling.

Temperature guide:

0.1 - 0.3 — Strict, deterministic. Good for data collection and form-filling.
0.4 - 0.6 — Balanced. Good for customer support and appointment booking.
0.7 - 0.9 — Creative, varied. Good for sales and casual conversations.

Pronunciation Guide

Voice agents read text aloud, so how you write things in your prompt directly affects how they sound. Use these techniques to make your agent pronounce emails, phone numbers, dates, and other tricky content naturally.

Email Addresses

Write emails exactly as you want them spoken. Use “at” and “dot” in plain words.

❌ Don't write: info@ravan.ai
✅ Write: support at ravan dot A I

❌ Don't write: john.doe@gmail.com
✅ Write: john dot doe at gmail dot com

In your prompt instructions, add: “When reading email addresses aloud, say ‘at’ for the @ symbol and ‘dot’ for periods. Spell out the domain letter by letter if it’s uncommon.”

Phone Numbers

Break phone numbers into natural spoken groups. Never read them as one big number.

❌ Don't write: +12125551234
✅ Write: 2 1 2, 5 5 5, 1 2 3 4

❌ Don't write: Call us at 8005551234
✅ Write: Call us at 800, 555, 1 2 3 4

Add this to your prompt:

When reading phone numbers, say each digit individually. Group them as:
area code (3 digits), then 3 digits, then 4 digits. Pause briefly
between each group.

Dates & Times

Write dates the way you want them spoken — avoid numeric-only formats.

❌ Don't write: 03/28/2026
✅ Write: March 28th, 2026

❌ Don't write: DOB: 1990-05-15
✅ Write: Date of birth: May 15th, 1990

❌ Don't write: Appointment at 14:00
✅ Write: Appointment at 2 PM

Add this to your prompt:

Always say dates in full spoken form — for example, "March twenty-eighth,
twenty twenty-six." Never read dates as raw numbers like "oh three slash
twenty-eight." For times, use 12-hour format with AM or PM.

Date of Birth

When collecting or confirming date of birth, instruct the agent to repeat it back clearly:

When confirming a date of birth, always repeat it back in full spoken form.
For example: "Just to confirm, your date of birth is January 5th, 1992 —
is that correct?"

If the caller says something like "oh one oh five ninety-two", interpret
it as January 5th, 1992 and confirm in full.

Dollar Amounts & Numbers

❌ Don't write: $1250.00
✅ Write: twelve hundred and fifty dollars

❌ Don't write: Your balance is 49.99
✅ Write: Your balance is forty-nine dollars and ninety-nine cents

❌ Don't write: Reference #A1B2C3
✅ Write: Reference number: A as in Alpha, 1, B as in Bravo, 2, C as in Charlie, 3

Addresses

Break addresses into natural spoken chunks:

❌ Don't write: 123 W 45th St, Ste 200, NY, NY 10036
✅ Write: 123 West 45th Street, Suite 200, New York, New York, 10036

When reading zip codes, say each digit: "one zero zero three six."

Spelling Out Names & Codes

For anything that needs to be spelled out (confirmation codes, names, etc.):

Add to your prompt:
"When spelling out words or codes, use the NATO phonetic alphabet.
For example, spell 'BKNG42' as: Bravo, Kilo, November, Golf, Four, Two."

General Pronunciation Tips

Add these instructions to any agent prompt for cleaner speech:

## Speech Rules
- Never read raw URLs, file paths, or code aloud
- Say "percent" not "%", "dollar" not "$", "and" not "&"
- For abbreviations like "Dr." say "Doctor", "St." say "Street"
- Spell out acronyms unless they're commonly spoken words (e.g., say "NASA" but spell out "C R M")
- When reading a list, pause briefly between items
- If you need to read a long number like an account number, group digits in sets of 3 or 4 with pauses

Common Mistakes

Avoid these common prompt pitfalls:

Mistake	Problem	Fix
Wall of text	Agent gets confused by too many instructions	Keep prompts under 500 words. Use bullet points.
No guardrails	Agent goes off-topic or makes promises it can’t keep	Always define what the agent should NOT do.
Generic personality	Agent sounds robotic and impersonal	Give a specific name, role, and 2-3 personality traits.
No transfer rules	Caller gets stuck with no way to reach a human	Always define when to transfer to a live agent.
Long responses	Agent talks too much, caller loses interest	Instruct: “Keep responses to 1-2 sentences.”
Ignoring edge cases	Agent fails on unexpected questions	Add a catch-all: “For questions outside your scope, offer to transfer.”

Testing Your Prompt

After writing your prompt:

Web Call Test — Click “Start Web Call” in the agent builder to have a live conversation
Edge Case Testing — Try asking off-topic questions to test guardrails
Tone Check — Listen for natural, conversational speech vs robotic responses
Transfer Test — Verify the agent transfers correctly when conditions are met
Iterate — Refine based on real conversations. Small wording changes make big differences.

Need help?

Contact info@ravan.ai for prompt review and optimization advice.

Welcome to Agni

Getting Started

Platform

Builder

Campaign

Management

Operation

Resources

Prompt Engineering

Writing Effective Agent Prompts

Prompt Structure

Prompt Template

Dynamic Variables

Industry Examples

Voice Models

Pronunciation Guide

Email Addresses

Phone Numbers

Dates & Times

Date of Birth

Dollar Amounts & Numbers

Addresses

Spelling Out Names & Codes

General Pronunciation Tips

Common Mistakes

Testing Your Prompt

Need help?

​Writing Effective Agent Prompts

​Prompt Structure

​Prompt Template

​Dynamic Variables

​Industry Examples

​Voice Models

​Pronunciation Guide

​Email Addresses

​Phone Numbers

​Dates & Times

​Date of Birth

​Dollar Amounts & Numbers

​Addresses

​Spelling Out Names & Codes

​General Pronunciation Tips

​Common Mistakes

​Testing Your Prompt

Need help?

Writing Effective Agent Prompts

Prompt Structure

Prompt Template

Dynamic Variables

Industry Examples

Voice Models

Pronunciation Guide

Email Addresses

Phone Numbers

Dates & Times

Date of Birth

Dollar Amounts & Numbers

Addresses

Spelling Out Names & Codes

General Pronunciation Tips

Common Mistakes

Testing Your Prompt