Mercadinho Mercantes Multi-Agent AI Assistant

Mercadinho Mercantes - Multi-Agent AI Assistant

A sophisticated multi-agent AI system for Mercadinho Mercantes, a Brazilian retail chain. This system provides intelligent customer service through multiple specialized AI agents that can handle product inquiries, sales assistance, customer management, and store operations.

🏪 About Mercadinho Mercantes

Mercadinho Mercantes is a proud Brazilian retail company with multiple locations across São Paulo and Rio de Janeiro. Our AI assistant system enhances customer experience by providing personalized product recommendations, promotional information, and seamless appointment scheduling.

✨ Features

🤖 Multi-Agent Architecture

• Reception Agent: Welcomes customers and directs them to appropriate services
• Sales Agent: Handles product inquiries, recommendations, and sales assistance
• Customer Maintenance Agent: Manages existing customer accounts and special discounts

🛍️ Core Functionality

• Product Catalog: Browse available products with pricing and inventory
• Store Information: Find store locations and contact details
• Promotional System: Access store-specific promotions and discounts
• Customer Management: Track customer profiles and loyalty benefits
• Appointment Scheduling: Book store visits and product reservations
• Special Discounts: Exclusive offers for registered customers

🛠️ Technical Features

• MCP Integration: Model Context Protocol for tool calling
• Streamlit UI: Modern, responsive web interface
• Real-time Chat: Interactive conversation with AI agents
• Tool Visualization: Transparent view of AI tool usage
• Session Management: Persistent conversation history

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• OpenAI API key
• Git

Installation

1. Clone the repository
   git clone <repository-url> cd mcp_mercadinho
2. Install dependencies
   pip install -r requirements.txt
3. Set up environment variables
   export OPENAI_API_KEY="your_openai_api_key_here"
   Or create a .env file:
   echo "OPENAI_API_KEY=your_openai_api_key_here" > .env

Running the Application

1. Start the MCP server (in one terminal):
   mcp run server.py --transport sse
2. Launch the Streamlit client (in another terminal):
   streamlit run chat_multi_agent_client.py
3. Open your browser and navigate to the URL shown in the Streamlit output (typically http://localhost:8501)

🏗️ Architecture

System Components

Agent Roles

Reception Agent (RecepcaoAssistente)

• Purpose: Initial customer contact and routing
• Responsibilities:
  • Welcome customers to Mercadinho Mercantes
  • Present company information and website
  • Route customers to appropriate specialized agents
  • Handle general inquiries

Sales Agent (VendasAssistente)

• Purpose: Product sales and recommendations
• Responsibilities:
  • Show available products and inventory
  • Provide product recommendations
  • Handle promotional offers
  • Schedule store visits
  • Process sales inquiries

Customer Maintenance Agent (ManutencaoSocioAssistente)

• Purpose: Existing customer support and loyalty management
• Responsibilities:
  • Verify customer membership status
  • Apply special discounts for members
  • Handle product reservations
  • Manage customer accounts

Available Tools (MCP Functions)

📊 Data Structure

Products

• Categories: Hortifruit, Electronics
• Information: ID, name, category, price, quantity
• Examples: Bananas, Apples, PlayStation 5, LED TV

Stores

• Locations: São Paulo (Parelheiros, Mooca), Guarujá, Santo André, Rio de Janeiro (Ipanema, Nova Iguaçu)
• Information: ID, name, city, state

Customers

• Types: Regular customers, Members (with special discounts)
• Information: ID, name, associated store, discount eligibility

🎯 Usage Examples

Product Inquiry

Store Visit Scheduling

Customer Discount Check

🔧 Configuration

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key for GPT-4 access

Model Settings

• Model: GPT-4-1106-preview
• Temperature: 0 (deterministic responses)
• Tool Choice: Auto
• Parallel Tool Calls: Disabled

🛡️ Security Considerations

• API keys should be stored securely in environment variables
• Never commit API keys to version control
• Use .env files for local development
• Consider implementing rate limiting for production use

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Check the Issues page
• Contact the development team
• Visit Mercadinho Mercantes

🔮 Future Enhancements

• Integration with real inventory systems
• Payment processing capabilities
• Multi-language support (Portuguese/English)
• Mobile app development
• Advanced analytics and reporting
• Integration with CRM systems

Built with ❤️ for Mercadinho Mercantes