wang2122/sprix-sage-router

Agent discovery tells a system which agents exist. It does not answer the harder runtime question: who should work with whom after execution has already begun?

SAGE—State-Aware Graph Exchange—is the decision layer between A2A discovery and task execution. It evaluates three routes in one auditable objective:

SAGE is designed to sit above the Agent2Agent (A2A) protocol. A2A provides Agent Cards, messages, tasks, artifacts, authentication, and transport. SAGE decides which feasible agent configuration should execute the task, in which mode, and why.

_{Figure 1. SAGE filters candidates, compares all three routing modes, jointly searches assignments and schedules, ranks feasible plans, and learns from execution evidence.}

SAGE is deliberately narrow: checkpoint-aware reconfiguration after execution has begun.

• Concrete continuation value. The router preserves completed requirements and combines in-flight completion, observed partial quality, current ownership, and artifact portability to estimate how much work each candidate must actually redo.
• Comparable runtime actions. SELF, COLLABORATE, and HANDOFF share one permission-, budget-, and deadline-constrained action space. Progress-masked and static-coalition baselines receive the same registry and limits.
• Requirement-conditioned evidence. Reliability is tracked per agent and requirement instead of assuming that one reputation score transfers across skills.
• Trajectory-level falsification. A separate evaluator replays checkpoints and scores artifact reuse, added cost, recovery latency, wasted work, and final quality without calling SAGE's switching equation.

Noisy-OR, beam search, a linear utility, Beta beliefs, online logistic regression, and DAG-induced communication edges are not claimed as inventions. They are replaceable implementation mechanisms. The repository also provides permission-first filtering, bounded candidate search, workload-sensitive quotes, auditable alternatives, degraded-route flags, state persistence, and transport-neutral A2A plans as engineering features.

For task requirement (r), SAGE combines global and requirement-conditioned trust into calibrated capability (q_{a,r}). If the current owner has completed fraction (f_r), a candidate owner reuses fraction (\eta_r):

$$ \eta_r=\begin{cases}f_r,&\text{owner retained}\f_r\tau_r,&\text{owner changed}\end{cases},\qquad \bar q_{a,r}=\eta_r q^{\mathrm{current}}_r+(1-\eta_r)q_{a,r} $$

Here (\tau_r) is artifact portability. Only the assigned owner contributes requirement coverage; adding an unassigned teammate no longer creates a noisy-OR quality gain. The same reused fraction reduces projected remaining cost and duration, so lost work is not charged again inside the learned success probability.

SAGE jointly searches calibrated requirement owners and their schedule. Work assigned to one agent is serialized, work on independent agents can run concurrently, and team-level cost and critical-path latency are checked again after construction.

Every feasible route is ranked by:

$$ U(m,S,z,E)=V\hat p_\theta(y=1\mid x,m,S,z,E)-\lambda_c C-\lambda_l L-\lambda_r R-\lambda_h H-\lambda_o O-\lambda_u\mathcal U+\beta\mathcal B $$

Here (z) is role assignment, (E) is the induced communication topology, (H) is context-transfer loss, (O) is coordination overhead, and (\mathcal U/\mathcal B) support uncertainty-aware exploration. The full design and limitations are documented in ALGORITHM.md.

The reference implementation requires Python 3.10+ and has no runtime dependencies.

git clone https://github.com/wang2122/sprix-sage-router.git
cd sprix-sage-router
python demo.py

Run the verification suite:

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

Minimal usage:

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")
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)
decision = trace.selected
print(decision.mode, decision.assignments, decision.topology)
print(trace.excluded_agents)

# Feed back the strongest available evidence after execution.
router.record_outcome(
    decision,
    ExecutionOutcome(
        success=0.9,
        requirement_scores={"planning": 0.95, "coding": 0.86},
        actual_cost=0.19,
        actual_latency_ms=1450,
    ),
)

# Persist learned evidence after validated outcomes.
snapshot = router.export_state()

Production integration maps protocol and marketplace signals into SAGE as follows:

sprix_a2a.py validates declared skill IDs against locally calibrated evidence and converts the selected route into a transport-neutral ExecutionPlan. The plan includes ownership, assignments, DAG dependencies, communication edges, estimated resources, and rationale.

The current prototype intentionally does not transmit tasks, authenticate endpoints, or verify signatures. An A2A client remains responsible for message/send, streaming, polling, cancellation, and secure artifact handling. See the integration guide and runnable examples.

The repository separates three questions instead of treating one synthetic table as proof of the whole system.

benchmark_dynamic.py replays 1,000 checkpoints over five seeds. The independent evaluator scores concrete artifact portability and remaining work; it never calls the router's switch-loss code. Every policy receives the same registry, action space, budget, and deadline.

The controlled intervention holds task, agents, difficulty, artifact portability, budget, and deadline fixed while changing only in-flight completion from 0.0 to 0.9. Progress-aware minus progress-masked utility grows from 0.0000 to +0.0684; the complete ten-point curve is emitted in JSON.

_{Controlled intervention. The two policies are identical except that the masked policy receives zero in-flight completion. Values are synthetic five-seed means, not real-endpoint evidence.}

benchmark_trust.py gives per-requirement and single-reputation models the same exogenous round-robin evidence stream, so exploration spend cannot explain the difference. After 500 observations per seed in the heterogeneous specialist setting, per-requirement trust reaches Brier 0.0125 ± 0.0018 and selection regret 0.0094 ± 0.0008, versus 0.0355 ± 0.0008 and 0.0310 ± 0.0359 for one reputation score. In the homogeneous negative control both methods have zero routing regret, so the benchmark does not manufacture an advantage when specialization is absent.

benchmark.py still runs 2,500 independent tasks against the structurally separate geometric evaluator. Its purpose is regression and learning ablation, not the mid-execution claim:

All three CLIs support deterministic seeds and JSON output. Exact commands, schemas, curves, and limitations are in the benchmarking guide.

• Signed Agent Card ingestion and capability normalization
• Requirement-conditioned trust and online success prediction
• Requirement DAG assignment and team-level deadline checks
• Evidence-aware partial credit and quote-fidelity learning
• Auditable alternatives and hard-filter explanations
• Versioned JSON learning-state snapshots
• Transport-neutral Agent Card mapping and execution plans
• Machine-readable deterministic benchmark reports
• Learned task-text embeddings and candidate retrieval
• Bounded quote-only candidate prefilter and request-local scoring cache
• Checkpoint-aware remaining-work and artifact-reuse model
• Progress-masked, static-coalition, dynamic-oracle, and trust-convergence studies
• Repeated checkpointed evaluation on heterogeneous real A2A endpoints
• Real A2A adapters for discovery, execution, streaming, and cancellation
• Offline replay on anonymized Sprix marketplace traces
• Adversarial-bid, churn, privacy, and policy-violation evaluation
• Distributed router service with observability and human approval gates

SAGE builds on coalition formation, multi-agent task allocation, combinatorial allocation, contextual bandits, LLM routing, and dynamic agent-network research. The source-linked comparison explains what each area establishes, how SAGE differs, and which optimality, mechanism-design, and causal-learning claims this repository does not make.

SAGE is an early-stage research preview, not a production SLA or a peer-reviewed result. Current main focuses the research claim on checkpoint-aware mid-execution rerouting and adds controlled progress, trajectory, static-coalition, and trust-convergence studies. These synthetic studies are not substitutes for real trace training or causal off-policy evaluation. Production deployment requires calibrated evaluators, authenticated identities, signed capability metadata, privacy and security review, persistent event-driven recovery, monitoring, and task-specific validation. See the operations guide for rollout gates and metrics.

Sprix AI is the A2A initiative of 屿智同行, focused on agent discovery, task matching, multi-agent scheduling, and transaction mechanisms for dependable agent-to-agent service exchange. Sprix SAGE Router is an open-source algorithmic research output of that initiative.

Company attribution describes the project's origin; this public repository remains a research preview and does not expose proprietary production systems or data.

• Yonghao Zhang — CEO of 屿智同行; Master's degree in Computer Science from Tsinghua University.
• Yichen Wang — CTO of 屿智同行; Sprix AI project lead and SAGE algorithm designer.

Additional community contributions are credited through their commits, pull requests, and the repository's contributors graph.

We welcome technically grounded issues and pull requests. Please read CONTRIBUTING.md, follow the Code of Conduct, and report vulnerabilities according to SECURITY.md.

If you use this design in academic work, cite the repository metadata in CITATION.cff.

Released under the MIT License. Copyright © 2026 Sprix AI at 屿智同行.