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

• Mid-execution tri-mode routing. SELF, COLLABORATE, and HANDOFF compete in the same utility function instead of relying on disconnected heuristics.
• Progress-aware replanning. Active executors, completed DAG nodes, failures, accumulated progress, and transferable context affect whether switching is worthwhile.
• Complementarity before prestige. A team is rewarded for marginal requirement coverage, not for collecting individually high-ranked but redundant agents.
• Contextual trust instead of one reputation score. Reliability is learned per agent and per requirement, so success in coding does not automatically imply strength in research.
• Task-DAG role assignment. Every remaining requirement is assigned to an executor; dependency edges become an inspectable communication topology and critical-path latency estimate.
• Joint team and role search. A nested assignment beam can trade a small capability margin for parallel execution instead of rejecting a deadline-feasible team after greedy role assignment.
• Learned outcome model. A regularized online predictor replaces the original fixed success equation and can later be swapped for a production reward model.
• Bounded team search. Beam search compares multiple team prefixes instead of committing to one greedy sequence.
• Bid fidelity. Quoted confidence, cost, and latency are calibrated against observed execution evidence.
• Permission-first matching. Ineligible agents never enter the ranking, regardless of predicted quality.
• Evidence-aware credit. Per-requirement and per-agent outcomes avoid giving every teammate identical full credit.
• Auditable alternatives. route_with_trace records the winner, ranked feasible alternatives, eligible agents, and explicit hard-filter reasons.
• Persistent learning. Versioned JSON snapshots preserve contextual trust, synergy, bid fidelity, and online-model state across restarts.
• Transport-neutral A2A plans. Agent Card helpers combine declarations with local evidence and produce execution plans without hiding transport responsibilities.

For task requirement (r), SAGE combines global and requirement-conditioned trust into calibrated capability (q_{a,r}). Team coverage is:

$$ C_r(S)=1-\prod_{a\in S}(1-q_{a,r}) $$

SAGE jointly searches calibrated requirement owners and their schedule. It can retain a slightly weaker executor when that choice parallelizes independent DAG nodes and improves constrained utility. 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.

_{Figure 2. Empirical mode sweep over budget and incumbent capability, with per-mode utility crossings and the factors that move the boundary. Exact boundaries depend on configuration and learned state.}

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

Minimal usage:

from sprix_sage import Agent, ExecutionOutcome, 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")
trace = router.route_with_trace(task)
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.

benchmark.py runs 2,500 tasks over five deterministic seeds in an external simulator. Hidden capability, pair effects, nonlinear quality, realized cost, and realized latency are deliberately different from SAGE's prediction model. Values are mean ± population standard deviation across seeds:

_{Figure 3. External quality, shared utility, normalized cost, deadline misses, and the Online SAGE route mixture. Error bars show population standard deviation across five seeds.}

All strategies are evaluated with the same external quality-cost-latency utility. Online SAGE spends more than static SAGE to obtain higher simulated quality; that trade-off remains visible instead of being hidden behind a capability-only score.

Use python benchmark.py --json benchmark-results.json for a versioned machine-readable summary, or change seeds and suite size with --seeds and --tasks-per-seed. See 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
• 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

• Agent2Agent Protocol Specification — interoperable Agent Cards and stateful tasks.
• RouteLLM: Learning to Route LLMs with Preference Data, ICLR 2025 — preference-based cost-quality routing.
• A Dynamic LLM-Powered Agent Network for Task-Oriented Agent Collaboration, COLM 2024 — task-specific dynamic team selection.
• GPTSwarm: Language Agents as Optimizable Graphs, ICML 2024 — agent systems as optimizable computation graphs.
• AFlow: Automating Agentic Workflow Generation, ICLR 2025 — automated workflow search and optimization.
• MasRouter: Learning to Route LLMs for Multi-Agent Systems, 2025 preprint — collaboration mode, role, and model routing.

SAGE is an early-stage research preview, not a production SLA or a peer-reviewed result. Version 0.2 adds a genuinely learned but deliberately lightweight policy layer, auditable routing traces, versioned learning snapshots, and a transport-neutral integration boundary. These 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 屿智同行.