A production-ready, industry-grade multi-agent system for automating business operations at Munder Difflin Paper Company. This project demonstrates advanced software engineering practices combined with modern agentic AI patterns.
This system coordinates four specialized AI agents to handle:
- Inventory Management: Stock monitoring, reorder decisions, supplier coordination
- Quote Generation: Pricing calculations, bulk discounts, historical analysis
- Order Fulfillment: Order processing, inventory allocation, transaction recording
- Orchestration: Workflow coordination, intent routing, customer communication
- 🤖 Multi-Agent Architecture: Specialized agents with clear responsibilities
- 🔄 Workflow Orchestration: Seamless coordination between agents
- 💾 Database Management: SQLAlchemy ORM with Alembic migrations
- 🌐 REST API: FastAPI with automatic OpenAPI documentation
- 📊 Financial Reporting: Real-time cash balance and inventory valuation
- 🔍 Historical Analysis: Quote history search and pricing guidance
- ⚡ Caching Layer: Redis for performance optimization
- 🔄 Background Jobs: Celery for async processing
- 📈 Observability: Structured logging, metrics, and tracing
- 🧪 Comprehensive Testing: Unit, integration, and e2e tests
- 🐳 Containerization: Docker and Docker Compose setup
- 🔐 Security: Rate limiting, API authentication, secrets management
┌─────────────────────────────────────────────────────────────────┐
│ API Gateway Layer │
│ (FastAPI REST API) │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Agent Orchestration Layer │
│ (Orchestrator + Specialized Agents) │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Business Logic Layer │
│ (Services, Repositories, Domain Models) │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Data Access Layer │
│ (SQLAlchemy ORM + Alembic) │
└─────────────────────────────────────────────────────────────────┘
For detailed architecture documentation, see docs/architecture/system-design.md.
- Python 3.11+
- uv (recommended) or pip
- Redis (optional, for caching)
- PostgreSQL (optional, SQLite works for development)
# Clone the repository
git clone https://github.com/yourusername/multi-agent-system.git
cd multi-agent-system
# Install dependencies
make setup
# Configure environment
cp .env.example .env
# Edit .env with your settings (especially OPENAI_API_KEY)
# Initialize database
make init-db
# Seed with sample data
make seed# Start the API server
make run
# In another terminal, start the worker (optional)
make run-worker
# API will be available at http://localhost:8000
# API docs at http://localhost:8000/docs# Build and start all services
make docker-up
# View logs
make docker-logs
# Stop services
make docker-down- 📖 Implementation Plan - Detailed roadmap and learning guide
- 🏛️ Architecture - System design and patterns
- 🤖 Agent Design - Agent communication patterns
- 💾 Database Schema - Data model documentation
- 🌐 API Design - API specifications
- 🚢 Deployment Guide - Production deployment
- 🧪 Testing Guide - Testing strategies
- 👩💻 Development Guide - Development best practices
# Run all tests
make test
# Run with coverage
make test-cov
# Run specific test types
make test-unit
make test-integration
make test-e2e
# Run type checks
make typecheck
# Run linting
make lintmulti-agent-system/
├── src/multi_agent_system/ # Main application code
│ ├── api/ # FastAPI application
│ ├── agents/ # Agent implementations
│ ├── core/ # Core utilities
│ ├── database/ # Database layer
│ ├── domain/ # Domain models
│ ├── services/ # Business logic
│ └── utils/ # Utility functions
├── tests/ # Test suite
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # End-to-end tests
├── docs/ # Documentation
├── docker/ # Docker configuration
├── scripts/ # Utility scripts
└── pyproject.toml # Project configuration
This project demonstrates:
- Architecture Patterns: Layered architecture, repository pattern, dependency injection
- API Design: RESTful principles, request/response modeling, error handling
- Database Design: ORM patterns, migrations, query optimization
- Testing Strategies: Unit, integration, and e2e testing with high coverage
- DevOps Practices: Containerization, CI/CD pipelines, monitoring
- Agent Design Patterns: Orchestrator pattern, specialized agents, tool use
- Prompt Engineering: System prompts, few-shot learning, chain-of-thought
- Agent Communication: Message passing, state management, workflow orchestration
- LLM Integration: API integration, error handling, cost optimization
make help # Show all available commands
make dev # Install dev dependencies
make run # Start API server
make test # Run tests
make format # Format code
make lint # Run linter
make typecheck # Run type checks
make docker-up # Start all services- Create agent class in
src/multi_agent_system/agents/ - Define agent tools in
src/multi_agent_system/agents/tools/ - Add prompts in
src/multi_agent_system/agents/prompts/ - Register agent in orchestrator
- Add tests in
tests/unit/test_agents/
See Development Guide for details.
- Original concept from Udacity AI Agents course
- Built with pydantic-ai
- Powered by FastAPI
Your Name - muhammadafaq1999@gmail.com
Project Link: https://github.com/mafaq229/multi-agent-system