Route AI Agent Tasks with the Sprix SAGE Router

What is Sprix SAGE Router?

Sprix SAGE Router is an open-source Python research project for deciding how AI agents should execute a task after work has already begun. SAGE stands for State-Aware Graph Exchange. It operates between agent discovery and task execution, selecting a feasible agent configuration while considering current progress, capabilities, permissions, cost, latency, dependencies, and context-transfer loss.

The router compares three execution modes:

• SELF: The incumbent agent continues alone when its capabilities and accumulated context are sufficient.
• COLLABORATE: The incumbent retains ownership while complementary agents cover missing requirements.
• HANDOFF: A peer takes full ownership when its specialist advantage outweighs the cost of transferring context.

SAGE is designed to sit above the Agent2Agent protocol. A2A defines interoperable Agent Cards, tasks, messages, artifacts, authentication, and transport. SAGE addresses a different question: which eligible configuration should execute a task, in which mode, and why?

The current prototype returns routing decisions. It does not transmit tasks to agents, so an A2A client or another execution layer must carry out the selected route.

Key routing features

SAGE combines routing, scheduling, and online learning in one inspectable decision process. Its principal features include:

• Tri-mode routing: SELF, COLLABORATE, and HANDOFF candidates compete under the same utility objective.
• Progress-aware replanning: Accumulated progress, active executors, failures, completed task nodes, and transferable context can affect whether switching is worthwhile.
• Complementary team selection: Teams are rewarded for adding requirement coverage rather than collecting redundant high-ranked agents.
• Contextual trust: Reliability is learned for each agent and requirement instead of being reduced to one global reputation score.
• Task-DAG scheduling: Requirements are assigned to executors, while dependency edges determine execution order, communication topology, and critical-path latency.
• Bounded search: Beam search evaluates several collaboration-team prefixes rather than making a single greedy choice.
• Constraint-first filtering: Ineligible agents are removed before ranking, regardless of their predicted quality.
• Evidence-aware learning: Requirement scores, actual costs, and actual latency can update trust, synergy, the success model, and bid fidelity.
• Auditable results: Decisions expose the selected mode, assignments, topology, predicted success, coverage, cost, latency, risk, utility, and rationale.

How the algorithm evaluates a route

For each task requirement, SAGE combines global trust with requirement-conditioned trust to estimate an agent's calibrated capability. Team coverage increases when members contribute useful, nonredundant capability. Every remaining requirement is then assigned to the strongest calibrated team member.

The scheduler respects the requirement DAG. Work assigned to one agent is serialized, while independent work assigned to different agents can run in parallel. After constructing a candidate team, SAGE checks team-level cost and critical-path latency against the task's budget and deadline.

Feasible candidates are ranked with a utility function that balances predicted success value against cost, latency, risk, context-transfer loss, coordination overhead, and uncertainty. This allows a stronger specialist to lose to the incumbent when handing off would discard too much useful context. It also lets a complementary team beat a prestigious but redundant collection of agents.

Install and verify the project

Prerequisites

The reference implementation requires Python 3.10 or newer. According to the project README, it has no runtime dependencies.

Clone the repository

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

The demo.py script provides a readable end-to-end example. Because the repository exposes its implementation directly through sprix_sage.py, the quick start does not require a separate package-installation command.

Run tests and the benchmark

python -m unittest -v
python benchmark.py

The unit tests verify expected router behavior. The benchmark runs an external nonlinear simulator across deterministic seeds, allowing the static and online versions of SAGE to be compared with simpler routing strategies.

Create your first routing scenario

Step 1: Import the core types

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

This example uses Agent to describe candidates, Requirement and Task to define the work, SAGERouter to choose a route, and ExecutionOutcome to return evidence after execution.

Step 2: Define available agents

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,
    ),
]

Each agent has an identifier, a capability vector, a cost estimate, and a latency estimate. Here, planner is strong at planning, while coder is stronger at coding. This difference gives SAGE a reason to consider collaboration or handoff rather than ranking agents by one overall score.

Step 3: Model requirements and dependencies

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,
)

The task contains two weighted requirements. The coding requirement depends on planning, creating a small DAG in which planning must finish before coding. The task also supplies the values needed for constrained routing:

• value represents the value of successful completion.
• budget limits acceptable cost.
• deadline_ms limits scheduled latency.
• progress tells the router that execution is already 35 percent complete.

Progress matters because changing ownership mid-execution can introduce context-transfer loss. A specialist's capability advantage therefore does not automatically make handoff the best route.

Step 4: Route the task

router = SAGERouter(
    agents,
    incumbent_id="planner",
)

decision = router.route(task)

print(decision.mode)
print(decision.assignments)
print(decision.topology)

The incumbent is the agent that currently owns the task. Calling route compares feasible SELF, COLLABORATE, and HANDOFF candidates. The returned decision can be inspected through fields such as:

• decision.mode for the chosen execution mode.
• decision.assignments for requirement-to-agent role assignments.
• decision.topology for the dependency-induced communication structure.

Do not assume that this particular scenario must always produce one specific mode. The result depends on the router's calibrated estimates, constraints, progress, and learned state.

Learn from execution outcomes

Routing is only the first half of the workflow. After the selected agents execute the task, return the strongest available evidence to the router:

router.record_outcome(
    decision,
    ExecutionOutcome(
        success=0.9,
        requirement_scores={
            "planning": 0.95,
            "coding": 0.86,
        },
        actual_cost=0.19,
        actual_latency_ms=1450,
    ),
)

The overall success value gives the router a task-level result. Requirement-specific scores provide more precise credit assignment, preventing every teammate from receiving identical credit. Actual cost and latency help calibrate future predictions and provider quotes.

Repeated routing and feedback allow online SAGE to refine contextual trust, pair effects, success predictions, and bid fidelity. For useful learning, record outcomes consistently and prefer measured evidence over coarse success labels whenever that evidence is available.

Integrate SAGE with an A2A system

A production integration can translate protocol and marketplace signals into SAGE's internal representations:

• Normalize AgentCard.skills into capability vectors.
• Use security requirements as hard permission filters.
• Check supported input and output modes for compatibility before scoring.
• Map task status, artifacts, completed DAG nodes, and failures into current execution state and transfer-loss estimates.
• Represent provider quotes as bids containing cost, latency, and confidence.
• Use completed-task evaluations to update contextual trust, pair residuals, success predictions, and bid fidelity.

Once SAGE returns a decision, an A2A client can execute it using protocol operations such as message sending, streaming, task polling, or cancellation. Keep the boundary explicit: SAGE selects and explains the route, while the A2A layer handles communication and execution.

Advanced usage tips

Model the task as a meaningful DAG

Use dependencies to represent genuine execution order rather than placing every requirement in a flat list. Accurate dependencies let SAGE distinguish serial work from parallel work and produce a more useful critical-path latency estimate.

Prefer complementary capability descriptions

Describe agents with requirement-level capabilities. A single broad score would hide the distinction between planning, coding, research, or other skills and would weaken contextual trust and role assignment.

Treat permissions as hard constraints

Do not use predicted quality to override access rules. SAGE's permission-first design expects ineligible agents to be excluded before candidate ranking. Compatibility, authentication, and policy checks should likewise occur before execution.

Use realistic budgets and deadlines

SAGE checks constraints during candidate construction and again at the team level. Supply task-specific budgets and deadlines so that an individually attractive collection of agents cannot be selected when its combined cost or critical path is infeasible.

Inspect decisions instead of using only the mode

Review assignments, topology, coverage, predicted success, cost, latency, risk, utility, and rationale. The audit trail can reveal whether a route was chosen for genuine complementarity, incumbent context retention, lower transfer loss, or constraint feasibility.

Measure quote fidelity

Return actual cost and latency after execution. Without observed values, the router has less evidence for determining whether quoted confidence, price, and timing are reliable.

Evaluate trade-offs with a common utility

The included synthetic benchmark reports that online SAGE achieves higher simulated quality and common utility than the listed baselines, while spending more than static SAGE. This visible trade-off is important: routing should not hide cost behind a capability-only score.

The benchmark is synthetic and is not evidence of real-world superiority. Real deployment evaluation requires representative executions, strong routing baselines, calibration analysis, marketplace trace replay, heterogeneous agents, and adversarial conditions.

Understand the research-preview limitations

SAGE is an early-stage research preview, not a production service-level guarantee or peer-reviewed result. Its lightweight learned policy does not replace training on real traces or causal off-policy evaluation.

Before production deployment, the README recommends calibrated evaluators, authenticated identities, signed capability metadata, privacy and security review, persistent event-driven recovery, monitoring, and task-specific validation. Real adapters for A2A discovery, execution, streaming, and cancellation remain roadmap items, as do distributed service operation and human approval gates.

Repository resources

• sprix_sage.py contains the contextual router, DAG scheduler, beam search, and online updates.
• demo.py provides an end-to-end example.
• benchmark.py contains the external simulator and common-utility baselines.
• test_sprix_sage.py contains behavioral unit tests.
• ALGORITHM.md documents the formal objective, search process, credit assignment, and limitations.
• The GitHub repository contains contribution, security, governance, and license information.

Conclusion

Sprix SAGE Router provides a practical reference implementation for state-aware agent matching. By representing work as requirement DAGs, comparing SELF, COLLABORATE, and HANDOFF under shared constraints, and feeding execution evidence back into the router, you can experiment with auditable multi-agent decisions that account for both predicted quality and operational cost.

Start with demo.py, reproduce the minimal example, inspect every routing decision, and run the tests and synthetic benchmark. For real A2A deployment, add a separate execution adapter and complete the authentication, security, observability, recovery, and validation work required by your environment.