Da2a

Da2a demonstrates a multi-agent system for data analysis using the Agent Development Kit (ADK).

It showcases an agent-in-agent architecture where a root agent orchestrates tasks by communicating with specialized, independently deployed sub-agents via the Agent-to-Agent (A2A) protocol. The agents perform analysis on real-world e-commerce and marketing datasets from Olist.

Table of Contents

• Da2a
  • Table of Contents
  • Features
  • Prerequisites
  • Installation
  • Usage
    • Running Agents Locally
    • Deploying to GCP
  • Available Agents
    • Root Agent
    • Sub-Agents
  • Example Queries
    • E-commerce only
    • Marketing only
    • Multi-Agent (da2a)
  • License

Features

• Multi-Agent System: Implements a robust agent-in-agent architecture with a central orchestrator and specialized, distributed sub-agents.
• Agent-to-Agent (A2A) Communication: Demonstrates how agents can communicate and delegate tasks over the network using the A2A protocol.
• Specialized Data Analysis Agents: Features distinct agents for e-commerce and marketing data, each with its own database and query capabilities.
• Rapid Deployment: Go from code to a deployed multi-agent system on GCP in minutes.
• Modern Python Tooling: Employs uv for fast dependency management and just for simple command automation.

Prerequisites

Before you begin, ensure you have the following tools installed:

• gcloud
• just
• uv
• npm (for the mcp-sqlite tool)

Installation

1. Clone the repository:

   git clone https://github.com/fmind/da2a.git
   cd da2a

2. Set up your environment:

   Create a .env file by copying the .env.sample file. Populate it with your GCP project ID and location.

   cp .env.sample .env
   # Edit .env with your details

3. Install dependencies:

   just install

4. Ingest the datasets:

   This command unzips the datasets and loads them into the local SQLite databases for the e-commerce and marketing agents.

   just ingest

5. Configure Google Cloud:

   If you plan to deploy the agents, configure your GCP settings.

   just cloud

Usage

This project uses just as a command runner. You can see all available commands by running just with no arguments.

Running Agents Locally

To serve the root agent's web interface locally for testing and interaction:

just web

This starts the client application, which hosts the root agent. The root agent will connect to the e-commerce and marketing agents, which are expected to be running at their default localhost URLs. You will need to run the sub-agents in separate terminals.

(Note: Running the full multi-agent system locally requires starting each agent service separately. The just web command only starts the da2a/root agent.)

Deploying to GCP

To deploy all three agents (da2a, ecommerce, marketing) to Google Cloud Run:

just deploy-all

You can also deploy a single agent by specifying its name:

just deploy ecommerce
just deploy marketing
just deploy da2a

Available Agents

This project features a root_agent that acts as an orchestrator for two specialized data analysis sub-agents.

Root Agent

• Name: root_agent
• Location: da2a/agent.py
• Description: A data analysis orchestrator that understands user questions and delegates them to the appropriate sub-agent. It synthesizes the results into a final, user-friendly answer.

Sub-Agents

• ecommerce_agent:

  • Location: ecommerce/agent.py
  • Description: Answers questions about e-commerce data from the Olist dataset.
  • Data Scope: Orders, products, customers, sellers, payments, and reviews.
  • Tools: Uses mcp-sqlite to execute natural language queries against its SQLite database.

• marketing_agent:

  • Location: marketing/agent.py
  • Description: Answers questions about marketing funnel data from the Olist dataset.
  • Data Scope: Marketing Qualified Leads (MQLs), deals, seller acquisition, and lead origin.
  • Tools: Uses mcp-sqlite to execute natural language queries against its SQLite database.

Example Queries

E-commerce only

How many orders were placed in the state of 'SP' (São Paulo)?

There were 41,746 orders placed in the state of São Paulo (SP).

What are the top 5 product categories with the most products listed?

The top 5 product categories with the most products listed are:

Bed Bath Table with 3029 products. Sports Leisure with 2867 products. Furniture Decor with 2657 products. Health Beauty with 2444 products. Housewares with 2335 products.

Marketing only

How many Marketing Qualified Leads (MQLs) were acquired from each origin?

Here is the breakdown of Marketing Qualified Leads (MQLs) acquired from each origin:

Organic Search: 2,296 Paid Search: 1,586 Social: 1,350 Unknown: 1,099 Direct Traffic: 499 Email: 493 Referral: 284 Other: 150 Display: 118 Other Publicities: 65 N/A: 60

What are the top 3 business segments for closed-won deals?

The top 3 business segments for closed-won deals are:

Home Decor with 105 deals Health & Beauty with 93 deals Car Accessories with 77 deals

Multi-Agent (da2a)

What is the average freight value for orders handled by all sellers who were acquired through 'social' media channels?

The average freight value for orders handled by sellers who were acquired through 'social' media channels is 17.76.

What is the total sales revenue (sum of payment values) from sellers who were acquired via Display?

The total sales revenue (sum of payment values) from sellers who were acquired via the Display marketing channel is 1,207.95.

License

This project is licensed under the MIT License. See the LICENSE.txt file for details.