mate

Abstract

Production-ready multi-agent orchestration engine built on Google ADK. Database-driven agent config, 50+ LLM providers, MCP protocol, persistent memory, web dashboard, RBAC.

The Problem

In production AI agent deployments, iteration becomes prohibitively slow: every prompt tweak requires code changes, commits, and redeploys. Governance gaps emerge because ADK lacks built-in RBAC, making per-agent access control difficult to enforce. Cost tracking is opaque — teams spend without visibility into which agents consume which tokens. Regression testing is reactive, catching breakage only after user complaints surface. These pain points compound as agent hierarchies grow beyond a single notebook prototype.

What This Does

MATE is a production-ready multi-agent orchestration engine built on Google ADK that addresses these gaps through three integrated layers. The Studio layer (shared/template_agent/ and dashboard/) provides a drag-and-drop canvas for creating agents, defining parent→child connections, and attaching tools without touching JSON or Python — every agent lives in the database with versioned configurations and rollback capability. The Control Room layer (shared/utils/rbac_middleware.py, shared/utils/rate_limit_service.py) enforces RBAC per agent, tracks tokens across four buckets (prompt, response, thoughts, tool-use), and implements guardrails for hallucination scoring and rate limits. The Lab layer (shared/test/test_migration_system.py, documents/EVALS.md) provides an eval framework that runs agents against test suites, scores responses, and tracks pass rates across versions with webhook alerts for regressions.

The codebase comprises 283 files across shared/ (141 files, including 136 code files), server/ (7 files), and documentation. Python dominates with 108 files, supported by SQL (40), HTML (36), and Markdown (30). Key entry points include dispatch in server/rate_limit_middleware.py:38 and main in build_standalone_agent.py:641. The internal call graph resolves 1404 call edges between self-referencing functions, with get_session called from 109 places — the most connected function in the codebase.

How It Is Wired

Execution originates at the dispatch entry point in server/rate_limit_middleware.py:38, which reaches 21 functions and is called by nothing else in the repo. The call chain flows through check_request_limit → _get_config, touching the database via session.query(RateLimitConfig).filter(...). From main in build_standalone_agent.py:641, execution reaches 50 functions including copy_build_assets which operates on the filesystem via shutil.rmtree. The start entry point in shared/utils/trigger_runner.py:64 reaches 8 functions and triggers sync_cron_jobs which queries AgentTrigger from the database. The dashboard server (shared/utils/dashboard/dashboard_server.py) is the most routed-to file — 155 functions call into it, and it defines 1 class, handling __init__, _initialize_services, _invoke_agent_for_eval, _get_usage_stats, and _get_database_info. Hub modules like shared/utils/models.py (22 callers) and shared/utils/database_client.py (15 callers) carry wide blast radius; the latter participates in 11 import cycles across modules including shared/utils/agent_manager.py and shared/utils/utils.py.

How To Use It

Setup: Clone the repository verbatim:

git clone https://github.com/moses-y/mate.git && cd mate
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Set GOOGLE_API_KEY (or any supported provider key) in the newly created .env file.

Configuration: The .env.example file at the root and shared/template_agent/.env.example define required environment variables. Authentication defaults to admin / mate per the README.

Running it: Start the auth server:

python auth_server.py

The dashboard launches at http://localhost:8000. Alternatively, use Docker:

docker-compose up

Migrations run automatically on startup; the default database is SQLite.

Real-World Use

A product team building a hierarchy of agents — a sales qualifying agent, a pricing agent, and a compliance agent — can use MATE's dashboard to define the hierarchy visually, assign RBAC so only the finance team accesses the pricing agent, and enable token tracking to see that the compliance agent consumes 60% of budget on reasoning tokens. When they swap the model from Gemini to GPT-4o, the change takes effect immediately without redeploy because agent configuration lives in the database. Before releasing a new version, the eval framework runs the agent suite; if pass rates drop below the regression threshold, a webhook fires before the version reaches production.

Code Health & Issues

Static analysis of 135 code files identified 126 findings across 7 kinds:

High cognitive load: Deep nesting (x24) in shared/utils/models.py, shared/utils/utils.py, shared/callbacks/token_usage_callback.py — max indentation depth 6 makes control flow hard to follow. Oversized files (x6): shared/utils/models.py (691 lines), shared/utils/utils.py, shared/utils/agent_manager.py — hard to hold in one head.
Medium resilience: Broad exception handling (x15) in shared/utils/database_client.py, shared/utils/utils.py, shared/callbacks/token_usage_callback.py — bare except swallows errors indiscriminately.
High soundness: Import cycle member (x11) across shared/utils/database_client.py, shared/utils/utils.py, shared/utils/agent_manager.py — mutually reachable modules create fragile dependencies.
High clarity: Hub modules (shared/utils/models.py, shared/utils/database_client.py) — 28 and 21 modules depend on them respectively, creating high-blast-radius churn points.
Medium cognitive load: High branching density in shared/utils/utils.py — 203 branch points over 692 lines.
High clarity: Duplicated code blocks (347 repeated 6-line blocks across 45 files) including adk_main.py, standalone_server.py, build_standalone_agent.py, and shared/utils/dashboard/dashboard_server.py.

SDLC observations: No CI/CD pipeline detected (no .github/ CI config), dependencies declared without a lockfile (requirements.txt only), and no license file present in the root despite the Apache 2.0 license referenced in shields.io badges.

The Bottom Line

This repo provides a functional, database-driven orchestration layer that successfully abstracts agent configuration, RBAC, and cost tracking away from agent code — the dashboard and eval framework work as advertised. However, the codebase shows significant structural rot: circular imports across 11 modules, 691-line files, and no automated test gate. It's usable today for teams needing immediate agent governance, but any substantial refactoring will require untangling cycles and splitting oversized modules. Teams comfortable operating without CI/CD and who can absorb technical debt for faster iteration will find value; others should expect to invest in cleanup before production scaling.