Multi Agent Lab

🚀 Multi-Agent Lab 🤖

This project is developed for educational and demonstrative purposes, aiming to illustrate the fundamental concepts of multi-agent systems using the Google ADK (Agent Development Kit).

🚀 Quick Start

This project is exclusively developed for educational and demonstrative purposes, aiming to illustrate the fundamental concepts of multi-agent systems using the Google ADK (Agent Development Kit).

⚠️ IMPORTANT: This is NOT a production example! It's a teaching lab to understand:

• How to implement hierarchical agent architectures
• Integration between specialized agents
• Use of the MCP (Model Context Protocol)
• Execution of tools by AI agents
• Coordination among multiple language models

✨ Features

System Architecture Overview

The system simulates an e-commerce with health consultation, where different specialized agents work together to serve the customer.

Root Agent (Main Coordinator)
├── Shop Mate (Product Specialist)
│   └── Help Customer (MCP Interface)
├── Seller Agent (Sales Specialist)
│   ├── Create Order (Order Creation)
│   ├── Billing (Invoicing)
│   └── Manage Stock (Inventory Management)
└── Health Mate (Health Consultant)
    ├── Nutra Specialist (Nutrition/Skin Specialist)
    └── Workout Specialist (Exercise Specialist)

Implemented Components

1. Vitra AI (Main System)

• Root Agent: The main coordinator that delegates tasks to sub-agents
• Specialized prompts: Specific instructions for each agent
• Various models: Gemini, Claude, and Llama via LiteLLM

2. Search MCP Server (Tool Server)

• Product search: Interface with the search system (MeiliSearch)
• Payment plans: Simulation of financing options
• Logging: Recording of all operations for auditing

3. Specialized Sub-Agents

Shop Mate

• Function: Product recommendation and search
• Tools: Access to the MCP server for queries
• Model: Claude 3.5 Sonnet

Seller Agent

• Function: Complete order processing
• Sub-agents:
  • Create Order: Order creation and management
  • Billing: Invoice generation
  • Manage Stock: Inventory control
• Tools: Custom e-commerce functions

Health Mate

• Function: Health and well-being consultation
• Sub-agents:
  • Nutra Specialist: Skin and nutrition care
  • Workout Specialist: Exercise and training tips
• Models: Gemini 2.5 Flash and Llama 3.1 8B

📦 Installation

Prerequisites

• Python 3.13+
• UV (Python package manager)
• MeiliSearch running on port 7700 (optional - see alternatives below)

1. Install Dependencies

# Clone the repository
git clone <your-repository>
cd multi_agent_lab

# Install main system dependencies
cd vitra_ai
uv sync

# Install MCP server dependencies
cd ../search_mcp_server
uv sync

2. Configure Models

Make sure you have the API keys configured:

# For Claude (Anthropic)
export ANTHROPIC_API_KEY="your-key-here"

# For Gemini (Google)
export GOOGLE_API_KEY="your-key-here"

# For Ollama (local)
# Install Ollama and download the llama3.1:8b model
ollama pull llama3.1:8b

3. Run the System

Option 1: With MeiliSearch (Full)

# Terminal 1: Start MeiliSearch
docker run -it --rm -p 7700:7700 getmeili/meilisearch:v1.5

# Terminal 2: Run the MCP server
cd search_mcp_server
uv run help_customer.py

# Terminal 3: Run the main system
cd vitra_ai
uv run agent.py

Option 2: Without MeiliSearch (Simulated)

# Just the main system (with mocked data)
cd vitra_ai
uv run agent.py

4. Test with ADK Web Interface

To test the system using the ADK web interface:

# 1. First, install the dependencies
cd vitra_ai
uv sync

# 2. Activate the virtual environment
source .venv/bin/activate

# 3. Return to the project root folder
cd ..

# 4. Run the ADK web (should be run one level above the project folder)
adk web

Important: The adk web command should always be run in a folder that is the parent of the project folder, not inside the project folder itself.

💻 Usage Examples

Basic Usage

The basic usage of this project is to understand and experiment with multi - agent systems. You can start the system as described in the installation section and interact with it using the ADK web interface.

Advanced Usage

You can customize the system by following the instructions in the "Customizing the MCP Server" section. For example, you can replace MeiliSearch with other data sources.

🔧 Technical Details

Customizing the MCP Server

Alternatives to MeiliSearch

The search_mcp_server/help_customer.py file can be easily modified to use other data sources:

1. Local JSON File

import json

@mcp.tool()
def search_products_by_terms(terms: str):
    with open("products.json", "r") as f:
        products = json.load(f)
    # Implement simple term search
    results = [p for p in products if terms.lower() in p['name'].lower()]
    return {"hits": results}

2. External REST API

@mcp.tool()
def search_products_by_terms(terms: str):
    # Example with a product API
    response = requests.get(f"https://api.mercadolibre.com/sites/MLB/search?q={terms}")
    return response.json()

3. SQLite Database

import sqlite3

@mcp.tool()
def search_products_by_terms(terms: str):
    conn = sqlite3.connect("products.db")
    cursor = conn.execute("SELECT * FROM products WHERE name LIKE ?", (f"%{terms}%",))
    results = cursor.fetchall()
    conn.close()
    return {"hits": results}

4. Elasticsearch

from elasticsearch import Elasticsearch

es = Elasticsearch([{'host': 'localhost', 'port': 9200}])

@mcp.tool()
def search_products_by_terms(terms: str):
    response = es.search(
        index="products",
        body={"query": {"match": {"name": terms}}}
    )
    return response

Project Structure

multi_agent_lab/
├── vitra_ai/                    # Main agent system
│   ├── agent.py                 # Root agent configuration
│   ├── prompt.py                # Prompts and instructions
│   ├── sub_agents/              # Specialized agents
│   │   ├── shop_mate/           # Product specialist
│   │   ├── seller/              # Sales specialist
│   │   └── health_mate/         # Health consultant
│   ├── vitra_doc/               # System logs
│   └── pyproject.toml           # Dependencies
├── search_mcp_server/           # MCP tool server
│   ├── help_customer.py         # Tool implementation
│   ├── log/                     # Operation logs
│   └── pyproject.toml           # Dependencies
└── README.md                    # This file

Demonstrated Concepts

1. Agent Hierarchy

• How to organize agents in a hierarchical structure
• Task delegation among specialized agents
• Coordination of multiple subsystems

2. MCP Protocol

• Implementation of external tools
• Communication between agents and services
• Logging and auditing of operations

3. Multi - Model Integration

• Simultaneous use of different LLMs
• Task - specific specialization
• Agent - specific parameter configuration

4. Custom Tools

• Creation of domain - specific tools
• Data persistence in files
• Simulation of external systems

Experimentation and Learning

Suggested Modifications

1. Add new agents: Create a customer service agent
2. Implement new tools: Add integration with real APIs
3. Experiment with models: Test other LLMs or adjust parameters
4. Improve logging: Implement structured JSON logging
5. Add validation: Implement data validation between agents

Points to Note

• Hardcoded paths: The paths are fixed, adapt them to your environment
• Authentication: Tokens are exposed for teaching purposes
• Error handling: Minimal implementation, suitable only for demonstration
• Performance: Not optimized for production

📚 Documentation

Additional Resources

• Google ADK Documentation
• MCP Protocol Specification
• LiteLLM Documentation

Contributions

This is an educational project! Feel free to:

• Fork and experiment
• Suggest educational improvements
• Add usage examples
• Report bugs or inconsistencies

⚠️ Important Note

This project is a learning tool. Use it to understand concepts, experiment with modifications, and adapt it to your educational needs! 🚀