> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/build/system-prompt.md). # Role Prompt Design Guide {% hint style="info" %} You can use the [System Prompt Generator AI tool](https://chat.maiagent.ai/web-chats/4b67b140-db5f-40dc-bce3-f2217e9574bd) created by MaiAgent to help you refine your system prompt {% endhint %} ## What Is a "System Prompt"? Imagine you're directing a movie and need to tell the actors what role they're playing, what personality they have, and how they should speak. A **system prompt** is like a "script" for the AI, telling it what kind of customer service agent to portray.
### Glossary of Technical Terms Before we begin, let's get familiar with a few important concepts: **AI Agent** * **Analogy**: Like a virtual employee you've hired * **Explanation**: An AI system capable of autonomously executing tasks; in customer service scenarios, it's your digital customer service representative **Prompt** * **Analogy**: An "instruction manual" for the AI * **Explanation**: The instructional text that tells the AI what to do and how to do it **Context** * **Analogy**: The "memory" and "background information" of a conversation * **Explanation**: The relevant information the AI needs to understand the current conversation scenario **Token** * **Analogy**: A "unit" through which AI processes text, like breaking sentences into small chunks * **Explanation**: The basic unit of text processing for AI, affecting processing efficiency and cost *** ## Why Is the System Prompt So Important? #### AI Customer Service Without a System Prompt ``` User: "Why hasn't my order arrived yet?" AI: "According to system data, your order status is processing." ``` *Feels like talking to a robot — cold and impersonal* #### AI Customer Service With a Good System Prompt ``` User: "Why hasn't my order arrived yet?" AI: "I completely understand your concern! Let me check your order status right away. Based on the tracking information, your package is currently at the distribution center, and it's expected to arrive tomorrow afternoon. Would you like me to provide the tracking number?" ``` *Feels like talking to a real customer service agent — warm and professional* *** ## The Four Pillars of a System Prompt #### 1. Identity Definition (Who) Tell the AI "who you are" **Bad — Vague identity** ``` You are a customer service agent ``` **Good — Clear identity** ``` You are "Mei," a senior customer service specialist at MaiAgent Company, with 5 years of customer service experience, specializing in product consultation and problem resolution. ``` #### 2. Tone and Style (How) Tell the AI "how to speak" **Tone Selection Guide:** * **Professional and formal**: Suitable for finance, legal, and healthcare industries * **Friendly and approachable**: Suitable for retail, dining, and lifestyle services * **Lively and youthful**: Suitable for gaming, entertainment, and fashion industries * **Warm and caring**: Suitable for education, health, and social services **Example: Friendly and Approachable Style** ``` When responding, use a warm and friendly tone, use polite forms of address to show respect, include phrases like "happy to help" for a personal touch, but avoid being overly enthusiastic or using too many exclamation marks. ``` #### 3. Professional Capabilities (What) Tell the AI "what you can do" ``` Your professional capabilities include: - Product feature introductions and usage guidance - Order inquiries and logistics tracking - Return and exchange policy explanations - Initial technical problem diagnosis - Account and payment issue resolution When encountering issues beyond your capabilities, proactively transfer the customer to a human agent. ``` #### 4. Behavioral Guidelines (Rules) Tell the AI "what you can and cannot do" ``` Mandatory principles: - Protect user privacy and never disclose personal information - Admit when you don't know something and never fabricate answers - When handling complaints, stay calm — apologize first, then resolve - Keep responses under 100 words for conciseness Strictly prohibited: - Making promises that cannot be fulfilled - Arguing with or contradicting users - Disclosing internal company information - Processing refund requests beyond your authority ``` *** ## Hands-On: Design Your First System Prompt #### Step 1: Analyze Your Business Needs **Consider these questions:** * Who are your customers? (age, occupation, usage habits) * What are your product/service highlights? * What questions do customers ask most frequently? * What kind of service experience do you want to deliver? #### Step 2: Choose the Right Role Configuration **E-commerce Customer Service Example** ``` You are "Helper," a professional online shopping consultant. You are familiar with all product information, skilled at recommending suitable products, and can quickly handle order-related issues. Your speaking style is friendly and natural, caring about customer needs like a friend. ``` **Healthcare Customer Service Example** ``` You are "Health Helper," a professional healthcare service consultant. You have basic medical knowledge and can provide information about appointments, examination procedures, etc., but you never provide medical diagnosis advice. Your speaking style is professional and warm, making patients feel reassured. ``` #### Step 3: Write the Complete System Prompt **System Prompt Template** ``` # Role Identity You are [Role Name], [Job Title] at [Company Name]. [Role background and professional experience] # Service Objective Your primary task is [core task], helping customers [achieve goal] through [service approach]. # Language Style - Tone: [Choose appropriate tone] - Vocabulary: [Specific vocabulary requirements] - Length: [Response length limit] # Professional Capabilities You can handle the following issues: - [Capability 1] - [Capability 2] - [Capability 3] # Behavioral Guidelines Must follow: - [Guideline 1] - [Guideline 2] Strictly prohibited: - [Prohibited action 1] - [Prohibited action 2] # Special Situation Handling When encountering [special situation], please [handling approach]. ``` *** ## Advanced Tips: Make Your System Prompt More Vivid #### 1. Add Personality Traits **Basic version:** ``` You are a customer service agent responsible for answering questions. ``` **Vivid version:** ``` You are "Zhi," a curious tech enthusiast. You're always excited about new features and love using simple analogies to explain complex technical concepts, making them easy for everyone to understand. ``` #### 2. Context-Aware Instructions Adjust responses based on different scenarios: ``` # Context-Aware Instructions - When a customer expresses dissatisfaction: respond with empathy first, then provide a solution - When a customer asks a technical question: explain using everyday analogies - When a customer hesitates to purchase: provide objective advice without pressuring a sale - When a customer praises the product: express gratitude and ask if they need further assistance ``` #### 3. Dynamic Adjustment Mechanism ``` # Conversational Adaptability Adjust your style based on the customer's responses: - If the customer uses formal language, be correspondingly formal - If the customer seems impatient, be more concise and efficient - If the customer is chatty, you can slightly extend the topic ``` #### **4. Version Control Friendly** * Add version numbers and changelogs * Maintain backward compatibility, ensuring existing workflows still function correctly after updating the system prompt Example: ``` Version: v1.0 # Update date: October 26, 2024 # Changelog: # - Initial version, providing basic product recommendation functionality. # - Recommends products based on user preferences. # - Response tone set to friendly and professional. ``` *** ## Test and Optimize Your System Prompt #### Phase 1: Basic Testing Test whether the AI's responses meet expectations using common questions **Test Question Examples:** * "What is your return policy?" * "When will my order arrive?" * "Is this product right for me?" #### Phase 2: Boundary Testing Test the AI's performance in extreme situations **Boundary Scenario Examples:** * When a customer is emotionally agitated * When encountering a question with no known answer * When asked to do something beyond authority #### Phase 3: Continuous Optimization **Collect Data** * Customer satisfaction scores * Issue resolution rate * Rate of transfers to human agents **Adjustment Strategies** * Supplement the knowledge base based on common questions * Adjust language style based on customer feedback * Refine behavioral guidelines based on failure cases *** ## **System Prompt Length Control Tips** **Best Practice Guidelines** The ideal system prompt length should be kept within 500-2000 words (approximately 200-800 tokens), with the optimal range typically being 800-1500 words. Remember this core principle: "Clarity over verbosity" — overly long instructions tend to be ignored by the model, while overly short ones may lead to unstable behavior. **Why Does Length Matter?** First, there's the **model performance** consideration — an overly long prompt dilutes the model's attention, affecting the execution of key instructions. Second, there's the **context space** limitation — the system prompt occupies the conversation's context window, compressing the space available for user conversation. Finally, there's **maintenance cost** — a concise, structured prompt is easier to continuously optimize and adjust. **Three Writing Tips** Structured design: Clearly segment content and place core instructions at the beginning. Conciseness principle: Remove duplicate descriptions and lengthy background, keeping only essential rules. Continuous validation: Conduct A/B testing across different models (GPT, Claude, Gemini) to find the optimal length configuration. **Practical Considerations** Different AI models have varying tolerance for long prompts, requiring individual testing and validation. For token calculation, Chinese characters are approximately 1 token each, while English is approximately 1 token per 0.75 words. Since the system prompt carries higher instruction weight, keep the content focused and avoid unnecessary verbosity. *** ## Frequently Asked Questions and Solutions #### Q1: How can I make the AI's responses more natural? **A:** Add specific conversation examples in the system prompt and set clear language style guidelines. #### Q2: What if the AI keeps answering irrelevant questions? **A:** Clearly define the service scope in the system prompt and teach the AI how to identify and handle out-of-scope questions. #### Q3: How do I balance professionalism and approachability? **A:** Adjust based on your target audience. B2B customers prefer professionalism, while B2C customers prefer approachability. Design A/B tests to find the optimal balance. *** ## Conclusion: Build Your Custom AI Customer Service Designing a system prompt is like training a new employee — it requires patience and continuous adjustment. Remember these key principles: 1. **Clear positioning**: Clearly tell the AI who it is 2. **Consistent style**: Maintain a unified language style 3. **Clear boundaries**: Clearly define what can and cannot be done 4. **Continuous optimization**: Continuously improve based on actual usage Start designing your first system prompt now! Remember, the best system prompts are those that are continuously refined through actual use. --- # 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.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/build/system-prompt.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.