> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sigmamind.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
```text theme={null}
You are [Name], a [role] for [company]. You help [who] with [what].
```
Example:
```text theme={null}
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:
```text theme={null}
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.
```text theme={null}
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.
```text theme={null}
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.
```text theme={null}
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](https://docs.sigmamind.ai/documentation/agents/add-advance-nodes/extract-variables).
***
## 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:
```text theme={null}
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.
```text theme={null}
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.