.. _ai-agents-overview: ==================== AI Agents Overview ==================== The tiger Rating Engine features AI-powered agents that enhance the rating experience with natural language interaction, intelligent explanations, and automated workflows. .. contents:: Table of Contents :local: :depth: 2 Introduction ============ AI Agents Capabilities ----------------------- .. figure:: _static/screenshots/ai_agents_dashboard.png :alt: AI Agents Dashboard :align: center :width: 100% *Screenshot Placeholder: AI Agents dashboard showing three cards - Explanation Agent (answers questions about premiums), Rating Agent (conversational quoting), Bulk Rating (process multiple quotes) with status indicators* The tiger Rating Engine includes three AI-powered features: 1. **Explanation Agent**: Explains premium calculations in plain language 2. **Rating Agent**: Collects information through conversation to calculate premiums 3. **Bulk Rating System**: Processes hundreds or thousands of quotes simultaneously Key Benefits ------------ .. table:: AI Agent Benefits :widths: 25 75 +---------------------------+------------------------------------------------------------+ | Benefit | Description | +===========================+============================================================+ | Natural Language | Ask questions and get answers in plain English | +---------------------------+------------------------------------------------------------+ | Transparency | Understand exactly how premiums are calculated | +---------------------------+------------------------------------------------------------+ | Efficiency | Process multiple quotes simultaneously | +---------------------------+------------------------------------------------------------+ | Accessibility | No technical knowledge required | +---------------------------+------------------------------------------------------------+ | Automation | Reduce manual data entry and errors | +---------------------------+------------------------------------------------------------+ Technology Stack ================ AI Platform ----------- .. figure:: _static/screenshots/ai_tech_stack.png :alt: AI Technology Stack :align: center :width: 100% *Screenshot Placeholder: Architecture diagram showing Django → Channels (WebSocket) → Pydantic AI → AWS Bedrock (Claude) → User Browser* Core technologies: * **Pydantic AI**: Agent framework for structured AI interactions * **AWS Bedrock**: Enterprise AI service (Claude models) * **Django Channels**: Real-time WebSocket communication * **Redis**: Session state and message queuing Supported Models ---------------- .. table:: AI Model Options :widths: 20 30 50 +--------------+--------------------------------+----------------------------------------+ | Provider | Model | Use Case | +==============+================================+========================================+ | AWS Bedrock | Claude 3.5 Sonnet | Production (recommended) | +--------------+--------------------------------+----------------------------------------+ | AWS Bedrock | Claude 3 Haiku | Fast responses, lower cost | +--------------+--------------------------------+----------------------------------------+ | AWS Bedrock | Claude 3 Opus | Complex reasoning | +--------------+--------------------------------+----------------------------------------+ Getting Started =============== Prerequisites ------------- To use AI Agents, you need: .. code-block:: text Requirements: ☑ Active user account with appropriate permissions ☑ AWS Bedrock access (configured by administrator) ☑ Modern web browser with JavaScript enabled ☑ WebSocket support (all modern browsers) Accessing AI Features --------------------- .. figure:: _static/screenshots/ai_access_menu.png :alt: AI Features Access :align: center :width: 100% *Screenshot Placeholder: Navigation menu highlighting AI features - Calculator with "Chat Mode" toggle, Rating History with "Explain" buttons, Bulk Rating menu item* AI features are integrated throughout the application: 1. **Explanation Agent**: * Click "Explain This Quote" on any completed rating * Available in Rating History detail pages * Works with successful and warning-status ratings 2. **Rating Agent**: * Access via "Chat Mode" in Calculator * New menu item: "AI Quote Assistant" * Mobile-friendly interface 3. **Bulk Rating**: * Navigate to "Bulk Rating" in main menu * API endpoint: ``/api/rating/bulk-calculate/`` * Supports CSV upload and API integration User Permissions ---------------- .. table:: AI Agent Permissions :widths: 20 40 40 +------------------+---------------------------+----------------------------------+ | Role | Explanation Agent | Rating Agent | +==================+===========================+==================================+ | Viewer | Own ratings only | No access | +------------------+---------------------------+----------------------------------+ | Underwriter | All ratings | Full access | +------------------+---------------------------+----------------------------------+ | Product Manager | All ratings | Full access + bulk rating | +------------------+---------------------------+----------------------------------+ | Administrator | All ratings | Full access + bulk rating | +------------------+---------------------------+----------------------------------+ Quick Start Guide ================= Using the Explanation Agent ---------------------------- .. figure:: _static/screenshots/explanation_agent_quickstart.png :alt: Explanation Agent Quick Start :align: center :width: 100% *Screenshot Placeholder: Step-by-step guide - 1) Complete a rating, 2) Click "Explain This Quote", 3) Ask questions in chat, 4) Receive plain-language answers* 1. Complete a rating calculation 2. Navigate to the rating run detail page 3. Click **Explain This Quote** button 4. Read the automatic explanation 5. Ask follow-up questions in the chat **Example Questions:** .. code-block:: text • "Why is my premium this amount?" • "How did the territory factor affect the price?" • "What would happen if I increased the deductible?" • "Explain the building class rating" Using the Rating Agent ---------------------- .. figure:: _static/screenshots/rating_agent_quickstart.png :alt: Rating Agent Quick Start :align: center :width: 100% *Screenshot Placeholder: Conversational flow - User says "I need a quote for my business" → Agent asks about product type → Collects information → Calculates premium* 1. Click **Chat Mode** or **AI Quote Assistant** 2. Tell the agent what you need: *"I need a quote for my business"* 3. Answer the agent's questions naturally 4. Review collected information 5. Confirm and calculate premium **Example Conversation:** .. code-block:: text User: "I need a BOP quote" Agent: "I'll help you with that! What's your territory code?" User: "Downtown Chicago" Agent: "That's territory 14. What's your building's square footage?" User: "About 5000" Agent: "Perfect! Next, what's your business classification?" Using Bulk Rating ----------------- .. figure:: _static/screenshots/bulk_rating_quickstart.png :alt: Bulk Rating Quick Start :align: center :width: 100% *Screenshot Placeholder: Bulk rating interface - Upload CSV → Configure options → Monitor progress → Download results* 1. Prepare a CSV file or JSON data with rating requests 2. Navigate to **Bulk Rating** → **Upload** 3. Upload your file or paste JSON 4. Configure options (webhooks, notifications) 5. Monitor progress in real-time 6. Download results when complete See :doc:`bulk_rating` for detailed instructions. Best Practices ============== Explanation Agent Tips ---------------------- Get better explanations: * **Be specific**: Ask about particular factors, coverages, or calculations * **Follow up**: Ask "why" to get deeper explanations * **Request examples**: Ask "what if" questions to understand scenarios * **Clarify terms**: If you don't understand, ask the agent to explain Example interactions: .. code-block:: text Good: "Why did the brick construction reduce my premium?" Better: "How much did brick construction save compared to wood frame?" Good: "Explain the territory factor" Better: "Why is territory 14 more expensive than territory 01?" Rating Agent Tips ----------------- Optimize conversations: * **Be natural**: Talk normally, the agent understands context * **Provide details**: More information = faster quote * **Correct mistakes**: Say "actually" or "change" to update * **Review before calculating**: Confirm all details are correct Example corrections: .. code-block:: text Agent: "You said 500 square feet, correct?" User: "Actually, that's 5000 square feet" Agent: "Updated! 5,000 square feet." Bulk Rating Tips ---------------- Maximize efficiency: * **Validate data**: Check your data before upload * **Use templates**: Download and modify sample templates * **Monitor progress**: Watch the real-time progress indicator * **Review errors**: Check error logs for failed ratings * **Use webhooks**: Get notified when large jobs complete Security and Privacy ==================== Data Protection --------------- .. figure:: _static/screenshots/ai_security_features.png :alt: AI Security Features :align: center :width: 100% *Screenshot Placeholder: Security diagram showing encrypted WebSocket, user authentication, session isolation, and no conversation storage* AI agent security features: * **Encrypted Communication**: All WebSocket connections use TLS * **Authentication Required**: Must be logged in to access agents * **Authorization Checks**: Can only access your own data * **Session Isolation**: Each conversation is independent * **No Storage**: Conversations are not saved (only ratings) * **Audit Trail**: All rating calculations are logged Data Handling ------------- What the AI sees: .. table:: AI Agent Data Access :widths: 30 70 +---------------------+------------------------------------------------------------+ | Data Type | Access | +=====================+============================================================+ | Rating Data | Full access to calculation inputs and outputs | +---------------------+------------------------------------------------------------+ | User Information | Name and ID only (no contact info) | +---------------------+------------------------------------------------------------+ | Product Config | Factor definitions, tables, formulas | +---------------------+------------------------------------------------------------+ | Conversations | Not stored; ephemeral session only | +---------------------+------------------------------------------------------------+ | Other Users' Data | No access (except staff/superusers) | +---------------------+------------------------------------------------------------+ Limitations and Considerations =============================== Current Limitations ------------------- Be aware of these limitations: .. table:: AI Agent Limitations :widths: 30 70 +------------------------+----------------------------------------------------------+ | Limitation | Details | +========================+==========================================================+ | Calculation Accuracy | Agent explains results; doesn't change calculations | +------------------------+----------------------------------------------------------+ | Product Knowledge | Limited to configured products only | +------------------------+----------------------------------------------------------+ | Historical Data | Can only access ratings you created or can view | +------------------------+----------------------------------------------------------+ | Complex Scenarios | May need multiple clarifying questions | +------------------------+----------------------------------------------------------+ | Language Support | English only (currently) | +------------------------+----------------------------------------------------------+ Response Accuracy ----------------- AI agent responses are: * **Factual**: Based on actual rating data and configuration * **Consistent**: Use the same formulas and tables as the rating engine * **Helpful**: Designed to explain, not to sell or persuade * **Limitations**: May occasionally need clarification or correction .. note:: If an agent's explanation seems incorrect, please report it to your administrator. The agent learns from configuration data, and errors may indicate a configuration issue. Cost Considerations ------------------- .. figure:: _static/screenshots/ai_cost_tracking.png :alt: AI Cost Tracking :align: center :width: 100% *Screenshot Placeholder: Admin dashboard showing AI usage metrics - conversations per day, average tokens per conversation, estimated cost* AI usage costs: * **Per Conversation**: ~$0.01-$0.03 average * **Bulk Rating**: Negligible per rating (~$0.001) * **Enterprise Plan**: Usage tracked and billed monthly * **Cost Controls**: Administrators can set usage limits Troubleshooting =============== Common Issues ------------- .. table:: AI Agent Troubleshooting :widths: 30 70 +---------------------------+-------------------------------------------------------+ | Issue | Solution | +===========================+=======================================================+ | Chat won't connect | Check internet connection, try refreshing page | +---------------------------+-------------------------------------------------------+ | Agent not responding | Wait 10-15 seconds; may be processing | +---------------------------+-------------------------------------------------------+ | Explanation unclear | Ask for clarification or examples | +---------------------------+-------------------------------------------------------+ | Can't access AI features | Check user permissions with administrator | +---------------------------+-------------------------------------------------------+ | Bulk job stuck | Check job status in Bulk Rating dashboard | +---------------------------+-------------------------------------------------------+ Getting Help ------------ For AI agent issues: * **In-App Help**: Click "?" icon in chat window * **Support Email**: ai-support@tigerrating.com * **Documentation**: Read detailed agent guides * **Training**: Request AI agent training from your administrator Next Steps ========== Learn more about specific AI features: .. toctree:: :maxdepth: 2 explanation_agent rating_agent bulk_rating performance_optimization Recommended reading order: 1. **Explanation Agent**: :doc:`explanation_agent` - Understand premium calculations 2. **Rating Agent**: :doc:`rating_agent` - Conversational quoting 3. **Bulk Rating**: :doc:`bulk_rating` - High-volume processing .. tip:: Start with the Explanation Agent to understand how premiums are calculated, then move to the Rating Agent for creating new quotes. .. warning:: AI agents are tools to assist underwriters and should not replace professional judgment. Always review calculated premiums for appropriateness.