Skip to main content

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+

License Python Tests Deps Status

GitCode GitHub

中文版 · 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)

Source distribution for agent-route-grid 0.1.1
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)

Table of built distributions (wheels) for agent-route-grid 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page