agent_tracker/README.md

🤖 AgentHub

Modern AI Agent Management System with Advanced Analytics

AgentHub is a comprehensive, production-ready FastAPI application for managing AI agents across your organization. It provides role-based access control, usage analytics, dual authentication systems, and a modern responsive web interface.

✨ Key Features

🔐 Dual Authentication Systems

• Local Authentication: Traditional email/password with bcrypt hashing
• Azure AD Integration: Enterprise SSO with MSAL and PKCE flow
• JWT Token Management: Secure cookie-based sessions
• Role-Based Access Control: Admin and user permissions

🤖 Comprehensive Agent Management

• Full CRUD Operations: Create, read, update, delete AI agents
• Rich Metadata: Name, description, purpose, version, status, location, department, contact, tags, userbase, capabilities
• Status Tracking: Active, Development, Inactive, Deprecated
• User Ownership: Users can only edit their own agents (admins can edit all)
• Advanced Search: Full-text search across agent fields
• Real-time Filtering: Filter by status, sort by various criteria

📊 Usage Analytics & Monitoring

• Usage Tracking: Monitor agent usage patterns over time
• Interactive Charts: Chart.js visualizations with daily/weekly/monthly views
• Usage Statistics: Total usage, first/last usage tracking
• Date Range Filtering: Custom date range analysis
• Health Monitoring: Database connectivity and system health checks

👥 User Management

• User Registration: Self-service account creation
• Admin Interface: Comprehensive user management for administrators
• Profile Management: User profile editing and management
• Access Control: Fine-grained permission management

🎨 Modern Web Interface

• Responsive Design: Mobile-first Bootstrap 5 interface
• Modern UI/UX: Custom CSS with gradients, animations, and smooth transitions
• Interactive Components: Modals, dropdowns, tabs, and dynamic content
• Accessibility: ARIA labels and keyboard navigation support
• Dark Theme Support: CSS variables for easy theming

🔌 API Integration

• RESTful API: Complete REST API for all operations
• Agent Collector API: External system integration for automatic agent discovery
• OpenAPI Documentation: Auto-generated API docs with FastAPI
• Health Endpoints: System monitoring and diagnostics

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Interface │    │   REST API      │    │   External APIs │
│   (Bootstrap 5) │────│   (FastAPI)     │────│   (Collector)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
         ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
         │  Authentication │    │   Business      │    │   Data Layer    │
         │  (JWT + MSAL)   │────│   Logic         │────│   (MongoDB)     │
         └─────────────────┘    └─────────────────┘    └─────────────────┘

Technology Stack

• Backend: FastAPI (Python 3.8+)
• Database: MongoDB with Motor (async driver)
• Authentication: JWT + Azure AD/MSAL
• Frontend: Bootstrap 5 + Jinja2 templates
• Charts: Chart.js for analytics
• Deployment: Uvicorn + Systemd
• Security: bcrypt, python-jose, CSRF protection

🚀 Quick Start

1. Clone and Install

   git clone <repository-url>
   cd agent_app
   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

2. Configure Environment

   cp .env.example .env
   # Edit .env with your configuration
   

3. Start MongoDB

   # macOS with Homebrew
   brew services start mongodb-community
   
   # Linux with systemd
   sudo systemctl start mongod
   

4. Run Application

   uvicorn main:app --reload --port 8000
   

5. Access Application

   • Visit: http://localhost:8000
   • Default admin: admin@agenthub.com / admin123
   • Test user: test@example.com / testpass123

📋 Installation & Setup

Prerequisites

• Python 3.8+
• MongoDB 4.4+
• Git

Local Development Setup

1. Environment Setup

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

2. Environment Configuration Create .env file:

   # Database
   MONGODB_URI=mongodb://localhost:27017
   MONGODB_DBNAME=agenthub_db
   
   # Security
   SECRET_KEY=your-secret-key-here
   ALGORITHM=HS256
   ACCESS_TOKEN_EXPIRE_MINUTES=60
   
   # Local Development
   DISABLE_MSAL=true
   BASE_PATH=
   
   # Agent Collector API
   AGENT_COLLECTOR_API_KEY=your-api-key-here
   

3. Database Setup

   • Install and start MongoDB locally
   • No manual database creation needed (auto-created)

4. Create Admin User

   # Register via web interface first, then promote
   python make_admin.py admin@yourdomain.com
   

Production Setup

1. Azure AD Configuration (Optional)

   DISABLE_MSAL=false
   AZURE_CLIENT_ID=your-client-id
   AZURE_AUTHORITY=https://login.microsoftonline.com/your-tenant-id
   AZURE_REDIRECT_URI=https://your-domain.com/auth/azure/callback
   BASE_PATH=/your-app-path
   

2. Systemd Service

   sudo cp agenthub.service /etc/systemd/system/
   sudo systemctl enable agenthub
   sudo systemctl start agenthub
   

🎯 Usage

Agent Management

1. Create Agent: Navigate to "Register New Agent" and fill in details
2. View Agents: Use "All Agents" or "My Agents" views
3. Search & Filter: Use the search bar and status filters
4. Edit/Delete: Use action buttons (only for owned agents)
5. Usage Analytics: View detailed usage charts and statistics

User Management (Admin)

1. Access Admin Dashboard: Admin users see admin navigation
2. Manage Users: View, edit, activate/deactivate users
3. Promote Users: Grant admin privileges to users
4. Monitor System: View statistics and system health

Search & Discovery

• Global Search: Search across agents and users
• Advanced Filtering: Filter by status, department, tags
• Real-time Results: Instant search as you type

📚 API Documentation

Authentication Endpoints

POST /login          # Local authentication
GET  /auth/azure/login    # Azure AD login (if enabled)
GET  /auth/azure/callback # Azure AD callback
GET  /logout         # Logout and clear session

Agent API Endpoints

GET    /api/agents           # Get user's agents
GET    /api/agents/all       # Get all agents (for users)
POST   /api/agents           # Create new agent
GET    /api/agents/{id}      # Get specific agent
PUT    /api/agents/{id}      # Update agent
DELETE /api/agents/{id}      # Delete agent

Usage Analytics API

GET /api/agents/{name}/usage       # Get usage statistics
GET /api/agents/{name}/usage/chart # Get chart data

Admin API Endpoints

GET /api/admin/users        # Get all users
PUT /api/admin/users/{email} # Update user
GET /api/admin/agents       # Get all agents

Agent Collector API

POST /agents                # External agent registration
GET  /                      # Health check

API Usage Examples

Create Agent

curl -X POST "http://localhost:8000/api/agents" \
  -H "Content-Type: application/json" \
  -b "access_token=your-jwt-token" \
  -d '{
    "agent_name": "DataProcessor",
    "agent_description": "Processes customer data",
    "agent_purpose": "Data analysis and reporting",
    "agent_status": "Active",
    "agent_version": "1.2.0",
    "agent_department": "Analytics",
    "agent_capabilities": ["data-processing", "reporting"]
  }'

Get Usage Analytics

curl "http://localhost:8000/api/agents/DataProcessor/usage?start_date=2024-01-01&end_date=2024-12-31" \
  -b "access_token=your-jwt-token"

🔧 Configuration

Environment Variables

Variable	Default	Description
MONGODB_URI	mongodb://localhost:27017	MongoDB connection string
MONGODB_DBNAME	agenthub_db	Database name
SECRET_KEY	required	JWT secret key
ALGORITHM	HS256	JWT algorithm
ACCESS_TOKEN_EXPIRE_MINUTES	60	Token expiration time
DISABLE_MSAL	false	Disable Azure AD authentication
BASE_PATH	``	Application base path for reverse proxy
AZURE_CLIENT_ID	optional	Azure AD application ID
AZURE_AUTHORITY	optional	Azure AD authority URL
AZURE_REDIRECT_URI	optional	Azure AD callback URL
AGENT_COLLECTOR_API_KEY	optional	API key for collector endpoints

Authentication Modes

Local Only (Development)

DISABLE_MSAL=true
BASE_PATH=

Azure AD + Local (Production)

DISABLE_MSAL=false
BASE_PATH=/your-app-path
AZURE_CLIENT_ID=your-client-id
AZURE_AUTHORITY=https://login.microsoftonline.com/your-tenant
AZURE_REDIRECT_URI=https://your-domain.com/your-app-path/auth/azure/callback

🛠️ Development

Project Structure

agent_app/
├── main.py                 # FastAPI application and routes
├── models.py              # Pydantic data models
├── crud.py                # Database operations (CRUD)
├── auth.py                # JWT authentication logic
├── database.py            # MongoDB connection setup
├── config.py              # Configuration management
├── msal_auth.py           # Azure AD/MSAL authentication
├── make_admin.py          # Admin user promotion script
├── requirements.txt       # Python dependencies
├── agenthub.service       # Systemd service configuration
├── templates/             # Jinja2 HTML templates
│   ├── base.html          # Base template with Bootstrap
│   ├── nav.html           # Dynamic navigation component
│   ├── index.html         # Landing page
│   ├── login.html         # Authentication form
│   ├── register.html      # User registration
│   ├── agent_register.html # Agent creation form
│   ├── agent_management.html # Agent dashboard
│   ├── search.html        # Global search interface
│   ├── profile.html       # User profile management
│   ├── user_management.html # User management interface
│   └── admin/
│       └── dashboard.html # Admin dashboard with analytics
├── static/                # Static assets
│   ├── style.css          # Custom CSS with modern design
│   └── microsoft-logo.svg # Microsoft branding asset
└── documentation/
    ├── CLAUDE.md          # Claude Code development guidelines
    ├── README_DEV.md      # Local development setup guide
    ├── FEATURE_SUMMARY.md # Detailed feature breakdown
    └── agent_collector_api_documentation.md # API integration guide

Development Guidelines

1. Code Style: Follow existing patterns and conventions
2. Database: Use Motor async driver with proper ObjectId handling
3. Authentication: Use cookie-based auth for web interface
4. Templates: Pass current_user dict objects to templates
5. Error Handling: Implement comprehensive error handling
6. Security: Never log or expose secrets, validate all inputs

Running Tests

# Add your test commands here when implemented
pytest tests/

Code Quality

# Add linting commands here when implemented
flake8 .
black .

🚀 Deployment

Production Deployment

1. Server Setup

   # Install dependencies
   apt update && apt install python3 python3-venv mongodb
   
   # Create application directory
   mkdir -p /var/www/html/agent_tracker
   cd /var/www/html/agent_tracker
   

2. Application Setup

   # Deploy application files
   git clone <repository> .
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

3. Service Configuration

   # Install systemd service
   sudo cp agenthub.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable agenthub
   sudo systemctl start agenthub
   

4. Nginx Configuration (Example)

   location /agent_tracker {
       proxy_pass http://localhost:8038;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
   }
   

Docker Deployment

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Environment-Specific Configuration

Development: Local auth only, root path Staging: Azure AD + local, sub-path
Production: Azure AD primary, sub-path, enhanced security

🔌 External Integrations

Agent Collector API

External systems can automatically register agents using the Agent Collector API:

import requests

# Register agent from external system
agent_data = {
    "name": "AutomationBot",
    "description": "Automated task processing agent",
    "purpose": "Process and analyze customer requests",
    "status": "active",
    "department": "Customer Success",
    "capabilities": ["nlp", "automation", "data-analysis"]
}

response = requests.post(
    "https://your-domain.com/agents",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key"
    },
    json=agent_data
)

Features:

• Automatic agent registration
• Duplicate detection and usage tracking
• Health monitoring integration
• Error handling and retry logic

📈 Analytics & Monitoring

Usage Tracking

• Automatic Collection: Usage data collected via Agent Collector API
• Visualization: Interactive charts with multiple time periods
• Statistics: Total usage, trends, peak periods
• Export: Data available via REST API

System Monitoring

• Health Checks: Database connectivity monitoring
• Performance: Async operations for scalability
• Logging: Comprehensive application logging
• Metrics: User and agent statistics

🔒 Security

Authentication Security

• Password Hashing: bcrypt with salt
• JWT Tokens: Secure token generation with expiration
• CSRF Protection: State validation for OAuth flows
• Session Management: Secure cookie handling

Application Security

• Input Validation: Pydantic model validation
• SQL Injection: MongoDB queries with proper escaping
• XSS Protection: Template auto-escaping
• HTTPS: TLS encryption in production

Access Control

• Role-Based: Admin vs user permissions
• Resource Ownership: Users can only access their own resources
• API Authentication: Token-based API access
• Admin Functions: Protected admin-only operations

🤝 Contributing

1. Fork the Repository
2. Create Feature Branch: git checkout -b feature/amazing-feature
3. Make Changes: Follow existing code patterns
4. Test Changes: Ensure all functionality works
5. Commit Changes: git commit -m 'Add amazing feature'
6. Push Branch: git push origin feature/amazing-feature
7. Open Pull Request

Development Workflow

• Use virtual environments for isolation
• Follow existing code style and patterns
• Test all authentication flows
• Verify responsive design
• Check admin and user permissions

📝 Common Tasks

User Management

# Create admin user
python make_admin.py user@domain.com

# Check user status  
python -c "import asyncio; import crud; print(asyncio.run(crud.get_user_by_email('user@domain.com')))"

Database Operations

# Access MongoDB directly
mongosh agenthub_db

# View collections
db.agents.find()
db.users.find()
db.agent_usage.find()

Service Management

# Check service status
sudo systemctl status agenthub

# View logs
sudo journalctl -u agenthub -f

# Restart service
sudo systemctl restart agenthub

🐛 Troubleshooting

Common Issues

Authentication Problems

• Check JWT secret key configuration
• Verify Azure AD credentials (if using MSAL)
• Clear browser cookies and retry

Database Connection

• Verify MongoDB is running: sudo systemctl status mongod
• Check connection string in environment variables
• Validate database permissions

Template Rendering

• Ensure BASE_PATH is correctly configured
• Check static file serving configuration
• Verify template context variables

Permission Errors

• Check user roles in database
• Verify admin permissions for management functions
• Review agent ownership for edit/delete operations

Debug Mode

# Enable debug logging
export DEBUG=true
uvicorn main:app --reload --log-level debug

📊 System Requirements

Minimum Requirements

• CPU: 1 core
• RAM: 512MB
• Storage: 1GB
• Network: 1Mbps

Recommended Production

• CPU: 2+ cores
• RAM: 2GB+
• Storage: 10GB+ (for logs and data)
• Network: 10Mbps+
• Database: MongoDB cluster or replica set

📄 License

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

🆘 Support

• Documentation: Check /docs endpoint for API documentation
• Issues: Report bugs and feature requests via GitHub issues
• Health Check: Visit /debug/config for system configuration
• Admin Tools: Use admin dashboard for system monitoring

---

AgentHub - Built with ❤️ using FastAPI, MongoDB, and Bootstrap 5