| --- |
| title: Smart Customer Support Agent |
| emoji: 💬 |
| colorFrom: yellow |
| colorTo: purple |
| sdk: gradio |
| sdk_version: 5.33.0 |
| app_file: app.py |
| pinned: false |
| license: mit |
| short_description: Agentic retrieval & smart routing for customer support |
| tags: |
| - agent-demo-track |
| - llamaindex |
| - llamacloud |
| - rag |
| - agentic-retrieval |
| - smart-routing |
| - customer-service |
| - chatbot |
| - claude |
| - anthropic |
| - cohere-embed |
| --- |
| |
| # 💬 Smart Customer Support Triage Agent |
|
|
| An intelligent customer support system powered by LlamaIndex, Anthropic Claude and Gradio, featuring agentic routing and smart document retrieval across multiple knowledge bases. |
|
|
| > [!IMPORTANT] |
| > This project earned [Agent Track Honorable Mention](https://www.gradio.app/hackathon-winners) in “Gradio Agents & MCP Hackathon 2025”. Thank you so much! 🥹🙏❤️ |
|
|
| ## 🔮 Live Demo |
|
|
| Try the chatbot: **[https://huggingface.co/spaces/karenwky/cs-agent](https://huggingface.co/spaces/karenwky/cs-agent)** |
|
|
| _\* Llama-3.1-405B-Instruct supported by Nebius AI Studio is used as the LLM in live demo._ |
|
|
| ## 📹 Preview |
|
|
| <video controls autoplay src="https://huggingface.co/proxy/cdn-uploads.huggingface.co/production/uploads/67d2db58176fdb283211e929/VZv-vBdGfYTsyD-3LuJYC.mp4"></video> |
|
|
| ## 🚀 Technologies Used |
|
|
| - **LLM**: Anthropic Claude Sonnet 4.0 for natural language understanding and generation |
| - **RAG Framework**: LlamaIndex for agent framework and intelligent query routing |
| - **Cloud Platform**: LlamaCloud for document parsing & indexng, managed vector database |
| - **UI Framework**: Gradio for interactive web interface |
| - **Observability**: LlamaTrace (Arize Phoenix) for LLM tracing and monitoring |
| - **Language**: Python 3.12 |
| - **Document Types**: PDF, PPTX, CSV support |
| - **Coding Assistance**: Gemini 2.5 Flash |
| - **Synthetic Data**: Grok Chat, Slidesgo for sample knowledge base generation |
|
|
| ## 📁 Project Structure |
|
|
| ``` |
| cs-agent/ |
| ├── app.py # Main application logic |
| ├── requirements.txt # Python dependencies |
| ├── logo.png # Chatbot avatar image |
| └── data/ # Sample knowledge base |
| ├── ProductManuals/ # Product documentation |
| ├── FAQGeneralInfo/ # FAQ and general information |
| ├── BillingPolicy/ # Billing and payment policies |
| └── CompanyIntroductionSlides/ # Company overview |
| ``` |
|
|
| ## 🔄 Architecture & Workflow |
|
|
| <img src="https://huggingface.co/proxy/cdn-uploads.huggingface.co/production/uploads/67d2db58176fdb283211e929/U3hKTIcnfrSE3ErjuFE8U.png" |
| alt="Architecture & Workflow Diagram" width="1000" /> |
|
|
| ## ✨ Key Features |
|
|
| ### 🎯 **Agentic Routing** |
| - Intelligent query classification and routing to appropriate knowledge bases |
| - Composite retrieval with automatic reranking |
| - Context-aware document selection based on query intent |
|
|
| ### 🧠 **Metadata Awareness** |
| - Extracts and utilizes document metadata (e.g., author, creation date, modification date) |
| - File-specific information retrieval from document properties |
| - Enhanced context understanding through metadata integration |
|
|
| ### 🔄 **Automatic Version Control** |
| - Tracks document versions automatically (e.g., `late_payment_policy_v2.pdf`) |
| - Maintains historical document access |
| - Version-aware responses for policy and procedure queries |
|
|
| ### 💾 **Memory Management** |
| - Persistent chat memory with token limit |
| - Context preservation across conversation turns |
| - Condensed question generation for better retrieval |
|
|
| ### 📊 **Observability** |
| - Real-time LLM tracing with Arize Phoenix |
| - Retrieval performance monitoring |
| - Source attribution and scoring visibility |
|
|
| ## 🚀 Quick Start |
|
|
| ### Prerequisites |
| - Python 3.8+ |
| - LlamaCloud API key |
| - Anthropic API key |
| - (Optional) Arize Phoenix API key |
|
|
| ### Installation |
|
|
| 1. **Clone the repository** |
| ```bash |
| git clone https://github.com/karenwky/cs-agent |
| cd cs-agent |
| ``` |
|
|
| 2. **Install dependencies** |
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| 3. **Set environment variables** |
| ```bash |
| export ANTHROPIC_API_KEY="your-anthropic-api-key" |
| export LLAMA_CLOUD_API_KEY="your-llamacloud-api-key" |
| |
| # Optional: For Phoenix tracing |
| export PHOENIX_PROJECT_NAME="your-phoenix-project" |
| export PHOENIX_API_KEY="your-phoenix-api-key" |
| ``` |
|
|
| 4. **Set up LlamaCloud indices** |
| - Create a project named `CustomerSupportProject` in LlamaCloud |
| - Upload documents to create these indices: |
| - `ProductManuals` |
| - `FAQGeneralInfo` |
| - `BillingPolicy` |
| - `CompanyIntroductionSlides` |
|
|
| 5. **Launch the application** |
| ```bash |
| python app.py |
| ``` |
|
|
| ## 🗣️ Sample Questions |
|
|
| ### 📚 **Product Manual Queries** |
| - "Help! No response from the app, I can't do anything. What should I do?" |
| - "What are the procedures to set up task automation?" |
| - "How can your software help team collaboration?" |
| - "Who is the author of the product manual and when is the last modified date?" |
|
|
| ### ❓ **General FAQ & Company Info** |
| - "Who are the founders of this company? What are their backgrounds?" |
| - "Is your company environmentally friendly?" |
| - "What kind of technical detail can I expect for sustainability questions?" |
|
|
| ### 💰 **Billing & Policy Questions** |
| - "I got a $200 invoice outstanding for 45 days. How much is the late charge?" |
| - "What is your latest late payment policy?" |
| - "If I enable auto-pay but my payment method expires, will I get notified?" |
| - "Does the 14-day refund policy refer to calendar days or business days?" |
|
|
| ### 🔧 **Complex Multi-Domain Queries** |
| - "If I sign up for annual 'Pro' subscription with 10% discount but cancel after 20 days, what exact refund amount considering the 14-day policy?" |
| - "For multi-user discounts, if I add a 5th user mid-cycle, when does the 10% discount apply and how is prorating calculated?" |
|
|
| ## 🔮 Potential Enhancements |
|
|
| ### 🎯 **Advanced AI Capabilities** |
| - **Multi-modal Support**: Add image and video processing for visual troubleshooting guides |
| - **Voice Integration**: Implement speech-to-text and text-to-speech for accessibility |
| - **Sentiment Analysis**: Detect customer frustration levels and escalate appropriately |
| - **Predictive Analytics**: Anticipate customer needs based on interaction patterns |
|
|
| ### 🔧 **Technical Improvements** |
| - **Streaming Responses**: Implement real-time response streaming for better UX |
| - **Caching Layer**: Add Redis/Memcached for frequently accessed information |
| - **API Gateway**: Create RESTful APIs for integration with existing support systems |
| - **Containerization**: Docker support for easy deployment and scaling |
|
|
| ### 📊 **Analytics & Monitoring** |
| - **Custom Dashboards**: Build comprehensive analytics for support metrics |
| - **A/B Testing**: Framework for testing different response strategies |
| - **Performance Metrics**: Track response accuracy, user satisfaction, and resolution rates |
| - **Automated Quality Assurance**: Implement response quality scoring and feedback loops |
|
|
| ### 🔐 **Security & Compliance** |
| - **Authentication System**: User management and role-based access control |
| - **Data Encryption**: End-to-end encryption for sensitive customer data |
| - **Audit Logging**: Comprehensive logging for compliance and security monitoring |
| - **GDPR Compliance**: Data privacy controls and user data management |
|
|
| ### 🌐 **Integration & Scalability** |
| - **CRM Integration**: Connect with Salesforce, HubSpot, or other CRM systems |
| - **Ticketing System**: Integration with Zendesk, Jira Service Management |
| - **Multi-language Support**: Internationalization for global customer base |
| - **Load Balancing**: Horizontal scaling for high-traffic scenarios |
|
|
| ### 🤖 **Advanced Agent Capabilities** |
| - **Tool Integration**: Connect with external APIs and services |
| - **Workflow Automation**: Automated ticket creation and routing |
| - **Escalation Logic**: Smart human handoff based on complexity scoring |
| - **Learning System**: Continuous improvement from customer interactions |
|
|
| ## 🙏 Acknowledgments |
|
|
| - [RAG is dead, long live agentic retrieval — LlamaIndex](https://www.llamaindex.ai/blog/rag-is-dead-long-live-agentic-retrieval) |
| - [LlamaCloudIndex + LlamaCloudRetriever - LlamaIndex](https://docs.llamaindex.ai/en/stable/module_guides/indexing/llama_cloud_index/) |
| - [Condense plus context - LlamaIndex](https://docs.llamaindex.ai/en/stable/api_reference/chat_engines/condense_plus_context/) |
| - [LlamaIndex | Phoenix](https://arize.com/docs/phoenix/tracing/integrations-tracing/llamaindex#setup) |
|
|
| ## 📝 License |
|
|
| This project is licensed under the MIT License. |
