PAclaw Swarm

An autonomous PA with the super power to cater to your daily needs like todos, expenses, manage emails and calendar, stock, data and business analysis. It is well organised mini YOU.

Comment

PAclaw Swarm: An Autonomous Multi-Agent Assistant

Hackathon Submission: All Things Agentic Hackathon (Google / Devpost)
Track: The Taskmaster
Technologies: Google ADK (Agent Development Kit), Gemini 3.5 Flash (Production) / Gemini 2.5 Flash (Testing), Google Cloud Run, Supabase PostgreSQL, FastAPI, Telegram Webhook

🔥 Beyond Passive Chatbots

Imagine waking up to a personal executive briefing already delivered to your phone—your emails triaged, your day's schedule mapped out, market movements analyzed, and high-priority tasks organized—without you ever typing a single prompt.

Most AI tools today are strictly passive: they sit inside a browser tab and wait for human instructions. PAclaw Swarm changes the paradigm. Powered by Google ADK and Gemini 3.5 Flash for production execution (with Gemini 2.5 Flash powering rapid automated testing & verification suites), PAclaw Swarm operates 24/7 as an autonomous, proactive digital chief of staff that runs in the background, handles massive data streams, and automates complex workflows asynchronously.

💡 Inspiration

Most AI tools today suffer from a fundamental limitation: they wait for you to ask. They sit passively inside a browser tab, requiring manual prompts, manual copy-pasting, and repetitive instructions.

We set out to build PAclaw Swarm — an autonomous, proactive multi-agent assistant designed to handle the heavy lifting of daily productivity. Inspired by the vision of a true digital chief of staff, PAclaw Swarm actively monitors your calendar, reads your emails, tracks market movements, calculates financial balance sheets, generates platform-optimized content, plans travel itineraries, and alerts you proactively via Telegram and an interactive Operations Dashboard.

Instead of a single monolithic chatbot, PAclaw Swarm is built as an intelligent swarm of 10 specialized sub-agents coordinated by a central root Orchestrator.

🚀 What It Does

PAclaw Swarm operates 24/7 as a background agentic system. It processes requests asynchronously, executes real-world tools, and persists state across sessions.

🌟 Key Features & Specialist Roster

  1. Root Orchestrator Agent: Dynamically classifies user intent and routes execution to domain specialist agents while maintaining conversation context.
  2. Tasks & Projects Agent: Creates, updates, and tracks project tasks with priority matrixing and SQLite/Supabase ORM persistence.
  3. Google Workspace Agent: Integrates live with Gmail, Google Calendar, Google Drive, and Google Contacts (searching unread emails, scheduling calendar meetings, querying drive files).
  4. Financial Tracker Agent: Logs income and expenses, infers transaction categories, normalizes multi-currency inputs, and computes net balances: $$\text{Net Balance} = \sum \text{Income} - \sum \text{Expenses}$$
  5. Market Intelligence Agent: Analyzes stock and crypto assets using live market feeds (yfinance), computes percentage changes, and manages custom watchlists.
  6. Deep Research Agent: Scrapes web pages, performs web searches, tracks topic preferences, and generates comprehensive research reports.
  7. News Digest Agent: Synthesizes custom daily news digests tailored to user topic preferences.
  8. Multi-Platform Content Creation Agent: Writes platform-customized posts for LinkedIn, X (Twitter) threads, and Medium articles, incorporating fact-checking and editorial revisions.
  9. Business Analytics Agent: Loads raw CSV datasets, computes descriptive statistics (averages, totals, top performers), and generates structured business reports.
  10. Travel Planning Agent: Builds multi-day travel itineraries, queries flights and hotels, and syncs trip schedules directly to Google Calendar.
  11. Proactive Autonomous Engine & Scheduler: Runs background loops to evaluate overdue task deadlines, upcoming calendar events, urgent unread emails, and stock volatility ($|\Delta P| \ge 3.0\%$).
  12. Operations Dashboard & Telegram Bot: Serves a real-time web UI dashboard via FastAPI and routes updates directly to a Telegram Bot with clean, mobile-optimized HTML formatting.

⚙️ How We Built It

PAclaw Swarm was built from the ground up using Google's Agent Development Kit (ADK) and Google Cloud serverless infrastructure.

                      +-------------------------------------------------+
                      |               USER INTERFACES                   |
                      |  [Telegram Bot]  |  [Operations Dashboard UI]   |
                      +------------------------+------------------------+
                                               |
                                               v
                      +-------------------------------------------------+
                      |         FastAPI Server & Webhook Gateway        |
                      +------------------------+------------------------+
                                               |
                                               v
                      +-------------------------------------------------+
                      |            ADK ROOT ORCHESTRATOR                |
                      |            (model: gemini-3.5-flash)            |
                      +------------------------+------------------------+
                                               |
   +-------------------+-----------------------+-------------------+-------------------+
   |                   |                       |                   |                   |
   v                   v                       v                   v                   v
[Workspace Agent] [Finance Agent]       [Market Agent]     [Content Agent]     [Research Agent]
 (Gmail/Calendar)  (Supabase DB)       (yfinance API)      (Editor Tools)       (Web Scraper)
   |                   |                       |                   |                   |
   +-------------------+-----------------------+-------------------+-------------------+
                                               |
                                               v
                      +-------------------------------------------------+
                      |             GOOGLE CLOUD INFRASTRUCTURE         |
                      |   [Cloud Run Container]  |  [Vertex AI SDK]     |
                      |   [Supabase PostgreSQL]  |  [Secret Manager]    |
                      +-------------------------------------------------+

Stack & Technologies

  • Core Agent Framework: Google Agent Development Kit (Google ADK)
  • LLM Backbone: Gemini 2.5 Flash / Gemini 3.5 via Vertex AI (google-genai SDK)
  • Cloud Infrastructure: Google Cloud Run (Serverless Container Hosting)
  • Database: Supabase PostgreSQL (Production) / SQLite (Local / Testing)
  • API & Web Gateway: FastAPI & Uvicorn
  • Messaging Integration: Telegram Bot API via Webhooks

🧠 Mathematical & Algorithmic Models

To ensure deterministic evaluation in data analytics and financial calculation tools, the agents execute verified mathematical formulas rather than estimating numbers:

1. Weighted Asset Price Volatility

$$\Delta P_{\text{pct}} = \left( \frac{P_{\text{current}} - P_{\text{previous}}}{P_{\text{previous}}} \right) \times 100$$ When $|\Delta P_{\text{pct}}| \ge \text{Threshold}$, the Autonomous Engine fires an instant alert to Telegram.

2. Analytical Metric Aggregation

$$\bar{X}{\text{sales}} = \frac{1}{N} \sum{i=1}^{N} x_i, \quad \text{Top Performer} = \arg\max_{p \in P} \left( \frac{\sum \text{Sales}_p}{\text{Count}_p} \right)$$

💥 Challenges We Ran Into

  1. Non-Deterministic Tool Contracts vs Structured Outputs:

    • Problem: Early iterations of the Content Creation tools used static string templates, causing the agent to get trapped in editorial rewrite loops when user topics changed.
    • Solution: Refactored content_tools.py into dynamic functional processors that accept research_notes and draft_content parameters, enabling the agent to weave real search facts into articles.

  2. Serverless OAuth Credentials & State Persistence:

    • Problem: Deploying to Google Cloud Run meant local file-based credentials (~/.config/gcloud/) were unavailable in the container filesystem, causing Google Workspace API calls to fail.
    • Solution: Upgraded workspace_auth.py to support container-packaged adc.json loading and base64 environment variable credential hydration, enabling 24/7 uninterrupted OAuth access on Cloud Run.

  3. Vertex AI Regional IAM Permissions:

    • Problem: Deploying to Cloud Run resulted in 403 PERMISSION_DENIED errors on aiplatform.endpoints.predict because Cloud Run's default compute service account lacked Vertex AI IAM roles.
    • Solution: Granted roles/aiplatform.user to <PROJECT_NUMBER>-compute@developer.gserviceaccount.com using gcloud projects add-iam-policy-binding.

🎯 Accomplishments That We're Proud Of

  • Full Multi-Agent Swarm: Successfully implemented 10 specialized ADK sub-agents with clean routing and zero cross-agent state contamination.
  • Zero-Friction Telegram Bot: Full 2-way interaction via webhooks on Cloud Run — users can manage tasks, check emails, summarize finances, and research topics directly from their phone.
  • Proactive Background Execution: The scheduler engine actively monitors calendar events, overdue tasks, urgent emails, and stock swings without waiting for user prompts.
  • Production Cloud Deployment: Successfully packaged, built, and deployed to Google Cloud Run.

📚 What We Learned

  • Designing Agentic Swarms: Dividing responsibilities into 10 specialized sub-agents dramatically improves precision, reducing prompt size and preventing hallucinated tool arguments.
  • Reliable Tool Design: Tools should act as functional data transformers rather than hardcoded text generators, giving the LLM room to reason over input facts.
  • Serverless Background Architectures: Managing asynchronous webhook endpoints and OAuth token auto-refreshes in stateless Cloud Run container instances.

🔮 What's Next for PAclaw Swarm

  • 🎙️ Voice Interface: Integrate Gemini 2.0 / 3.0 Live Audio WebSockets for hands-free voice interaction over Telegram audio messages.
  • 🧠 Vector Memory Bank: Implement pgvector / Vertex AI Search for long-term semantic memory across months of user interactions.
  • 🏢 Multi-User Enterprise Fleet: Expand the governance model to support multi-tenant team accounts with role-based access control (RBAC).

🛠️ Reproducible Spin-Up & Test Instructions

To verify and run the project locally:

1. Clone & Activate Virtual Environment

git clone https://github.com/zackmendel/google_adk.git
cd google_adk/002_adk_hackathon
source .venv/bin/activate

2. Run the Full Reproducible Test Suite (101/101 Tests)

PYTHONPATH=. DATABASE_URL="" SQLITE_DB_PATH=":memory:" TELEGRAM_BOT_TOKEN="" python3 -m unittest discover -s pa_agent/tests -v

3. Launch Local Operations Dashboard

uvicorn pa_agent.dashboard_app:app --host 0.0.0.0 --port 8000

Access at: http://localhost:8000

Submitted to the All Things Agentic Hackathon 2026 (Google / Devpost)

Built With

Share this project:

Updates

Submission history