agent-route-grid:基于 Python 的多智能体审计路由项目

An audited routing layer for multi-agent teams: zone-based routing policy, workspace isolation, hash-chained trail (MIT).

Branch1Tags2
FilesLast commitLast update
2 days ago
3 days ago
4 days ago
4 days ago
4 days ago
4 days ago
4 days ago
3 days ago
4 days ago
4 days ago
3 days ago
4 days ago
3 days ago

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.

Introduction

An audited routing layer for multi-agent teams: zone-based routing policy, workspace isolation, hash-chained trail (MIT).

Customize your domain