How mjanbandhu/multi-agent-productivity-assistant works
1. This repository is a Python 3.12 backend for a multi-agent productivity assistant. The runtime is FastAPI, packaged for Docker and deployed on Google Cloud Run. The app is centered on a single HTTP API that accepts natural-language productivity requests.
2. The main entrypoint is app/main.py, which wires the FastAPI application and mounts the API routes from app/api/routes.py. That file is the external boundary of the system: users send a POST /query request and receive a normalized response payload.
3. Request handling follows a clear pipeline: API route → primary orchestration agent → specialized agent(s) → tool layer → database. The PrimaryAgent in app/agents/primary_agent.py is the central router that decides whether the query should go to the task, notes, calendar, or multiple agents in sequence.
4. The specialized agents are split by domain in app/agents/task_agent.py, app/agents/notes_agent.py, and app/agents/calendar_agent.py. Each agent is responsible for interpreting user intent in its domain and coordinating the corresponding operation, rather than letting the API layer talk directly to storage.
5. The tool layer in app/tools/ is the execution boundary between agent logic and persistence. task_tool.py, notes_tool.py, and calendar_tool.py encapsulate the actual CRUD-style operations for tasks, notes, and events, keeping business operations separated from routing logic.
6. Database access is isolated in app/db/connection.py and app/db/queries.py. The README indicates PostgreSQL/AlloyDB with psycopg2, so the architecture is a synchronous relational backend: tools call query helpers, which use the shared DB connection layer to execute SQL against PostgreSQL.
7. The system supports multi-step instructions, so a single query can fan out to more than one agent. Example: “create task … and add note … and schedule meeting …” is expected to be decomposed by the primary agent into multiple domain actions, each handled by its own specialized agent/tool path.
8. The app/mcp/ directory suggests an internal Model Context Protocol-style tool exposure layer. server.py and tool_registry.py likely provide a registry and server boundary for exposing the assistant’s tools to an MCP-compatible client or internal agent runtime, separating tool registration from the FastAPI request surface.
9. app/utils/helpers.py is the shared utility boundary for reusable parsing or formatting logic that is not specific to one domain. In an architecture diagram, this sits as a supporting cross-cutting layer used by agents or tools rather than as a primary subsystem.
10. The deployment model is cloud-native and stateless at the application layer. Environment variables provide database credentials, while the container image is started via Docker/Cloud Run or the Procfile/Uvicorn command shown in the README. Persistent state lives in PostgreSQL, not in the API process.
11. The important external dependencies are FastAPI for HTTP, PostgreSQL for persistence, psycopg2 for DB connectivity, Docker for packaging, and Google Cloud Run for hosting. No frontend is present in the repository; this is a backend API service only.
12. For an architecture diagram, the key boundaries are: client/API ingress, primary orchestration, domain agents, tool execution, database access, and the optional MCP/tool registry layer. The system is intentionally modular so each product area can be extended independently without changing the external API contract.
Main entry points: primary_agent.py Primary agent · server.py MCP server · task_agent.py Task agent · queries.py SQL queries
Components 17
API ingress
HTTP entrypoint and external request surface
- Client · Sends natural-language productivity requests
- App entry · Builds and starts the FastAPI application
app/main.py - API routes · Exposes the POST /query request and normalizes responses
app/api/routes.py
Orchestration
Primary routing and domain agents
- Primary agent · Routes each request to one or more domain agents
app/agents/primary_agent.py - Task agent · Interprets task-related intent and coordinates task actions
app/agents/task_agent.py - Notes agent · Interprets note-related intent and coordinates note actions
app/agents/notes_agent.py - Calendar agent · Interprets calendar intent and coordinates event actions
app/agents/calendar_agent.py
Execution
Tool layer and database access
- Task tool · Executes task CRUD operations
app/tools/task_tool.py - Notes tool · Executes note CRUD operations
app/tools/notes_tool.py - Calendar tool · Executes calendar and event operations
app/tools/calendar_tool.py - SQL queries · Builds and runs domain SQL statements
app/db/queries.py - DB connection · Shared PostgreSQL connection management
app/db/connection.py - PostgreSQL · Persistent datastore for tasks, notes, and events
MCP layer
Internal tool exposure boundary
- MCP server · Exposes assistant tools through an MCP-style boundary
app/mcp/server.py - Tool registry · Registers available tools for the MCP layer
app/mcp/tool_registry.py
Support
Shared utilities and deployment/runtime boundary
- Helpers · Reusable parsing and formatting helpers
app/utils/helpers.py - Cloud runtime · Containerized deployment environment for the stateless API
Dockerfile
Connections 23
- Client → App entry: HTTP request · Client sends requests to the service entrypoint
- App entry → API routes: mounts · FastAPI app wires in the API routes
- API routes → Primary agent: dispatch · Route handler forwards queries into orchestration
- Primary agent → Task agent: task · Routes task intent to the task specialist
- Primary agent → Notes agent: notes · Routes note intent to the notes specialist
- Primary agent → Calendar agent: calendar · Routes calendar intent to the calendar specialist
- Primary agent → Task agent: multi-step · May fan out one request across multiple agents
- Task agent → Task tool: executes · Task agent delegates work to task tools
- Notes agent → Notes tool: executes · Notes agent delegates work to notes tools
- Calendar agent → Calendar tool: executes · Calendar agent delegates work to calendar tools
- Task agent → Helpers: uses · Shared parsing or formatting support
- Notes agent → Helpers: uses · Shared parsing or formatting support
- Calendar agent → Helpers: uses · Shared parsing or formatting support
- Task tool → SQL queries: sql · Tool layer calls query helpers for persistence
- Notes tool → SQL queries: sql · Tool layer calls query helpers for persistence
- Calendar tool → SQL queries: sql · Tool layer calls query helpers for persistence
- SQL queries → DB connection: uses · Query helpers execute through the shared DB connection
- DB connection → PostgreSQL: connects · Persistent state lives in PostgreSQL
- Tool registry → MCP server: registers · Registry provides the MCP server with available tools
- MCP server → Task tool: exposes · MCP boundary can expose task tools
- MCP server → Notes tool: exposes · MCP boundary can expose notes tools
- MCP server → Calendar tool: exposes · MCP boundary can expose calendar tools
- Cloud runtime → App entry: runs · Containerized deployment runs the API process