> For the complete documentation index, see [llms.txt](https://docs.voiceb.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voiceb.ai/product-guides/voiceb-prompt-and-script-guide.md). # VoiceB Prompt & Script Guide You no longer write prompts and scripts by hand. **Agent Studio** builds and refines your agent's configuration conversationally — you describe your business and your goals, and it generates the four core blocks that power every agent: **Goal, Script, Objections, and Guardrails**. This guide shows you how to work with Agent Studio, and explains the best practices behind well-structured blocks so you can review, refine, and optimize what it produces — and get more natural, personalized, conversion-oriented conversations. *** #### How it works in Agent Studio
Start a session and tell Agent Studio: * What your company sells * Who your target caller is * What a successful call looks like (a sale, a qualified lead, a booked appointment) * Any key objections your team regularly handles You can also give it a URL to build the knowledge base automatically (see Automate Your Knowledge Base with Web Scraping). Agent Studio generates the agent's full configuration across the four blocks below. You review and edit each block independently — or simply tell it what to change in plain language. The agent improves through conversation, not by hand-editing raw prompts. {% hint style="info" %} **Knowledge vs. behavior:** Keep your reference knowledge (facts, pricing, FAQs) consolidated in a **single knowledge block** for easy maintenance. Your agent's *behavior* — persona, flow, objections, and boundaries — is structured across the four blocks below. {% endhint %}
*** #### The Four Core Blocks Separating instructions by responsibility makes it easier for the AI to retrieve the right information — and simpler for you to update. ``` 1. GOAL → The mission, persona, and core objective 2. SCRIPT → The conversational flow, stages, and phrasing 3. OBJECTIONS → Rebuttals, FAQs, and soft-landing formulas 4. GUARDRAILS → Hard boundaries, do-nots, and fallback behaviors 5. KNOWLEDGE BASE 6. ... ```
**🎯 Block 1 — Goal (the "who" and "why")** The Goal block establishes the agent's identity, tone, and what a successful call looks like. * **Define a clear persona:** role, company name, and emotional tone.\ \&#xNAN;*e.g. "You are Sarah, a warm, professional customer success specialist at GreenEnergy Corp."* * **Establish a single target outcome:** state exactly what the agent is trying to achieve.\ \&#xNAN;*e.g. "Your primary goal is to qualify the lead and schedule a 15-minute consultation. Do not try to sell the product directly on this call."* * **Acknowledge the starting state:** briefly mention how the lead was generated.\ \&#xNAN;*e.g. "The contact requested a quote on our website yesterday."* **💬 Block 2 — Script (the "how")** The Script is a conversational map, not a rigid, word-for-word monologue. * **Write for the ear, not the eye:** short, conversational sentences that are easy to pronounce. Avoid jargon. * **Open warmly:** the first line the agent says should be short and welcoming.\ \&#xNAN;*e.g. "Hi, I'm \[Agent Name], your AI assistant from \[Company]. Which service are you interested in today?"* * **Use phase-based milestones:** * **Phase 1 — Hook & Permission:** acknowledge who they are, state why you're calling, ask for a moment. * **Phase 2 — Discovery & Qualification:** ask 1–2 open-ended questions instead of lecturing. * **Phase 3 — Pitch / Value Prop:** keep it under 3 sentences. * **Phase 4 — Close / Call-to-Action:** make a concrete, low-friction proposal. * **Build in micro-agreements:** check in often (*"Does that make sense?"*) to keep the caller engaged. * **Map the main flows / branches:** * *Interested – doesn't know what they want* → ask discovery questions * *Interested – knows what they want* → collect required data and move to close * *Already a customer* → redirect politely to customer service * *Wrong number* → end the call gracefully * *Wants a human agent* → collect data, then prepare transfer * **Validation rules:** check email format, phone length, IDs where required. Normalize values (*"3 coma 45" → "3.45 kW"*). * **Silence management:** * 1.5s → "Do you need me to repeat that?" * 3s → "Are you still there?" * 8s → end politely * **Closing lines:** * Valid lead → "Thanks, an agent will contact you soon." * Non-lead → "Thanks for your time, call us again if you need." * **Tone & voice:** \~150 words/minute, warm, professional, natural; use synonyms to avoid repetition. {% hint style="info" %} **Agent Instructions (DO NOT READ ALOUD):** Place non-spoken directives at the end of the Script block, in brackets, so the AI doesn't read them out. ``` Agent Instructions (DO NOT READ ALOUD) - Speak slowly and clearly. - Avoid long pauses or unnecessary delays. - Do not ask for personal data outside of the online form. - Use tone variation to sound natural and human. - Always acknowledge the customer's responses before moving forward. - Follow the sign-up steps strictly in sequence. ``` {% endhint %} **🛡️ Block 3 — Objections (the "what if")** Train your agent to handle pushback gracefully rather than ignoring it or sounding defensive. Use the **Acknowledge → Pivot → Ask (APA)** formula: * **Acknowledge:** validate the concern — *"I completely understand budget is top of mind right now\..."* * **Pivot:** reframe the value — *"...which is exactly why we focus on cutting your operational costs by 30%..."* * **Ask:** hand the microphone back — *"...how much are you currently spending on manual data entry?"* List the top 3–5 objections with ready responses, for example: * *"I don't have time right now."* * *"Is this a robot?"* → "Yes, I'm an AI assistant helping the team today — and I'm fully equipped to get this sorted for you. Can I ask..." * *"We already have a provider."* * *"Just email me the information."* * *Refuses privacy consent* → "I understand. Unfortunately I can't continue without your consent — if you change your mind, feel free to call us again." **🚧 Block 4 — Guardrails (the "do nots")** Guardrails keep your agent compliant, safe, and professional. * **Define no-go zones:** topics the agent must never discuss.\ \&#xNAN;*e.g. "Never promise specific pricing percentages; only state that pricing is customized."* * **Handle interruptions:** instruct the AI to yield instantly if the human speaks over it. * **Set fallback behaviors:** give the AI a line for when it doesn't know the answer.\ \&#xNAN;*e.g. "That's a great technical question — let me note it so our engineer can address it in your scheduled demo."* * **Identify transfer triggers:** define when to hand off to a human.\ \&#xNAN;*e.g. "If the caller becomes angry, demands a manager, or uses profanity, transfer the call immediately."* *** #### Conversation Design Golden Rules * **Keep turns short:** no single agent response should exceed \~30–40 words (\~15 seconds). Long monologues make callers tune out or interrupt. * **Format with Markdown inside blocks:** bolding, bullets, and numbered lists. The underlying model reads structured Markdown far better than walls of plain text. * **One question at a time:** never ask double-barreled questions. Ask, wait, then ask the next. *** #### Click to Call Variables Pass customer data from your form directly into the dialogue to personalize the conversation in real time. * Greeting → "Hi {{name}}, thanks for contacting us about {{product}}. How can I help you today?" * In-flow → "I see you're interested in {{product}}. Let's review the details together." *** {% hint style="danger" %} **Alert – Character Limit**\ For best performance, the combined content of your **Goal, Script, Objections, and Guardrails** blocks should stay **below 21,000 characters**.\ \- Beyond this limit, the AI may behave unpredictably, pause, or fail to load.\ \- Keep blocks concise, avoid redundant text, and move long instructions or legal disclaimers into **Agent Instructions** at the end of the Script (in brackets).\ \- Always test the agent after adding content to confirm it runs smoothly. {% endhint %} *** #### Data Collection Define what information the agent must request and validate. Typical fields: * Name * Email * Phone * Address (Street, Number, City, ZIP) * Consent (Yes/No) * Appointment date/time **Create a Data Collection Schema** {% hint style="info" %} **Tips:** Repeat each piece of data back in question form to confirm it. Normalize values. Don't collect data you won't use. {% endhint %} *** #### Integrations Connect your agent with **Salesforce**, **HubSpot**, or custom **Webhooks** to send collected data in real time. {% hint style="info" %} **Tips:** Always test the webhook with a sample call. Map your CRM fields to match the Data Collection schema. {% endhint %} *** #### Final Checklist ✅ Built and refined in Agent Studio\ ✅ Clear Goal — persona + single target outcome\ ✅ Script with phase-based milestones and modular flows\ ✅ Short, warm opening line\ ✅ Objections handled with the APA formula\ ✅ Guardrails: no-go zones, interruptions, fallbacks, transfer triggers\ ✅ Data Collection schema defined\ ✅ Validation + silence-management rules applied\ ✅ Standard closing messages\ ✅ Click to Call Variables used for personalization\ ✅ Turns short (30–40 words), one question at a time\ ✅ Combined blocks under 21,000 characters\ ✅ **Agent Instructions placed at the end of Script (DO NOT READ ALOUD)** ***
{% hint style="success" %} **Build or refine with Agent Studio:** Ask Agent Studio to review your live agent's blocks and suggest optimizations against these guidelines — or build a brand-new agent from scratch. It's all done in natural language. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.voiceb.ai/product-guides/voiceb-prompt-and-script-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.