Multi-Agent Matchmaking System

LLM-powered multi-agent system for organizing football matches. Uses geographic clustering and conversational agents to create balanced teams based on skill, availability, and preferences.

Software Architecture

Pattern: Supervised Execution (Orchestrator-Worker)

The system implements an orchestrator-worker pattern where:

• Orchestrator: CoordinatorAgent supervises and coordinates matchmaking
• Workers: UserAgent instances execute delegated tasks (answering questions)
• Pipeline: main.py orchestrates the overall workflow

main.py (Pipeline Orchestrator)
  └─> CoordinatorAgent (Orchestrator)
       ├─> Organizes matches via LLM
       ├─> Validates match plans
       └─> Delegates to UserAgent (Workers)
            └─> Answer questions, provide user info

Components

CoordinatorAgent (Orchestrator)

• Receives clustered users
• Uses LLM to organize matches (teams, scheduling)
• Validates match plans
• Tools: ask_question, success_match, fail_match

UserAgent (Worker)

• Created on-demand per user
• Responds to coordinator's questions
• Tools: send_notification, answer_polling

Installation

python -m venv myenv
source myenv/bin/activate
pip install -r requirements.txt

Create .env:

OPENAI_KEY=your_api_key
SERVER_URL=http://localhost:3000  # Optional

Usage

python main.py

Programmatic:

from src.coordinator_agent import CoordinatorAgent

coordinator = CoordinatorAgent()
coordinator.provide_users(users)
result, match_setup = coordinator.run(num_people=10, slot=(None, None))

Workflow

1. Fetch users from API → 2. K-means clustering → 3. For each cluster:
   • Fetch users within 15km
   • CoordinatorAgent organizes match
   • Validates & creates match via API
2. Loop every 5 seconds

Project Structure

agent/
├── main.py                 # Pipeline entry point
├── src/
│   ├── coordinator_agent.py  # Orchestrator
│   ├── user_agent.py         # Worker agents
│   ├── database.py           # API client
│   └── user.py               # Data models
├── data_processing/
│   └── cluster_for_users.py  # K-means clustering
├── utils/utils.py           # Enums & models
└── tests/                    # Test suite

Dependencies

• langchain-openai, langchain-classic, langchain - LLM framework
• pydantic - Data validation
• scikit-learn, numpy - Clustering
• requests - API client
• python-dotenv - Environment config

Configuration

Environment Variables:

• OPENAI_KEY (required) - LLM API key
• SERVER_URL (optional) - Backend API URL

Parameters (main.py):

• num_people: Players per match (default: 10)
• people_per_cluster: Users per cluster (default: 40)
• max_clusters: Max clusters (default: 15)
• radius_km: Search radius (default: 15km)

Data Models

User:

{
    "user_id": str,
    "age": int,
    "skill_level": int,
    "position": str,
    "location": {"latitude": float, "longitude": float},
    "calendar": {"YYYY-MM-DD": ["HH:MM", ...]}
}

Match Plan:

{
    "teams": [{"team_id": str, "players": [...]}],  # Exactly 2 teams
    "pitch": str,
    "date": "YYYY-MM-DD",
    "time": "HH:MM",
    "match_possible": bool,
    "needs_alternative_slot": bool
}

Testing

python tests/Coordinator_test.py
python tests/UserAgent_test.py

Troubleshooting

• API Key Error: Ensure .env has OPENAI_KEY
• No Users: Check SERVER_URL or use mock_data/users.json
• Validation Failures: Ensure exactly 2 teams, valid player IDs, correct date/time format