https://github.com/seehiong/adk-web-multi-agent
Multi-Agent System built with Google ADK and OpenRouter models, coordinating specialist agents to query PostgreSQL (via MCP Toolbox) and Data Commons for HDB resale data and global statistics.
https://github.com/seehiong/adk-web-multi-agent
agent-hierarchy coordinator-pattern datacommons google-adk llm multi-agent-system openrouter postgresql toolbox
Last synced: 3 months ago
JSON representation
Multi-Agent System built with Google ADK and OpenRouter models, coordinating specialist agents to query PostgreSQL (via MCP Toolbox) and Data Commons for HDB resale data and global statistics.
- Host: GitHub
- URL: https://github.com/seehiong/adk-web-multi-agent
- Owner: seehiong
- Created: 2025-11-03T11:47:16.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-11-03T12:46:21.000Z (3 months ago)
- Last Synced: 2025-11-03T13:20:40.284Z (3 months ago)
- Topics: agent-hierarchy, coordinator-pattern, datacommons, google-adk, llm, multi-agent-system, openrouter, postgresql, toolbox
- Language: Jupyter Notebook
- Homepage:
- Size: 31.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ADK Web Multi-Agent System
This repository demonstrates building a multi-agent system using **Google's ADK (Agent Development Kit)**. The system allows for natural language querying across two distinct data sources: a local **PostgreSQL** database for HDB resale data and the **Data Commons MCP API** for general global statistics.
The architecture implements a **Coordinator/Dispatcher** Pattern to route specialized queries to the correct agent.
**Read the full guide here:** [ADK Web Multi-Agent System](https://seehiong.github.io/posts/2025/11/adk-web-multi-agent-system/)
## Project Structure
```bash
adk-web-multi-agent-system/
├── tools.yaml # MCP Toolbox configuration for PostgreSQL tools
├── toolbox_playground.ipynb # Jupyter Notebook containing testing/execution code
├── pyproject.toml # Project dependencies managed by uv
├── .gitignore
└── agents/ # Directory for individual specialist agents
├── __init__.py # Makes 'agents' a package
├── agent.py # Defines the Coordinator LLM Agent
├── datacommons_agent/ # Agent for global Data Commons queries
│ ├── __init__.py
│ ├── agent.py # Defines the Data Commons LLM Agent
│ └── instructions.py
└── postgres_agent/ # Agent for structured HDB PostgreSQL queries
├── __init__.py
├── agent.py # Defines the PostgreSQL LLM Agent
└── instructions.py
```
## Prerequisites & Setup
This project relies on external services and specific environment tools:
1. **PostgreSQL Database**: A local instance running on 127.0.0.1:5432 with the public.resale_transactions table populated (DDL provided in the blog post).
2. **Data Commons MCP Server**: Start a local instance using the Data Commons CLI:
```powershell
uvx datacommons-mcp serve http --port 8001
```
3. **Toolbox (PostgreSQL Interface)**: The MCP tool server for PostgreSQL can be started from project root:
```powershell
.\toolbox
```
4. **Python Environment**: Managed using `uv` for dependency isolation:
```powershell
uv venv
uv init
uv add google-adk litellm toolbox-core
```
## Running the Agents
This project structure requires a **Coordinator Agent** (defined in the main execution logic) that hierarchically manages the `postgres_agent` and `datacommons_agent` via the `sub_agents` argument.
To run the entire multi-agent system locally, execute the following command from your activated environment:
```powershell
adk web
```