> For the complete documentation index, see [llms.txt](https://dataqueue.gitbook.io/voicehub-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dataqueue.gitbook.io/voicehub-docs/agent-design-and-usage/prompt-design.md). # Prompt Design Well-written prompts define how your agent behaves throughout a conversation. Keep prompts structured, specific, and limited to the scope where their instructions apply. ### Global Prompt The global prompt contains instructions that apply throughout the entire conversation and across all pathway nodes. Use the global prompt for: * The agent’s identity and general purpose * Personality and tone * Preferred terminology and word usage * Language behavior * General business or safety rules * Fallback behavior for unrelated topics * Instructions that should apply consistently across the whole pathway Avoid repeating global instructions inside every node prompt. #### Global prompt example ``` You are Noor, a calm and professional medical intake agent for Al-Razi. Use clear and simple language. Be patient when asking the user to repeat information. Use the term "appointment" instead of "booking". If the user asks about an unrelated topic, politely explain that you can only assist with medical intake and appointments. When Arabic words form the primary sentence structure, respond in Arabic, even when English technical terms are present. When English words form the primary sentence structure, respond in English, even when Arabic names or a few Arabic words are present. ``` ### Node Prompts A node prompt defines what the agent must do at one specific step in the pathway. Treat each node prompt as a small contract. Clearly define: * The context of the current step * The input variables available to the node * The task the agent must complete * The rules it must follow * What to do when information is missing or unclear Keep node prompts focused. Do not repeat the full agent personality or general instructions already included in the global prompt. #### Node prompt example ``` ### CONTEXT The user is scheduling a medical appointment. ### INPUT VARIABLES patientName: {{patientName}} preferredLocation: {{preferredLocation}} appointmentTime: {{appointmentTime}} ### TASK Confirm the patient's name, preferred location, and appointment time. ### RULES - Only use information provided by the user or available in the input variables. - Do not guess missing information. - Ask only for information that is still missing. - Keep the response short and clear. ### FALLBACK If the user's answer is unclear, ask them to repeat it. If the information remains unclear, offer to transfer the user. ``` ### Variable Templating Use variables to insert information collected earlier in the pathway or provided when the call starts. Write a variable using the following format: ``` {{varName}} ``` VoiceHub replaces the placeholder with the variable's current value before the prompt is processed. Use clear and descriptive variable names. Whenever possible, write the variable name before its placeholder and include a type or unit when it helps prevent confusion. ``` patientName: {{patientName}} availableBalance (number, JOD): {{availableBalance}} cardStatus (active, blocked, expired): {{cardStatus}} ``` Avoid vague variable names such as: ``` data info result value ``` #### Example before variable replacement ``` ### INPUT VARIABLES patientName: {{patientName}} appointmentTime: {{appointmentTime}} ### TASK Tell {{patientName}} that their appointment is scheduled for {{appointmentTime}}. ``` #### Available variable values ``` patientName = Noor appointmentTime = Monday at 10:00 AM ``` #### Prompt after variable replacement ``` ### INPUT VARIABLES patientName: Noor appointmentTime: Monday at 10:00 AM ### TASK Tell Noor that their appointment is scheduled for Monday at 10:00 AM. ``` The agent now receives the real values instead of the variable placeholders. ### Handling Missing Variables Always define what the agent should do when required information is unavailable. A variable may be missing, empty, or null. The agent must not guess or infer its value from unrelated context. #### Recommended behavior ``` - If patientName is missing, ask the user for their name. - If appointmentTime is missing, ask for the preferred appointment time. - Do not invent or estimate missing values. - Before responding, verify that every value used in the answer is available. ``` For nodes that return structured values for routing or later processing, use one predictable fallback value: ``` If required information is unavailable, return: DATA_NOT_AVAILABLE ``` For conversational nodes, use a natural fallback: ``` If the required information is missing, ask the user to provide it. ``` ### Keep Node Responsibilities Separate Do not place voice instructions or pathway-routing instructions inside node prompts. #### Do not add voice instructions to node prompts Avoid instructions such as: ``` Speak using a female voice. Speak more slowly. Use a higher pitch. ``` Configure voice selection and voice behavior in the relevant voice settings instead of the node prompt. A node prompt may describe the conversational tone when it is specific to the current step, but it should not attempt to control the technical voice configuration. #### Do not add edge-selection instructions to node prompts Avoid instructions such as: ``` If the user says yes, select the Confirmation edge. Move to the Transfer edge when the answer is unclear. Choose the second edge after collecting the user's name. ``` Configure routing and transition conditions using Pathway Edges. The node prompt should describe only the task: ``` Ask the user to confirm the appointment details. ``` The connected edges should determine what happens next based on the user's response. ### Recommended Prompt Structure The following structure works well for most node prompts: ``` ### IDENTITY Define the role only when the node requires a role different from the global prompt. ### CONTEXT Explain the current step of the conversation. ### INPUT VARIABLES List every variable available to the node. ### TASK State exactly what the agent must do. ### RULES Define what information may be used and what the agent must avoid. ### FALLBACK Define what to do when information is missing or unclear. ``` Not every prompt needs every section. Include only the sections that help make the node's responsibility clear. ### Complete Example #### Global prompt ``` You are Noor, a calm and professional medical intake agent for Al-Razi. Use short and clear sentences. Be patient and respectful. Respond in the language primarily used by the user. Only assist with patient intake and appointment-related requests. For unrelated topics, politely redirect the conversation to medical intake. Do not provide a diagnosis or invent medical information. ``` #### Node prompt before replacement ``` ### CONTEXT The user has provided their appointment information. ### INPUT VARIABLES patientName: {{patientName}} preferredLocation: {{preferredLocation}} appointmentTime: {{appointmentTime}} ### TASK Confirm the appointment details with the user. ### RULES - Use only the values shown in Input Variables. - Do not add information that was not provided. - Keep the confirmation short. - Ask for any required value that is missing. ### FALLBACK If the user says that any detail is incorrect, ask for the correct value. ``` #### Variable values ``` patientName = Noor preferredLocation = Al-Razi Main Clinic appointmentTime = Monday at 10:00 AM ``` #### Node prompt after replacement ``` ### CONTEXT The user has provided their appointment information. ### INPUT VARIABLES patientName: Noor preferredLocation: Al-Razi Main Clinic appointmentTime: Monday at 10:00 AM ### TASK Confirm the appointment details with the user. ### RULES - Use only the values shown in Input Variables. - Do not add information that was not provided. - Keep the confirmation short. - Ask for any required value that is missing. ### FALLBACK If the user says that any detail is incorrect, ask for the correct value. ``` A suitable response would be: ``` Noor, your appointment is scheduled at Al-Razi Main Clinic on Monday at 10:00 AM. Is that correct? ``` ### Best Practices * Use short sections instead of long paragraphs. * Write direct and specific instructions. * Keep global behavior in the global prompt. * Keep each node focused on one conversation step. * List input variables explicitly. * Use descriptive variable names. * Define what happens when information is missing. * Do not allow the agent to guess sensitive or account-specific information. * Keep routing instructions in Pathway Edges. * Keep technical voice configuration out of node prompts. * Test prompts using complete, missing, and unclear variable values.