Medusa Fleet Broker
A deterministic routing broker for multi-agent fleets — the LLM never decides who gets a task or what they're allowed to touch. It only executes what a rules-based broker already approved.
Why this project exists (read this first)
We're upfront about this: eligibility rules for this hackathon exclude our region from prize consideration. So this wasn't built to win — it was built to answer a real question we had for our own venture studio: can an agent-governance product like this actually be positioned and sold to enterprise buyers — CTOs, compliance officers, founders — who need to put AI agents into production without losing control of them? The hackathon deadline was just the forcing function to build a real, working answer instead of a slide deck. Everything below is functional and tested, not aspirational.
The Problem
Enterprises don't hesitate to adopt AI agents because the agents aren't smart enough. They hesitate because nobody can answer three boring questions with confidence: Which agent is allowed to touch this system? What happens when it fails? Can we prove, after the fact, exactly what it did and why?
Most agent demos skip straight to "look what it can do" and bolt on security as an afterthought — a system prompt asking the model to "be careful." That's not a control. A model that can talk itself into believing an action is fine is not a substitute for an access-control layer that never asks the model's opinion in the first place.
Solution
Fleet Broker is the routing layer that sits in front of a fleet of agents, not one of the agents itself. It decides which agent gets a task before the task starts, based on a closed vocabulary of declared capabilities and scopes — and it can reroute or quarantine an agent if its reliability drops, without a human having to notice first.
The one rule everything else follows: an LLM never makes a routing or permission decision. Gemini is invoked only after the broker has already decided who does the work and exactly what they're allowed to touch.
The 9 guardrails
| # | Guardrail | What it actually prevents |
|---|---|---|
| 1 | Closed agent registry | An unregistered agent can't invent a capability like delete_everything to become eligible for a task |
| 2 | Capability ≠ scope | Knowing how to do something is tracked separately from being allowed to touch it |
| 3 | Frozen manifests | An agent can't quietly expand its own permissions mid-run |
| 4 | Mandatory human approval on writes | crm:write, files:write, calendar:write always escalate to needs_human — reliability score doesn't buy a bypass |
| 5 | Two-tier budget ceilings | A misconfigured per-agent limit still can't exceed the fleet-wide hard cap |
| 6 | Circuit breaker | 3 consecutive failures → quarantine, lifted only by a named human, never by the system itself |
| 7 | Recency-weighted reliability | A score, not a vibe — new agents get an explainable cold-start prior, not free trust |
| 8 | Input sanitization | Injection attempts are flagged, never silently stripped; PII is redacted, not deleted |
| 9 | Hash-chained audit log | Editing any past decision breaks the chain — detected on verification, not assumed |
Architecture
Task request
│
▼
FleetBroker — capability match → scope check → reliability check → budget check
│
├─ verdict: refused ──────────────► logged, nothing executes
├─ verdict: needs_human ───────────► logged, escalated, nothing executes
└─ verdict: routed
│
▼
GeminiWorker — re-checks verdict, re-checks scopes, re-sanitizes input,
enforces budget preflight, validates output, never claims
an action it didn't perform
│
▼
Hash-chained audit log — one entry per decision, tamper-evident
Deployment target (coded and unit-tested, not currently running live — see
Challenges below): Gemini via Vertex AI → FastAPI Agent Gateway
(X-Agent-Identity-Key, constant-time comparison, fail-closed if
unconfigured) on Cloud Run → Firestore (agent registry + persistent
audit chain).
Repo layout
fleet-broker/
├── demo.py 7 scenarios — broker core, refusal, escalation,
│ quarantine, audit tamper detection
├── demo_gemini_worker.py 5 scenarios — worker guardrails, real Gemini call
├── demo_api.py 8 scenarios — full FastAPI + Agent Gateway
├── main.py FastAPI entrypoint (Cloud Run target)
├── deploy.sh / deploy.ps1 Cloud Run deployment automation
└── broker/
├── core.py routing, hash-chained audit log
├── manifest.py closed capability/scope vocabulary
├── reliability.py recency-weighted scoring, circuit breaker
├── gemini_worker.py worker guardrails (Vertex AI or API-key mode)
└── firestore_store.py registry + audit persistence
Challenges We Ran Into ⚠️
1. A Google Cloud billing account demanded an upfront prepayment, not just the standard $0–1 verification hold
PROBLEM: our region's account required a real CA$20 prepayment before
Cloud Run/Firestore would activate, beyond the usual refundable
authorization hold.
✅ SOLVED: switched Gemini to API-key mode (Google AI Studio, no billing
account required) so the full local test suite — including a real Gemini
call — runs and proves the routing logic and guardrails end to end.
RESULT: deploy.sh, main.py, and firestore_store.py remain fully coded
and unit-tested against an in-memory fake store, ready to deploy the
moment that friction is worth resolving.
2. Keeping the LLM out of every permission decision
PROBLEM: the easiest architecture is one where the model reads the task and
decides what to do with it — which is exactly the design we refused to
build.
✅ SOLVED: the broker computes routed / needs_human / refused before
Gemini is ever invoked, and the worker independently re-checks the verdict,
the scopes, and the budget — so a bug upstream fails closed, not open.
RESULT: three layers would all have to fail simultaneously for a
disallowed action to execute.
3. Making the audit log actually tamper-evident, not just tamper-logged
PROBLEM: an append-only log that trusts storage order isn't proof of anything. ✅ SOLVED: every entry hashes the previous entry's hash. Verification re-walks the chain from scratch rather than trusting arrival order — tested by deliberately editing one entry and confirming detection points to the exact broken link. RESULT: a tampered entry is provably tampered, not just suspicious.
Accomplishments We're Proud Of 🎖️
- Zero-LLM-permission architecture, actually enforced — not a claim in a slide, a guardrail re-checked independently at both the broker and the worker layer
- 20 test scenarios across 3 suites, all passing, covering refusal, escalation, quarantine, budget ceilings, audit tamper detection, and a real Gemini call
- Hash-chain tamper detection that actually catches tampering — tested by breaking it on purpose
- Honest scope discipline — the deployment path is fully coded and tested, not deployed live, and this README says so plainly instead of implying otherwise
What's Next
- Persist reliability scores in Firestore (currently the registry and audit chain survive a cold start; reliability history doesn't yet)
- Stress-test suite: concurrent load at the per-agent cap, capability/scope mismatch edge cases, quarantine persistence under load
- Resolve the Cloud billing friction and run the full Vertex AI + Cloud Run
- Firestore stack live
- Use what we learned here to shape how we pitch agent governance to actual enterprise buyers — which was the real point of building this
One-Paragraph Pitch
Medusa Fleet Broker is a deterministic routing layer for multi-agent fleets that keeps every permission decision out of the LLM's hands. It decides which agent gets a task before the task starts, escalates write-scope actions to a human every time regardless of an agent's track record, quarantines unreliable agents until a named human clears them, and keeps a hash-chained audit log that proves — not just claims — that no past decision was altered. Gemini executes approved work only. Built to find out how this kind of infrastructure actually gets sold to the people who have to trust it in production.
Built With
python · fastapi · pydantic · google-genai (gemini api) · google-cloud-firestore · google-cloud-run · google-cloud-vertex-ai · google-cloud-secret-manager · docker
Try it out
Repository is private for this submission. No live URL — see "Challenges" above for why, and the repo's README for full local spin-up instructions (no cloud account required to run the test suite).
Log in or sign up for Devpost to join the conversation.