Multi-Agent Productivity Assistant

A production-style hackathon prototype that orchestrates multiple agents to plan work, route tool calls, execute workflows, and persist structured outputs through a FastAPI service.

Overview

This project demonstrates how to build a practical multi-agent backend system with:

• A primary orchestration agent coordinating specialized sub-agents
• MCP-style tool integration for calendar, task management, and notes
• Multi-step workflow execution with execution logs
• Structured persistence using SQLite and SQLAlchemy
• API-first deployment surface using FastAPI

Key Features

• Agent orchestration: Planner, Scheduler, and Knowledge agents under one orchestrator
• Tool routing: dynamic mapping of actions to MCP tool clients
• Workflow history: each run is tracked with step-level execution logs
• Data storage: tasks, notes, workflow runs, and tool executions are persisted
• API docs: interactive Swagger UI at /docs
• Test coverage: endpoint and workflow tests with pytest

Architecture

Agent Layer

• ProductivityOrchestrator (primary coordinator)
• PlannerAgent (goal -> plan steps)
• SchedulerAgent (action -> tool routing)
• KnowledgeAgent (workflow summary generation)

Tool Layer

• MCPToolRegistry resolves tool clients
• MCPToolClient executes either:
  • Real HTTP calls to external MCP endpoints
  • Local mock execution when endpoints are not configured

Data Layer

• tasks
• notes
• workflow_runs
• tool_executions

Project Structure

MultiAgentProductivityAssistant/
├─ app/
│  ├─ api/
│  │  └─ routes.py
│  ├─ core/
│  │  ├─ agents.py
│  │  └─ mcp_tools.py
│  ├─ db/
│  │  ├─ database.py
│  │  ├─ models.py
│  │  └─ repository.py
│  ├─ services/
│  │  └─ orchestrator.py
│  ├─ config.py
│  ├─ main.py
│  └─ schemas.py
├─ tests/
│  ├─ test_api.py
│  └─ test_workflow.py
├─ requirements.txt
├─ Dockerfile
└─ README.md

API Endpoints

• GET /
• GET /health
• POST /api/v1/workflows/execute
• POST /api/v1/tasks
• GET /api/v1/tasks?user_id=<id>
• POST /api/v1/notes
• GET /api/v1/notes?user_id=<id>
• GET /api/v1/workflow-runs?user_id=<id>

Quick Start (Local)

cd C:/Users/Harsh/MultiAgentProductivityAssistant
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Open:

• API docs: http://127.0.0.1:8000/docs
• Health check: http://127.0.0.1:8000/health

Example Workflow Request

{
  "user_id": "user-123",
  "goal": "Schedule my meetings, generate tasks, and capture notes",
  "context": {
    "timeframe": "this week",
    "due_date": "2026-04-02",
    "priority": "high"
  }
}

MCP Integration

Configure optional external MCP endpoints:

• CALENDAR_MCP_URL
• TASK_MCP_URL
• NOTES_MCP_URL

If these are not set, the system uses built-in mock execution so local demo still works.

Testing

Run all tests:

python -m pytest -q

Run a specific test:

pytest tests/test_api.py::test_execute_workflow -v

Deployment

• Deployment guide: DEPLOYMENT.md
• Docker image setup: Dockerfile

Hackathon Submission Assets

• Submission checklist: SUBMISSION_CHECKLIST.md
• Presentation content: PRESENTATION.md
• Demo script: DEMO_SCRIPT.md

Repository

GitHub: https://github.com/vartexx/MultiAgentProductivityAssistant