Sprix SAGE Router
A checkpoint-aware routing layer for A2A agent networks that decides mid-execution whether to continue, collaborate, or hand off.
Evidence shows permission requirements enter as a hard eligibility filter, SECURITY.md documents a threat model and pushes identity, sandboxing, and least-privilege credentials to adopters; the core deliberately does not transmit, authenticate, or sign. Deductions: human confirmation appears only as an unchecked roadmap item with no implementation; rollback exists only as learning-state snapshot export with no decision-level recovery; source and test files were not supplied, so the hard-filter and data-flow claims score on README assertions alone.
Evidence shows cross-document consistency (README, pyproject, and CI workflows agree on modules, commands, schema versions) and near-zero dependency-availability risk with no runtime dependencies. Deductions: failure-message and exception quality cannot be verified because test_*.py and sources were not provided; CI smoke benchmarks cover only small parameter ranges.
Evidence shows unusually explicit scenario framing (the SELF/COLLABORATE/HANDOFF usage table), capability boundaries (no transport, no auth, research preview), and Python 3.10–3.12 CI matrix. Deductions: environment fit requires the adopter to build the A2A client; real-endpoint evaluation remains an open roadmap item; trigger-precision evidence is entirely from self-authored synthetic benchmarks.
Evidence shows complete information architecture (layered ALGORITHM/RELATED_WORK/INTEGRATION/OPERATIONS/BENCHMARKING docs, repository map), full MIT license text, well-formed pyproject metadata, named maintainers, and SECURITY/CONTRIBUTING/CITATION files. Deductions: CHANGELOG.md is referenced but not supplied, so version history is inferred from 0.3.0 and the roadmap; examples/README.md was not provided, so example quality is unverified; unverified publisher identity means maintenance sustainability can only be scored on declaration.
Evidence shows auditable traces with ownership, assignments, topology, and rationale, three deterministic CLIs emitting JSON reports, and near-zero deployment cost as pure Python with no runtime deps. Deductions: marginal value hinges on the core progress-awareness claim whose supporting numbers come from project-authored evaluators that the README itself labels 'not evidence of real-world superiority', so realized utility cannot be confirmed from this evidence.
Evidence shows strong fact/inference separation — synthetic numbers are repeatedly labeled regression evidence only, the research-preview status and explicit non-claims are stated, and benchmark commands and schemas are reproducible. Deductions: cross-source corroboration is entirely absent; all performance figures come from evaluators written by the same authors with no third-party or real-endpoint validation; key source and test files were not in the review materials, so formula-to-implementation traceability could not be completed.
- This is a static source review (confidence: low); no code was executed, and the supplied materials exclude source and test files, so many scores rest on README assertions.
- All benchmark figures come from project-authored evaluators that the README itself disclaims as real-world evidence; independently validate the mid-execution switching decisions on real A2A endpoints before adoption.
- The prototype performs no authentication, signing, or task transmission; production use must add identity, authorization, sandboxing, and human approval per SECURITY.md — no confirmation mechanism is implemented.
- Keep secrets, private prompts, and personal data out of snapshots and traces; poisoned learning evidence can shift online beliefs and there is no rollback mechanism.
- Publisher identity is unverified by any curated registry; treat maintenance sustainability as declared only and verify independently.
What does this agent do, and when should you use it?
Sprix SAGE Router is an open-source research preview from Sprix AI at 屿智同行, positioned as the decision layer above the A2A protocol: it answers who should work with whom after execution has already begun. Its core is a checkpoint-aware SAGERouter that compares SELF, COLLABORATE, and HANDOFF routes under one auditable objective, weighing completed DAG nodes, reusable artifacts, observed partial quality, remaining work, failures, budget, and deadline. The codebase comprises sprix_sage.py (router, DAG scheduler, beam search, audit traces), sprix_learning.py (online model and Beta beliefs), sprix_types.py (validated types), and sprix_a2a.py (Agent Card normalization and transport-neutral ExecutionPlan), with zero runtime dependencies on Python 3.10+. Three benchmark CLIs (benchmark.py, benchmark_dynamic.py, benchmark_trust.py) ship with the repo, but the authors state explicitly that these synthetic results are regression and falsification evidence only, not proof of real-world superiority, and the project is not a production SLA or peer-reviewed result.
It takes a Task (with a Requirement DAG, value, budget, deadline, progress) and an ExecutionState (active agents, in-flight progress/quality, completed requirements, artifact portability). SAGERouter.route_with_trace() applies permission and capability filters, then jointly searches requirement ownership and schedules across SELF/COLLABORATE/HANDOFF modes (work on one agent serializes; independent agents run concurrently), ranks feasible plans by the utility U(m,S,z,E)=V·p̂_θ−λC−λL−λR−λH−λO…, and returns an auditable trace with ownership, assignments, DAG dependencies, communication edges, estimated resources, and rationale. After execution, record_outcome() ingests an ExecutionOutcome (success, per-requirement scores, actual cost and latency) to update requirement-conditioned trust and the online success model; export_state() emits versioned JSON learning snapshots. sprix_a2a.py maps signals like A2A AgentCard.skills into normalized capability vectors and converts the selected route into a transport-neutral ExecutionPlan. The repo also provides demo.py, examples/, and three benchmark commands with deterministic seeds and JSON output.
- Engineering teams building A2A multi-agent systems that need a mid-execution (checkpoint) decision on whether the incumbent continues, recruits a small complementary team, or hands off fully to a specialist peer.
- Multi-agent platform developers who want requirement-conditioned trust—tracking each agent's reliability per skill instead of one reputation score across all skills.
- Researchers reproducing or comparing progress-aware vs. progress-masked, static-coalition, dynamic-oracle, and trust-convergence baselines via the checkpoint trajectory replay in benchmark_dynamic.py.
- Teams needing explainable routing: route_with_trace exposes excluded agents, hard-filter explanations, and auditable alternatives for post-hoc review of switching decisions.
- Teams running offline learning ablations and regression tests on synthetic data: benchmark.py and benchmark_trust.py support deterministic seeds and JSON reports.
What are this agent's strengths and limitations?
- Tightly scoped research focus: it addresses checkpoint-aware reconfiguration after execution begins—a runtime gap in most A2A discovery layers—and evaluates SELF/COLLABORATE/HANDOFF within one permission-, budget-, and deadline-constrained action space.
- Auditable and falsifiable by design: route_with_trace returns rationale, exclusion reasons, and alternatives; an independent evaluator scores outcomes without calling the router's switch-loss equation, and benchmarks include progress-masked controls and homogeneous negative controls.
- Low integration burden: Python 3.10+ with zero runtime dependencies, versioned JSON learning-state snapshots, and benchmark CLIs with deterministic seeds and JSON output.
- All benchmark numbers come from synthetic evaluators authored alongside the project; the README itself states they are not evidence of real-world superiority, and repeated checkpointed evaluation on heterogeneous real endpoints is still pending—validate before adopting.
- The prototype boundary is explicit: no task transmission, endpoint authentication, or signature verification; your A2A client must handle message/send, streaming, cancellation, and secure artifact handling, and real A2A adapters remain on the roadmap.
- As an early-stage research preview it is neither a production SLA nor peer-reviewed; production deployment requires calibrated evaluators, authenticated identities, signed capability metadata, privacy/security review, and rollout gates—nontrivial adoption cost.
How do you install or deploy this agent?
Requires Python 3.10+ with no runtime dependencies:
git clone https://github.com/wang2122/sprix-sage-router.git
cd sprix-sage-router
python demo.pyNo API keys or credentials needed. Verification: python -m unittest -v; benchmarks: python benchmark.py, python benchmark_dynamic.py, python benchmark_trust.py.
How do you use this agent?
Embed it as a Python library in your scheduling code. Minimal usage:
python
from sprix_sage import Agent, ExecutionOutcome, ExecutionState, Requirement, SAGERouter, Taskagents = [Agent("planner", {"planning": 0.92, "coding": 0.55}, cost=0.08, latency_ms=900),
Agent("coder", {"planning": 0.35, "coding": 0.96}, cost=0.12, latency_ms=1200),
]
task = Task("build-feature",
requirements=(Requirement("planning", 0.4), Requirement("coding", 0.6, depends_on=("planning",))),
value=1.0, budget=0.30, deadline_ms=4000, progress=0.35)
router = SAGERouter(agents, incumbent_id="planner")
state = ExecutionState(active_agents=("planner",),
active_assignments={"planning": "planner", "coding": "planner"},
completed_requirements=frozenset({"planning"}),
inflight_requirement="coding",
inflight_progress=0.35, inflight_quality=0.72,
artifact_transferability={"planning": 0.95, "coding": 0.40})
trace = router.route_with_trace(task, state=state)
print(trace.selected.mode, trace.selected.assignments, trace.selected.topology)
router.record_outcome(trace.selected, ExecutionOutcome(success=0.9, requirement_scores={"planning": 0.95, "coding": 0.86},
actual_cost=0.19, actual_latency_ms=1450))
snapshot = router.export_state()Note: the current prototype does not transmit tasks, authenticate endpoints, or verify signatures; message/send, streaming, polling, cancellation, and secure artifact handling remain the responsibility of your A2A client.