Sprix SAGE Router: checkpoint-aware rerouting for A2A agent networks

The gap SAGE fills between agent discovery and task execution

Agent discovery answers which agents exist. It does not answer who should work with whom once execution has already started, and that is the question this project targets. The README frames SAGE, short for State-Aware Graph Exchange, as "the decision layer between A2A discovery and task execution." The intended user is an engineer wiring up a multi-agent network on top of the Agent2Agent protocol, where agents advertise capabilities through Agent Cards and exchange tasks, messages and artifacts, but where nothing in the protocol itself decides whether the incumbent agent should keep going.

The three routes are named SELF, COLLABORATE and HANDOFF. SELF keeps the incumbent agent in place. COLLABORATE keeps the incumbent as owner but adds a small complementary team. HANDOFF transfers full ownership to a peer. The README's own framing of the trade-off is that HANDOFF is worth it only when specialist advantage exceeds context-transfer loss, which is the honest way to put it: changing owners throws away accumulated context, and the router has to price that loss.

This is a narrow problem, and the project says so. The research focus is "checkpoint-aware reconfiguration after execution has begun." If your agents each run a single short task and never need to be reassigned mid-flight, the router adds a decision layer you will not exercise.

How the routing objective works: calibrated capability, reuse fractions and one utility score

The mechanism visible in the README is a scoring pipeline. For a requirement r, SAGE combines a global trust value with a requirement-conditioned one to produce a calibrated capability q. When the current owner has completed fraction f of that requirement, a candidate owner reuses fraction eta, and eta equals f if ownership is retained or f times the artifact portability tau if ownership changes. The blended quality is then eta times the current owner's quality plus (1 minus eta) times the candidate's quality. The practical consequence is that switching owners only pays when the new agent is good enough to overcome the work that gets redone.

The same reused fraction reduces projected remaining cost and duration, which prevents the router from charging lost work twice, once as rework and again inside the learned success probability. The README states that only the assigned owner contributes requirement coverage, so adding an unassigned teammate no longer creates a noisy-OR quality gain. That is a deliberate correction rather than a feature, and it makes the model less optimistic than a naive coalition score.

Assignment and scheduling are searched jointly. Work assigned to one agent is serialized; work on independent agents can run concurrently; team-level cost and critical-path latency are rechecked after construction. Feasible routes are ranked by a single linear utility that subtracts cost, latency, risk, handoff loss, coordination overhead and uncertainty, and adds an exploration bonus. The README is explicit that noisy-OR, beam search, the linear utility, Beta beliefs, online logistic regression and DAG-induced communication edges are not claimed as inventions. They are described as replaceable implementation mechanisms. That candour is unusual and it tells you where to look if you want to swap a component.

Installing Sprix SAGE Router and running a first route

The reference implementation requires Python 3.10 or later and, according to the README, has no runtime dependencies. The quick start is a clone followed by the demo script. Running it should print the demo's routing output, which is the fastest way to confirm the package imports cleanly on your interpreter.

py -3.10 -c "import sys; print(sys.version)"
git clone https://github.com/wang2122/sprix-sage-router.git
cd sprix-sage-router
python demo.py

The verification suite is run with the standard library test runner, and the repository ships several benchmark scripts alongside it. The README lists them as follows.

python -m unittest -v
python benchmark.py
python benchmark_dynamic.py
python benchmark_trust.py

For a first real route, the README's minimal usage example builds two agents with per-skill capability scores, a task with two requirements where coding depends on planning, and an execution state that records what has already completed. The router is constructed with an incumbent, and route_with_trace returns a trace whose selected field carries the mode, assignments and topology.

from sprix_sage import (
    Agent, ExecutionOutcome, ExecutionState,
    Requirement, SAGERouter, Task,
)

agents = [
    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")

The state object is where this library differs from a plain dispatcher. You supply completed_requirements, the in-flight requirement and its progress, observed partial quality, and a per-requirement artifact transferability map. The example sets coding transferability to 0.40, which is the number that makes HANDOFF expensive in this scenario. After execution, record_outcome takes an ExecutionOutcome with a success value, per-requirement scores, actual cost and actual latency. The README's example then notes that the decision can be persisted, though the truncated text stops at that point.

Where the router is the wrong tool, and what the README does not document

The most concrete limitation is stated by the project itself: the status badge reads Research Preview, and pyproject.toml classifies the package as Development Status 3 - Alpha. Treat the API as moving. There is no published compatibility promise, and the release history shows v0.1.0 on 2026-08-18 followed by v0.3.0 on 2026-08-28, a ten-day gap with a minor version jump. That is a fast-moving surface for a library you would put on a critical path.

The second limitation is evidential. The repository ships benchmark.py, benchmark_dynamic.py, benchmark_trust.py, benchmark_scaling.py and two evaluator benchmarks, and the README describes a separate evaluator that replays checkpoints and scores artifact reuse, added cost, recovery latency, wasted work and final quality without calling SAGE's switching equation. That separation is the right design if you want an honest comparison, but the README does not present results, so you cannot conclude from the documentation that SAGE beats a static coalition. The README does state that progress-masked and static-coalition baselines receive the same registry and limits, which tells you the comparison is intended to be fair. Intended is not the same as demonstrated.

Third, the inputs are your responsibility. The router needs artifact transferability per requirement and observed partial quality for the in-flight work. Neither can be measured by the library. If you cannot produce those numbers, the reuse fraction eta is a guess, and the whole handoff decision rests on it. The README does not document how to estimate transferability, and it does not document rollback behaviour if a chosen route fails after selection. For a system whose purpose is mid-execution correction, the absence of a documented rollback path is the gap I would press on first.

Sprix SAGE Router compared with a static coalition scheduler

The natural alternative is a static assignment: pick the best agent for each requirement up front, then let the plan run. The README names this directly as a baseline, calling it a static coalition, and says such baselines receive the same registry and limits as SAGE. The difference in approach is when the decision is made. A static scheduler commits before execution and has no mechanism to react to observed partial quality or to a requirement that turns out to be harder than advertised. SAGE re-evaluates at checkpoints, using completed requirements, in-flight progress and observed quality as inputs.

A second alternative is a reputation-based dispatcher, where each agent carries one trust score and the highest scorer takes the task. The README rejects that model explicitly: reliability is tracked per agent and per requirement rather than assuming one reputation score transfers across skills. In the README's own example, the planner scores 0.92 on planning and 0.55 on coding, so a single global score would misrepresent it in both directions.

The cost of the SAGE approach is that you must supply more state. A static scheduler needs a capability table. SAGE needs capability, cost, latency, completed requirements, in-flight progress, observed quality and transferability, plus an outcome record after each run so the trust model has something to learn from. If your execution environment cannot emit those signals, a static assignment is the better engineering choice, and the router will not earn its complexity.

Maintenance, packaging and licence implications

The repository is not archived, and the last push was on 2026-08-28. That is recent relative to the release cadence, but it is a single data point, and the project describes itself as a research output of Sprix AI at 屿智同行 rather than a product. Plan for the possibility that the research focus moves on.

Upgrade cost is low in one respect and uncertain in another. The package has no runtime dependencies, so there is no dependency tree to reconcile and no transitive version conflicts. It also builds with setuptools and declares four top-level modules: sprix_sage, sprix_learning, sprix_types and sprix_a2a. The uncertainty is the API. Between v0.1.0 and v0.3.0 the version moved twice in ten days, and the README does not state a deprecation policy. Pin the version in your own requirements and read CHANGELOG.md before bumping.

The licence is MIT, declared in pyproject.toml as license = "MIT" with license-files = ["LICENSE"]. MIT permits commercial use and modification provided the copyright notice and permission notice are retained. That is a permissive arrangement, but it is not legal advice, and if you redistribute the library inside a product you should read the LICENSE file in the repository and confirm the notice requirements with whoever handles compliance on your side. The repository also ships CITATION.cff, which suggests the authors expect academic citation alongside code reuse.

Editorial conclusion

Adopt Sprix SAGE Router if you are building an A2A network and need an auditable decision layer for mid-execution rerouting, particularly if you want to inspect why a route was chosen rather than only which agent won. Do not adopt it as a production scheduler today: the project labels itself Research Preview, the last push was on 2026-08-28, and the README does not document rollback, persistence guarantees, or a stable API contract. Before committing, verify three things in the repository itself: that the routing trace exposes the fields your system needs, that record_outcome fits your evidence pipeline, and that the MIT licence terms suit how you intend to distribute the code.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. wang2122/sprix-sage-router on GitHub