.. _rating-agent: ============= Rating Agent ============= The Rating Agent is an AI-powered conversational assistant that collects insurance information through natural dialogue and calculates premiums automatically. Instead of filling out forms, users can simply chat with the agent to get quotes. .. contents:: Table of Contents :local: :depth: 2 Overview ======== What is the Rating Agent? -------------------------- .. figure:: _static/screenshots/rating_agent_conversation.png :alt: Rating Agent Conversation :align: center :width: 100% *Screenshot Placeholder: Chat interface showing natural conversation - "I need a quote for my business" → "What type of business?" → Agent collecting information conversationally* The Rating Agent is a conversational AI that: * Collects rating information through natural dialogue * Asks intelligent follow-up questions * Validates inputs in real-time * Guides users through the quoting process * Calculates premiums automatically * Handles corrections and changes easily Key Features ------------ .. table:: Rating Agent Features :widths: 30 70 +---------------------------+------------------------------------------------------------+ | Feature | Description | +===========================+============================================================+ | Natural Conversation | Talk normally, no forms to fill | +---------------------------+------------------------------------------------------------+ | Smart Questions | Asks for required information based on product | +---------------------------+------------------------------------------------------------+ | Real-Time Validation | Catches errors immediately with helpful guidance | +---------------------------+------------------------------------------------------------+ | Context Awareness | Remembers answers, handles corrections | +---------------------------+------------------------------------------------------------+ | Multi-Product Support | Works with all configured insurance products | +---------------------------+------------------------------------------------------------+ | Progress Tracking | Shows what's been collected and what's needed | +---------------------------+------------------------------------------------------------+ When to Use ----------- Use the Rating Agent when: * You prefer conversation over forms * Helping clients who are uncomfortable with web forms * Training new staff (agent guides through process) * On mobile devices (easier than form input) * Collecting information during phone calls * You want a faster, more natural quoting experience Getting Started =============== Accessing the Rating Agent --------------------------- .. figure:: _static/screenshots/rating_agent_access.png :alt: Access Rating Agent :align: center :width: 100% *Screenshot Placeholder: Main menu showing "AI Quote Assistant" menu item and Calculator page with "Switch to Chat Mode" toggle button* Access the agent in two ways: **Option 1: Chat Mode Toggle** 1. Navigate to **Calculator** 2. Click **Switch to Chat Mode** toggle 3. Calculator transforms into chat interface 4. Start typing to begin conversation **Option 2: Dedicated Page** 1. Click **AI Quote Assistant** in main menu 2. Opens full-screen chat interface 3. Agent greets you automatically 4. Begin your conversation First-Time User Experience --------------------------- .. figure:: _static/screenshots/rating_agent_first_use.png :alt: First-Time User Experience :align: center :width: 100% *Screenshot Placeholder: Welcome message from agent explaining how to get started with examples of what to say* When you first open the chat, the agent welcomes you: .. code-block:: text Agent: "Hello! I'm your insurance quoting assistant. I can help you get quotes for: • Business Owners Policy (BOP) • General Liability • Workers Compensation • Commercial Auto • And more... Just tell me what you need! For example: • 'I need a quote for my business' • 'I want a BOP policy' • 'Get me a workers comp quote' What can I help you with today?" Using the Rating Agent ====================== Understanding the Interface ---------------------------- .. figure:: _static/screenshots/rating_agent_interface_anatomy.png :alt: Interface Anatomy :align: center :width: 100% *Screenshot Placeholder: Annotated chat interface showing conversation area, progress sidebar, collected data panel, and input field* The interface includes: 1. **Chat Area** (Left, 60%): * Conversation history * Agent messages (blue, left-aligned) * Your messages (gray, right-aligned) * Typing indicator * Auto-scrolls to latest 2. **Progress Sidebar** (Right, 40%): * Product selected * Collection progress (e.g., "3 of 5 factors collected") * Collected data summary * Edit buttons for corrections * Calculate button (when ready) 3. **Input Area** (Bottom): * Text input field * Send button * Microphone button (if supported) Starting a Quote ---------------- **Example 1: Direct Request** .. code-block:: text User: "I need a BOP quote" Agent: "Perfect! I'll help you get a Business Owners Policy quote. First, I need to know your business location. What's your territory code or ZIP code?" **Example 2: General Request** .. code-block:: text User: "I need insurance for my business" Agent: "I'd be happy to help! What type of business insurance do you need? Common options: • Business Owners Policy (BOP) - Property + Liability • General Liability - Covers lawsuits and injuries • Workers Compensation - Employee injury coverage • Commercial Auto - Vehicle coverage Which one interests you?" **Example 3: Specific Scenario** .. code-block:: text User: "My client owns a retail store downtown and needs insurance" Agent: "Got it! A downtown retail store typically needs a Business Owners Policy (BOP) that covers both property and liability. I'll collect some information to calculate the premium: Starting with location - you mentioned downtown. What's the specific territory code or ZIP code?" The Conversation Flow ===================== Product Selection ----------------- .. figure:: _static/screenshots/rating_agent_product_selection.png :alt: Product Selection :align: center :width: 100% *Screenshot Placeholder: Conversation showing agent helping user select the right product with explanations of each option* The agent helps identify the right product: .. code-block:: text User: "I'm not sure which product I need" Agent: "No problem! Let me help you figure it out. What kind of business is this for, and what are you trying to protect? • Physical building or property? • Liability (if someone gets injured)? • Employees (workers compensation)? • Vehicles (commercial auto)? Tell me more about your situation." User: "I have a coffee shop and want to protect the building and if someone slips and falls" Agent: "Perfect! For a coffee shop, I recommend a Business Owners Policy (BOP). It combines: ✓ Property coverage (your building, equipment, inventory) ✓ Liability coverage (slip and falls, customer injuries) ✓ Business income (if you have to close due to damage) This is the most comprehensive and cost-effective option. Shall we proceed with a BOP quote?" Collecting Factors ------------------ .. figure:: _static/screenshots/rating_agent_collecting_factors.png :alt: Collecting Factors :align: center :width: 100% *Screenshot Placeholder: Sequential collection of factors with validation and helpful explanations* The agent asks for required information sequentially: **Factor 1: Territory** .. code-block:: text Agent: "Great! First, I need your territory code. This is usually a 2-digit code based on your location. If you don't know your territory code, just tell me your ZIP code or city and I'll help find it." User: "Downtown Chicago" Agent: "Chicago downtown is typically territory 14. Does that sound right?" User: "Yes" Agent: "Perfect! Territory 14 confirmed. (1 of 5 collected) Next, what's your business classification code? This is a 5-digit code describing your business type. For coffee shops, it's typically 47221 (Restaurants and Food Service). Is that your classification, or do you have a different one?" **Factor 2: Building Area** .. code-block:: text User: "Yes, that's right" Agent: "Excellent! Classification 47221 confirmed. (2 of 5) Now, what's the total square footage of your building?" User: "About 2500 square feet" Agent: "Got it - 2,500 square feet. (3 of 5) Next, what's your building's replacement value? This is how much it would cost to rebuild if destroyed." **Factor 3: Building Value** .. code-block:: text User: "I'm not sure, maybe $500,000?" Agent: "Okay, I have $500,000 as the building value. Keep in mind this should be the full replacement cost, not the market value or what you paid for it. For a 2,500 sq ft commercial building in downtown Chicago, typical replacement costs are $200-$300 per square foot, which would be $500,000-$750,000. Your $500,000 estimate seems on the lower end. Would you like to adjust this, or proceed with $500,000?" User: "Let's say $600,000 to be safe" Agent: "Smart choice! Updated to $600,000. (4 of 5) Last required item: What construction type is your building? • Brick (fire-resistant masonry) • Frame (wood construction) • Concrete (poured concrete) • Mixed (combination)" Handling Validation Errors --------------------------- .. figure:: _static/screenshots/rating_agent_validation.png :alt: Validation and Error Handling :align: center :width: 100% *Screenshot Placeholder: Agent catching an error and providing helpful guidance to correct it* The agent validates inputs immediately: **Example 1: Value Out of Range** .. code-block:: text User: "The building is 50 square feet" Agent: "I noticed 50 square feet is quite small for a coffee shop. Our system requires a minimum of 500 square feet for commercial properties. Did you mean: • 500 square feet? • 5,000 square feet? • 2,500 square feet? Or a different number?" User: "Sorry, I meant 2,500" Agent: "No problem! 2,500 square feet - that makes much more sense for a coffee shop. I've updated that." **Example 2: Invalid Format** .. code-block:: text User: "Territory is downtown" Agent: "I understand you're downtown! However, I need the specific 2-digit territory code for rating purposes. For downtown Chicago, the code is typically '14'. Does that work for you?" User: "Yes, 14" Agent: "Perfect! Territory 14 saved." Collecting Coverages -------------------- .. figure:: _static/screenshots/rating_agent_coverages.png :alt: Coverage Collection :align: center :width: 100% *Screenshot Placeholder: Agent explaining coverage options and helping user select appropriate limits* After collecting factors, the agent helps select coverages: .. code-block:: text Agent: "Great! I have all the basic information. (5 of 5) Now let's set up your coverages. For a BOP policy, you can select: 1. Building Coverage Protects the physical structure Recommended: $600,000 (matches your building value) 2. Business Personal Property Covers equipment, furniture, inventory Typical: $100,000-$250,000 3. General Liability Protects if customers get injured Standard: $1,000,000 4. Business Income (optional) Covers lost revenue if you close due to damage Optional: $50,000-$100,000 Would you like me to add all of these with standard limits, or would you like to customize?" User: "Standard limits sound good" Agent: "Perfect! I'll add: ✓ Building: $600,000 with $1,000 deductible ✓ Business Personal Property: $150,000 with $500 deductible ✓ General Liability: $1,000,000 ✓ Business Income: $75,000 You can always adjust these. Ready to calculate your premium?" Calculating the Premium ----------------------- .. figure:: _static/screenshots/rating_agent_calculation.png :alt: Premium Calculation :align: center :width: 100% *Screenshot Placeholder: Agent showing calculated premium with breakdown and next steps* When ready, calculate the premium: .. code-block:: text User: "Yes, calculate it" Agent: "Calculating your premium... ⏳" [Processing 3-5 seconds] Agent: "Great news! I've calculated your premium: **Annual Premium: $2,847** Breakdown by coverage: • Building: $1,320 • Business Personal Property: $485 • General Liability: $892 • Business Income: $150 This quote is valid for 30 days. What would you like to do next? • View full calculation details • Adjust coverages or deductibles • Save this quote • Email this quote • Start a new quote" Making Corrections ================== Changing Previous Answers -------------------------- .. figure:: _static/screenshots/rating_agent_corrections.png :alt: Making Corrections :align: center :width: 100% *Screenshot Placeholder: User correcting a previous answer and agent updating the information* The agent remembers context and handles changes: **Method 1: Conversational Correction** .. code-block:: text User: "Actually, the building is wood frame, not brick" Agent: "No problem! I've updated the construction type to wood frame. Note: This will affect your premium. Wood frame typically has higher rates than brick due to fire risk. The property premium will increase from $1,320 to approximately $1,580. Would you like me to recalculate with this change?" **Method 2: Using the Sidebar** 1. Look at "Collected Data" sidebar 2. Click "Edit" next to the field 3. Enter new value 4. Agent acknowledges the change **Method 3: Explicit Change Request** .. code-block:: text User: "Change the building value to $750,000" Agent: "Updated! Building value changed from $600,000 to $750,000. This will increase your Building coverage premium from $1,320 to approximately $1,650. Shall I recalculate the total premium?" Going Back ---------- If you need to change multiple things: .. code-block:: text User: "Can we start over with different coverages?" Agent: "Of course! I'll keep your basic information (territory, classification, building details) and we can reconfigure the coverages. Which coverages would you like to change?" User: "I want to increase the General Liability to $2 million" Agent: "Done! General Liability increased to $2,000,000. This will add approximately $380 to the annual premium. Any other changes?" Advanced Features ================= Multiple Locations ------------------ .. figure:: _static/screenshots/rating_agent_multiple_locations.png :alt: Multiple Locations :align: center :width: 100% *Screenshot Placeholder: Agent managing multiple locations with separate details for each* For businesses with multiple locations: .. code-block:: text User: "I have two locations" Agent: "Great! I can help you quote both locations. We can do this two ways: Option 1: Quote each location separately (2 separate policies) Option 2: Quote as a multi-location policy (1 combined policy) Which would you prefer?" User: "Separate policies" Agent: "Perfect! We'll quote each location individually. We just finished Location 1 (Downtown Chicago). For Location 2, I'll need the same information: • Territory/location • Building details • Coverages desired What's the address or territory for Location 2?" Comparing Options ----------------- Ask the agent to compare scenarios: .. code-block:: text User: "What if I increased the deductible to $5,000?" Agent: "Good question! Let me show you the comparison: Current ($1,000 deductible): • Annual premium: $2,847 • Out-of-pocket per claim: $1,000 With $5,000 deductible: • Annual premium: $2,490 (save $357/year) • Out-of-pocket per claim: $5,000 Pros of higher deductible: ✓ Save $357 per year ✓ Lower total cost if no claims Cons: ✗ Pay $4,000 more out-of-pocket per claim ✗ Need $5,000 cash available for emergencies Break-even: If you go 11+ years without a claim, higher deductible saves money. Would you like to switch to the $5,000 deductible?" Saving Quotes ------------- .. figure:: _static/screenshots/rating_agent_save_quote.png :alt: Saving Quotes :align: center :width: 100% *Screenshot Placeholder: Options for saving, emailing, or sharing the calculated quote* After calculating, save your quote: .. code-block:: text User: "Save this quote" Agent: "Quote saved! You can find it in Rating History. I've also created: • Quote Reference: Q-2025-0042 • Saved for: Next 30 days • Last modified: Jan 17, 2025 Would you like me to: • Email this quote to you? • Generate a PDF? • Share with a colleague? • Start another quote?" Best Practices ============== Getting the Best Experience ---------------------------- 1. **Be Natural**: Talk normally, the agent understands context .. code-block:: text ✓ "My building is about 5000 square feet" ✓ "The building's around 5,000" ✓ "5000 sqft" 2. **Provide Context**: More information helps the agent .. code-block:: text ✓ "I have a retail clothing store in downtown Chicago" Better than: "I need insurance" 3. **Ask Questions**: The agent can explain anything .. code-block:: text ✓ "What's a territory code?" ✓ "Why do you need the building value?" ✓ "What coverage limit should I choose?" 4. **Correct Freely**: Don't worry about mistakes .. code-block:: text ✓ "Actually, change that to 10,000" ✓ "Wait, I meant wood frame not brick" 5. **Review Before Calculating**: Check the sidebar summary Example Good Conversation -------------------------- .. code-block:: text User: "Hi, I need a quote for my coffee shop" Agent: "I'd be happy to help! I'll get you a Business Owners Policy quote for your coffee shop. Where is it located?" User: "235 Main Street, Chicago, IL 60601" Agent: "Perfect! That's territory 14 (Downtown Chicago). What's the square footage of your shop?" User: "Around 2000 square feet" Agent: "Got it - 2,000 sq ft. What's the building's replacement value? (Not what you paid, but what it would cost to rebuild)" User: "Maybe $500,000?" Agent: "For a 2,000 sq ft commercial building downtown, that seems reasonable. I'll use $500,000. What's the construction type?" User: "It's brick" Agent: "Excellent! Brick construction qualifies for better rates. I have everything I need. Calculating... ⏳ **Your annual premium: $2,385** This includes property coverage, liability, and business income protection. Want to see the breakdown?" User: "Yes please" Agent: "Breakdown: • Building coverage: $1,050 • Business property: $420 • General Liability: $765 • Business Income: $150 Questions? Want to adjust anything?" Troubleshooting =============== Agent Not Understanding ----------------------- If the agent seems confused: .. code-block:: text User: "The thing is 5000" Agent: "I'm not sure what you're referring to. Are you talking about: • Square footage? • Building value? • Coverage limit? Can you clarify?" ✓ Better: "The square footage is 5000" Agent Asking Repeated Questions -------------------------------- If the agent asks for something you already provided: .. code-block:: text User: "I already told you that - it's territory 14" Agent: "You're absolutely right, my apologies! I have territory 14 recorded. Let me continue with the next question..." Calculation Taking Too Long ---------------------------- If the calculation seems stuck: 1. **Wait**: Initial calculations can take 10-15 seconds 2. **Check Connection**: Look for "Connected" status 3. **Refresh**: If >30 seconds, refresh and try again 4. **Report**: If persistent, contact support Starting Over ------------- To start a completely new quote: .. code-block:: text User: "Start over" or "New quote" Agent: "Sure! I'll clear everything and we can start fresh. What type of insurance quote do you need?" Technical Details ================= How It Works ------------ .. figure:: _static/screenshots/rating_agent_architecture.png :alt: Rating Agent Architecture :align: center :width: 100% *Screenshot Placeholder: Architecture showing WebSocket connection, AI processing, data collection, and rating service integration* The Rating Agent: 1. **Understands Intent**: Uses AI to interpret what you're asking 2. **Determines Next Step**: Knows what information is needed 3. **Validates Input**: Checks answers in real-time 4. **Stores Data**: Keeps track of collected information 5. **Calculates Premium**: Calls the rating service when ready 6. **Provides Results**: Presents the calculated premium Supported Products ------------------ The agent works with all configured products: * Business Owners Policy (BOP) * General Liability * Workers Compensation * Commercial Auto * Property * And any other products in your system .. note:: The agent automatically learns about new products as they're added to the system. Data Collection --------------- The agent collects: * **Product Selection**: Which insurance product * **Risk Characteristics**: Required rating factors * **Coverage Options**: Selected coverages and limits * **Deductibles**: Chosen deductible amounts * **Additional Info**: Any modifiers or endorsements All collected data is stored in your conversation session and used to create the final rating request. Security and Privacy ==================== Data Protection --------------- Your conversations are protected: * **Encrypted**: All communication uses TLS encryption * **Authenticated**: Must be logged in * **Session-Isolated**: Each conversation is independent * **Temporary**: Conversation data expires after session * **Audit Trail**: Rating calculations are logged What Gets Saved --------------- .. table:: Data Retention :widths: 30 70 +---------------------+------------------------------------------------------------+ | Data Type | Retention | +=====================+============================================================+ | Conversation | Session only (not permanently stored) | +---------------------+------------------------------------------------------------+ | Collected Data | Until rating calculated or session expires | +---------------------+------------------------------------------------------------+ | Rating Results | Permanently stored in Rating History | +---------------------+------------------------------------------------------------+ Next Steps ========== * **Try It**: Click "AI Quote Assistant" to start a conversation * **Learn More**: See :doc:`ai_agents_overview` for AI features overview * **Compare**: Use traditional :doc:`performing_calculations` calculator * **Bulk Quotes**: See :doc:`bulk_rating` for high-volume quoting .. tip:: New users often find the Rating Agent easier than the traditional calculator. Try both to see which you prefer! .. warning:: Always review calculated premiums for accuracy before presenting to clients. The agent is a tool to assist, not replace, professional judgment.