Mercadinho Mercantes - Multi-Agent AI Assistant
A multi-agent AI system for Mercadinho Mercantes, a Brazilian retail chain. This system provides intelligent customer service through specialized AI agents that handle product inquiries, sales assistance, customer management, and store operations.
🏪 About Mercadinho Mercantes
Mercadinho Mercantes is a Brazilian retail company with multiple locations. This AI assistant system enhances customer experience by providing product recommendations, promotional information, and 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 customer accounts and special discounts
🛍️ Core Functionality
- Product catalog browsing
- Store information lookup
- Promotional system (store-specific)
- Customer management and loyalty benefits
- Appointment scheduling for store visits and product reservations
- Special discounts for registered customers
🛠️ Technical Features
- MCP (Model Context Protocol) integration for tool calling
- Streamlit UI for interactive chat
- Real-time chat with AI agents
- Tool usage visualization
- Session management
🚀 Quick Start
Prerequisites
- Python 3.8 or higher
- OpenAI API key
- Git
Installation
-
Clone the repository
git clone <repository-url> cd mcp_mercadinho -
Install dependencies
pip install -r requirements.txt -
Set up environment variables
export OPENAI_API_KEY="your_openai_api_key_here"Or create a
.envfile:echo "OPENAI_API_KEY=your_openai_api_key_here" > .env -
Database setup
- The application requires a pre-existing
loja_sistema.dbSQLite database with the correct schema. If you do not have this file, please request the schema or a setup script from the project maintainer. (The setup script is not included in this repository.)
- The application requires a pre-existing
Running the Application
-
Start the MCP server (in one terminal):
python server.py(By default, runs with stdio transport for local development.)
-
Launch the Streamlit client (in another terminal):
streamlit run chat_multi_agent_client.py -
Open your browser and navigate to the URL shown in the Streamlit output (typically
http://localhost:8501)
🏗️ Architecture
System Components
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Streamlit UI │◄──►│ Multi-Agent │◄──►│ MCP Server │
│ (Frontend) │ │ System │ │ (Backend) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ OpenAI GPT-4 │
│ (LLM Backend) │
└──────────────────┘
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 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)
| Tool | Description | Parameters |
|---|---|---|
get_produtos_disponiveis() | Retrieve available products | None |
get_lojas() | Get store locations and information | None |
get_categorias_produtos_promocao_por_loja(id_loja) | Get categories with promotions for a store | id_loja: int |
get_promocao_por_loja(id_loja) | Get product promotions for a store | id_loja: int |
get_info_cliente(cliente_id, nome) | Get customer information | cliente_id: int, nome: str |
reservar_pedido_com_desconto(id_loja, id_cliente, data_hora) | Reserve order with discount | id_loja: int, id_cliente: int, data_hora: str |
agenda_visita_para_compra(id_loja, data_hora) | Schedule store visit | id_loja: int, data_hora: str |
📊 Data Structure (Example)
Products
- Fields: produto_id, nome, descricao, categoria_id, valor
Stores
- Fields: loja_id, nome, cidade, estado, bairro
Customers
- Fields: cliente_id, nome, sobrenome, cliente_socio, cidade, estado, cep, rua, numero, bairro, complemento
🎯 Usage Examples
Product Inquiry
User: "What products do you have available?"
Agent: [Shows product catalog with prices and availability]
Store Visit Scheduling
User: "I want to visit a store to see the PlayStation 5"
Agent: [Finds nearest store, checks promotions, schedules visit]
Customer Discount Check
User: "My name is John Lennon, do I have any special discounts?"
Agent: [Verifies membership, applies special pricing]
🔧 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
.envfiles for local development - Consider implementing rate limiting for production use
🤝 Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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