Good agents start with good instructions. This guide walks you through writing a clear, structured prompt for your AI agent - step by step.
Why Your Prompt Matters
Your agent behaves exactly as you instruct it. Vague instructions produce vague behavior. The more specific and structured your prompt, the more consistently your agent performs — across every conversation, every edge case, every user.
The 5-Part Structure
Every agent prompt should have these five sections. Follow them in order.
1. Identity
Define who your agent is. Give it a name, a role, and a clear purpose. This sets the foundation for everything else.
Write it like this:
You are [Name], a [role] for [company]. You help [who] with [what].
You are Maya, a customer support assistant for Bloom Skincare.
You help customers with order questions, returns, and product guidance.
2. Style
Tell your agent how to communicate — tone, length, language level. Be specific. “Be friendly” means nothing. “Keep responses to 2 sentences and never use jargon” does.
Things to specify:
- Response length (e.g. 2–3 sentences max)
- Tone (e.g. warm, professional, direct)
- Whether to use the customer’s name
- How formal or casual the language should be
Example:
Be warm and concise. Keep answers to 2–3 sentences.
Always use the customer's name if you have it. Avoid technical terms.
3. Rules
List what your agent must always do — and must never do. These are your guardrails.
Always do:
- Ask for an order number before looking anything up
- Confirm actions with the user before completing them
- Offer to escalate if you can't resolve the issue
Never do:
- Promise a refund without checking policy first
- Make up information you don't have access to
- Mention competitor products
4. Task
Break the agent’s job into numbered steps. One action per step. This is the core flow the agent follows in every conversation.
Step 1: Greet the user and ask how you can help.
Step 2: Identify what the user needs.
Step 3: Collect their order number if relevant.
Step 4: Resolve the issue or escalate if needed.
Step 5: Close warmly and ask if there's anything else.
If your agent handles multiple use cases (e.g. returns AND product questions), write a separate task flow for each one.
5. Objection Handling
Tell your agent what to do when things don’t go smoothly. Cover at least three situations: confusion, frustration, and out-of-scope requests.
If the user is confused:
Slow down, repeat what you understood, and ask one clarifying question.
If the user is upset:
Apologize, acknowledge the issue without deflecting, and offer to
connect them with a human agent.
If the user asks something out of scope:
Say you can't help with that specifically, and offer to escalate or redirect.
Using Variables
Variables let you personalize conversations automatically. They pull in real data — like a customer’s name or order number — without hardcoding it.
Write variables in double curly braces: {{variable_name}}
Common examples:
| Variable | What it fills in |
|---|
{{customer_name}} | The caller’s actual name |
{{order_number}} | Their specific order ID |
{{company_name}} | Your company name |
{{agent_name}} | The AI agent’s name |
- Greeting:
"Hi {{customer_name}}, thanks for reaching out!"
- Confirmation:
"I've updated your order {{order_number}}."
- Escalation:
"Connecting you now, {{customer_name}}. One moment."
- Closing:
"Thanks for calling {{company_name}}. Have a great day!"
A variable only works if it’s been passed into the conversation or extracted during the call. If the data isn’t available, the agent will say the placeholder literally — like customer_name. Always make sure variable names match exactly what your system sends.
If your agent has access to external tools or APIs, your prompt needs to tell it when to use them — and what to do after.
Write each one as a trigger condition:
If the user asks for order status → use the check_order_status tool
→ confirm the result with the user before closing.
If the user wants a refund → use the escalate_to_human tool
→ do NOT attempt to process the refund yourself.
If the user is upset or asks for a manager → use the escalate_to_human tool
→ immediately, without attempting to resolve further.
List a trigger rule for every tool your agent has access to. Don’t assume the agent will figure out when to use them on its own.
Voice agents don’t always speak numbers, names, and codes the way you expect. Without explicit instructions, an agent might read a phone number as “four hundred fifteen million…” instead of digit by digit - or pronounce an order ID incorrectly.
Tell your agent exactly how to speak each type of data.
Why This Matters
The same value can be spoken in multiple valid ways. Your agent has no way to know which format you want unless you specify it clearly.
| Data Type | Uncontrolled Spoken Output | What You Want |
|---|
| State name | ”C A" | "California” |
| Phone number | ”four hundred fifteen million…" | "(4-1-5) 5-5-5-2-6-7-1” |
| Amount | ”one hundred twenty-five dollars" | "one hundred twenty-five dollars” |
| Order ID | ”$125" | "O-R-D 1-0-2-9-3” |
| ZIP code | ”ninety-four one oh five" | "9-4-1-0-5” |
Always say state names in full —
say "California", not "C A".
Always read phone numbers digit by digit —
say "(4-1-5) 5-5-5-2-6-7-1".
Always read dollar amounts $125 naturally for voice —
say "one hundred twenty-five dollars".
Always read order IDs clearly one character at a time —
say "O-R-D, 1-0-2-9-3".
Always read ZIP codes digit by digit —
say "9-4-1-0-5".
If your voice agent handles phone numbers, addresses, dates, verification codes, or IDs, add a speaking rule for each one. Clear pronunciation rules make conversations much easier for callers to understand.
Common Mistakes to Avoid
These are the most frequent reasons an agent behaves inconsistently or unexpectedly.
- Too vague on tone. “Be professional” is not enough. Say exactly what professional looks like for your brand.
- Missing the unhappy path. Most prompts only describe the ideal flow. Always write what happens when something goes wrong.
- Combining steps. If a step has two actions, split it into two steps.
- Skipping tool triggers. If a tool isn’t mentioned in the instructions, the agent won’t know when to use it.
- Untested variables. Always verify your variables are being passed in correctly before going live.
- No formatting rules for data. If you don’t specify how to handle phone numbers, amounts, state names, or IDs, your agent will pick a format on its own — and it’s often wrong.
