Prompt Engineering Guide

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].

Example:

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

Where to use them:

• 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.

For a full variable reference, see the Extract Variables Guide.

---

Connecting Tools

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.

---

Controlling How Data Is Formatted

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”

How to Write Voice Formatting Rules

Add speaking instructions to your Style or Rules section. Be explicit — say exactly how the agent should read values out loud.

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.