*** title: Prompting Guide sidebarTitle: Prompting description: Write prompts that make your voice agent sound natural, stay on track, and get work done. --------------------- For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.smallest.ai/atoms/developer-guide/build/agents/llm/llms.txt. For full documentation content, see https://docs.smallest.ai/atoms/developer-guide/build/agents/llm/llms-full.txt. A well defined prompt is the difference between a voice agent that frustrates users and one that delights them. This guide covers everything from SDK basics to advanced prompting strategies. ## Adding Prompts in the SDK Use `self.context.add_message()` in `__init__` to set your system prompt: ```python class MyAgent(OutputAgentNode): def __init__(self): super().__init__(name="my-agent") self.llm = OpenAIClient(model="gpt-4o-mini") self.context.add_message({ "role": "system", "content": """You are a customer support agent for Acme Corp. Your role: - Help customers with orders, returns, and product questions - Be friendly but concise Rules: - Never discuss competitors - Escalate billing disputes to a human""" }) ``` The `role` can be `"system"` (instructions), `"user"` (customer input), or `"assistant"` (agent responses). User messages are added automatically by the SDK. *** ## Why Voice Agents Are Different Voice agents operate under constraints that chatbots don't face: | Constraint | Impact | | ------------------------ | ------------------------------------------------------------- | | **Real-time pressure** | No time for visible "thinking", responses must feel immediate | | **No visual fallback** | Can't show lists, forms, or buttons. Everything is spoken | | **Linear attention** | Users can't skim or scroll back. Information must be chunked | | **Interruptions happen** | Users talk over agents, change minds, go on tangents | | **Listening is hard** | Users mishear and forget. Critical info needs confirmation | These constraints mean your prompt needs to be clearer, more structured, and more anticipatory than a typical chatbot prompt. *** ## Prompt Building Blocks We recommend organizing your prompt into these sections, so the agent always knows: who it is, how to behave, what it knows, what it can do, and where the edges are. 1. **Role & Objective**: "You are a support specialist for…" 2. **Personality & Tone**: "Friendly, calm, never condescending" 3. **Context (if applicable)**: "Customer name/order details for this outbound call." 4. **Instructions / Rules**: "Always verify identity before discussing accounts." 5. **Tools (if applicable)**: "Use `check_order_status` after confirming order ID." 6. **Conversation Flow**: "Open → Diagnose → Resolve → Close." 7. **Guardrails (if applicable)**: "Never provide legal advice; escalate abusive callers." This gives the agent a clear mental model: *who am I, how should I behave, what do I know, what can I do, how should the conversation go, and what are my limits?* *** ### 1. Role & Objective Start with a single, clear statement of what the agent is and what it's trying to accomplish. ``` You are Maya, a customer service agent for Acme Electronics. Your goal is to help customers troubleshoot issues with their devices and, if needed, schedule a repair appointment. ``` The agent knows its name, company, and two primary functions. ``` Help the customer. Be useful. ``` Vague—no direction on *how* to help or what success looks like. *** ### 2. Personality & Tone Voice agents need personality. Users form impressions within seconds. Define: * **Tone**: Professional? Casual? Warm? * **Energy level**: Calm? Upbeat? * **Conversational style**: Formal or relaxed? ``` You are friendly and professional—warm without being overly casual. You speak naturally, like a helpful colleague, not like a script. You're patient with confused customers and never condescending. ``` *** ### 3. Context (Outbound Calls) For outbound calls or when you have data about the user, provide it explicitly: ``` ## Context - Customer Name: {{customer_name}} - Order ID: {{order_id}} - Issue: {{issue_summary}} ``` The agent won't ask for information it already has. *** ### 4. Instructions / Rules Define the agent's general behavior. Good instructions are **actionable**, **specific**, and **prioritized**. ``` ## Instructions - Always verify the customer's identity before discussing account details - If the customer is frustrated, acknowledge briefly and focus on solving - Never quote exact prices—direct to the pricing page ``` Use bullet points. A wall of text is hard to parse for both you and the LLM. *** ### 5. Tools For each tool, specify what it does, when to use it, what info is needed, and how to handle results: ``` ## Tools ### check_order_status Use this to look up order status. - **Required**: Order ID - **When to use**: After confirming identity - **Result handling**: Summarize conversationally, don't read raw data ``` *** ### 6. Conversation Flow Describe how the conversation should unfold—not as a rigid script, but as a flexible guide. **Guide, don't script.** "When the user asks for their balance, retrieve it and share conversationally" is better than exact words to say. ``` ## Conversation Flow 1. **Opening**: Greet and ask how you can help. 2. **Identify the issue**: Listen. If billing → billing flow. If technical → troubleshooting. 3. **Troubleshooting**: - Ask clarifying questions - If solvable with basic steps, guide them through - If issue persists, offer to schedule repair 4. **Closing**: Summarize, confirm next steps, thank them. ``` Use routing between sections: `→ If address correct: proceed to [Schedule Delivery]` *** ### 7. Guardrails Define what the agent should **never** do. These are your safety nets. ``` ## Guardrails - Never provide medical, legal, or financial advice - Do not discuss pricing for unlisted services - If customer becomes abusive, calmly end the call - Never share internal processes or employee names ``` *** ## Common Mistakes **Problem:** Massive, unstructured paragraphs. **Fix:** Use headers, bullet points, clear sections. **Problem:** ALL CAPS, excessive exclamation marks, threatening language. **Fix:** Write calmly. "Never share pricing" works as well as "NEVER EVER SHARE PRICING!!!" **Problem:** "Be concise" + "Always explain thoroughly" + "Keep under 20 words." **Fix:** Prioritize. If brevity matters most, say so. **Problem:** Exact dialogues for every scenario. **Fix:** Describe the *goal*, not the exact words. Trust the agent. **Problem:** Only covers the happy path. **Fix:** Think through: What if they don't have the info? What if they're angry? **Problem:** "Use the booking tool" with no guidance. **Fix:** Be explicit about triggers, prerequisites, and error handling. *** ## Advanced Tips ### Chunk Information Voice users can only hold so much in memory. Break up complex information: ``` Share order information in digestible pieces. Start with status, then ask if they want details like tracking or delivery date. ``` ### Confirm Critical Information For phone numbers, dates, amounts—confirm them: ``` For important values, repeat them back naturally. Mishearing happens—a quick confirmation prevents bigger problems. ``` ### Set Boundaries Gracefully When you can't help, be natural about it: ``` "I can't change that directly, but I can connect you with someone who can" is better than "I am not authorized to perform that action." ``` *** ## Checklist Before deploying, verify: * **Clear objective**: Does the agent know what success looks like? * **Defined personality**: Will it sound human or robotic? Is tone appropriate? * **Structured flow**: Are main conversation paths clear? * **Tool instructions**: Does it know when and how to use each tool? * **Edge cases**: Have you handled common edge cases (“what if” scenarios)? * **Guardrails**: Are boundaries clear and appropriate? * **No contradictions**: Do all instructions align? * **Readable format**: Is the prompt easy to scan? *** ## Blueprint: Complete Example ```markdown # Role & Objective You are Sam, a delivery coordinator for HomeStyle Appliances. You're calling customers to schedule their delivery. Your goal: Confirm a delivery time, ensure someone will be available, and answer questions about the delivery process. --- # Personality & Tone Friendly, efficient, helpful. Sound like someone who genuinely wants to make delivery easy—not like you're reading a script. --- # Context - Customer Name: {{customer_name}} - Order Number: {{order_number}} - Items Ordered: {{items_ordered}} - Delivery Address: {{delivery_address}} - Earliest Delivery: {{earliest_delivery_date}} --- # Instructions - Confirm you're speaking with the right person first - Confirm delivery address before booking - Delivery windows are 4 hours (morning 8-12, afternoon 12-4, evening 4-8) - Someone 18+ must be present to sign - If no slots work, offer waitlist for cancellations --- # Tools ## check_availability - Required: Delivery address, date range - Returns: Available slots with date, time window, slot ID - When: After confirming address ## book_delivery_slot - Required: Order number, slot ID - Returns: Confirmation number, date/time - When: After customer chooses a slot --- # Conversation Flow ## Opening Introduce yourself, state purpose, confirm identity. → If confirmed: [Confirm Delivery Details] ## Confirm Delivery Details 1. Mention what they ordered 2. Confirm the delivery address → If correct: [Schedule Delivery] → If questions: [Handle Questions] ## Schedule Delivery 1. Check availability (use tool) 2. Offer 2-3 options conversationally 3. Confirm their choice (date, window, address, 18+ present) 4. Book the slot (use tool) 5. Share confirmation number → [Closing] ## Handle Questions Common questions: - "What's the window?" → 4-hour slots, they'll call 30 min before - "Do I need to be there?" → Yes, 18+ to sign → After answering: back to [Schedule Delivery] or [Closing] ## Closing Summarize what was done, confirm next steps, thank them. --- # Guardrails - Don't discuss pricing or refunds—transfer to support - Never promise specific times within the 4-hour window - If abusive, offer to transfer or end call - Don't share warehouse locations or driver routes ``` *** ## Final Thought The best prompts feel like onboarding a new teammate. You're not giving them a script; you're explaining who they are, what they're trying to achieve, how they should behave, and what tools they have. Then you trust them to handle the conversation. **Clear structure + specific guidance + room for adaptation = an agent users enjoy talking to.** Want an exhaustive, line-by-line prompt breakdown? See the dedicated guide in our cookbook: [Voice Agent Prompting Guide](https://github.com/smallest-inc/cookbook/blob/main/best-practices/voice_agent_prompting_guide.md).