agent-route-grid
An audited routing layer for multi-agent teams — zone-based routing policy, workspace isolation, and a hash-chained decision trail. Who executes, who reviews, who decides — visible and verifiable.
pip install agent-route-grid # zero deps, Python 3.9+
中文版 · Research prototype / AI-assisted development.
Multi-agent teams grow fast and drift into chaos: nobody knows who was supposed to decide, whether anyone reviewed it, or what actually happened. This library turns routing into a visible policy and every decision into a verifiable record.
Why a routing layer?
Most agent frameworks hand you workers; nobody hands you governance. This library packages the governance questions a real team asks:
- Who may execute this? → zone policy (risk-based)
- Who reviews it? → independent reviewer (yellow zone)
- Who else needs a say? → panel consultation (red zone)
- What happened? → hash-chained trail,
verify()offline
Route zones
| Zone | When | Strategy |
|---|---|---|
green |
low risk, routine | coordinator self-executes |
yellow |
medium risk | delegate to one worker, then independent review |
red |
high / critical risk | panel consultation, aggregate; any fault keeps fail-closed |
purple |
training / mentorship | route as a learning exercise with a referee |
The mapping is deterministic and injectable: pass your own ZonePolicy.
Product family
Part of the Verifiable-agent family — one fail-closed design language:
| Repo | Role |
|---|---|
| agent-call-audit | audit engine for agent tool calls |
| agent-memory-ledger | verifiable memory layer |
| agent-audit-gateway | HTTP gateway around the engine |
| agent-route-grid | audited multi-agent routing (this repo) |
Install
pip install agent-route-grid # once published
# dev / from source:
pip install -e .
Zero runtime dependencies. Python 3.9+.
Quick start
from routegrid import AgentSpec, Coordinator, Task
team = [
AgentSpec(name="worker", capabilities=("lookup",), scope="ws-w"),
AgentSpec(name="reviewer", capabilities=("lookup",), scope="ws-r",
review_capable=True),
]
co = Coordinator(team, timeout_s=2.0)
res = co.route(
Task(name="medium decision", risk="medium", requires=("lookup",)),
worker_fns={"worker": lambda t: {"summary": "done"}}, # your executors
reviewer_fns={"reviewer": lambda t, ctx: {"verdict": "approve"}},
)
print(res.zone, res.strategy, res.fail_closed) # yellow delegate+review False
Workers are injected callables — the coordinator never runs business logic; it only routes, times out, collects, and records.
Proof of life
Real output from python examples/demo.py:
1 green -> zone=green strategy=self-execute fail_closed=False
2 yellow -> zone=yellow strategy=delegate+review fail_closed=False
3 red -> zone=red strategy=panel+aggregate fail_closed=False
4 purple -> zone=purple strategy=mentor fail_closed=False
workspace isolation: worker->own True | worker->other False
trail verification: 4 entries, OK
fail-closed demo: panel-a errored -> fail_closed=True
Fail-closed invariants
| Invariant | Guarantee |
|---|---|
| Worker fault | worker error/timeout marks the call and route result fail-closed |
| Reviewer fault | missing/broken review keeps the result fail-closed |
| Panel dissent | red-zone panel with any non-ok call keeps denial semantics |
| Scope isolation | writing another agent's workspace is denied |
| Trail tamper-evident | verify() detects any modification to the chain |
Architecture
routegrid/
├── models.py AgentSpec / Task / WorkerCall / RouteResult
├── policy.py ZonePolicy (zone_for / panel_members), DEFAULT_POLICY
├── coordinator.py Coordinator: route() by zone, timed threads, trail
├── scope.py ScopeGuard: workspace write isolation
└── trail.py AuditTrail: append-only JSONL + sha256 chain
examples/ demo.py (five-scenario walkthrough)
tests/ 35 unit tests
Roadmap ideas
- Async orchestration (parallel panel with fan-out)
- Plugin hooks for human-in-the-loop review UIs
- Trail exporter (MCP / OTel)
Contributing / Security / License
- CONTRIBUTING.md — fail-closed first, sanitized commits, green tests.
- SECURITY.md — report privately; reference implementation.
- LICENSE — MIT,
agent-route-grid maintainers.
Metadata
Release files for agent-route-grid 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_route_grid-0.1.1.tar.gz | 11.4 kB | With provenance | Details for agent_route_grid-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_route_grid-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agent_route_grid-0.1.1-py3-none-any.whl |
Total release size: 23.0 kB
Release files / agent_route_grid-0.1.1.tar.gz
| Download URL | agent_route_grid-0.1.1.tar.gz |
|---|---|
| Size | 11.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2a5b7743a676802ddbf3667625a051cd32ca4de4cde881bcdfb6778b8eb4059f
|
|
BLAKE2b-256 checksum How to use checksums |
dd6df5f8aa321fe895acde5691e60b6c919b2ed07ac6ed920cf5b6c8426fdd45
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / agent_route_grid-0.1.1-py3-none-any.whl
| Download URL | agent_route_grid-0.1.1-py3-none-any.whl |
|---|---|
| Size | 11.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
57756b767b67c7c5d680d89222b523549802f908dc8f912a5587b61aefe560d6
|
|
BLAKE2b-256 checksum How to use checksums |
7e099fce1fb6c3e0dcbda0bed3686321e2e9523664a6948bca4b4bd99157c202
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for agent-route-grid 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_route_grid-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.