agenticraft_foundation.protocols.routing¶
Protocol-aware routing algorithms — Dijkstra (minimum-cost), BFS (minimum-hop), and resilient routing with failover.
Protocol-aware Dijkstra routing (Algorithm 1).
Finds optimal path considering protocol translation costs. State space: (agent, incoming_protocol).
RoutingState
dataclass
¶
State for protocol-aware routing.
State space: (agent_id, incoming_protocol) Each state represents being at an agent with a specific incoming protocol.
OptimalRoute
dataclass
¶
Result of protocol-aware routing.
Contains the optimal path with protocol sequence and cost breakdown.
path
instance-attribute
¶
Sequence of agent IDs from source to target
protocol_sequence
instance-attribute
¶
Protocol to use on each edge (len = len(path) - 1)
total_cost
instance-attribute
¶
Total path cost: Σ w_e(p) + Σ τ(p_i, p_{i+1}, v_i)
translation_points
instance-attribute
¶
List of (node_id, from_protocol, to_protocol) where translations occur
semantic_loss_estimate
instance-attribute
¶
Estimated semantic loss across all translations (0.0 to 1.0)
edge_costs = field(default_factory=list)
class-attribute
instance-attribute
¶
Individual edge costs
translation_costs = field(default_factory=list)
class-attribute
instance-attribute
¶
Individual translation costs
num_hops = 0
class-attribute
instance-attribute
¶
Number of hops (edges) in the path
num_translations
property
¶
Number of protocol translations (changes).
is_single_protocol
property
¶
Check if route uses only one protocol (no translations).
get_summary()
¶
Get route summary.
RoutingConfig
dataclass
¶
Configuration for Protocol-Aware Dijkstra.
max_hops = 10
class-attribute
instance-attribute
¶
Maximum number of hops allowed
max_translations = 3
class-attribute
instance-attribute
¶
Maximum number of protocol translations allowed
max_semantic_loss = 0.3
class-attribute
instance-attribute
¶
Maximum allowed semantic loss (0.0 to 1.0)
prefer_single_protocol = True
class-attribute
instance-attribute
¶
Prefer routes that don't require protocol translation
single_protocol_bonus = 0.1
class-attribute
instance-attribute
¶
Cost reduction for single-protocol routes
ProtocolAwareDijkstra
¶
Protocol-Aware Dijkstra Algorithm (Algorithm 1 from formal model).
State space: (agent, incoming_protocol) Transition: Consider all outgoing edges and protocol translations Cost: edge_weight + translation_cost
This algorithm finds the optimal route through a multi-protocol mesh, considering both edge weights and protocol translation costs.
Usage
dijkstra = ProtocolAwareDijkstra(graph, compatibility, cost_calculator)
Find optimal route¶
route = dijkstra.find_optimal_route( source="agent1", target="agent3", source_protocol=ProtocolName.MCP, )
if route: print(f"Path: {route.path}") print(f"Cost: {route.total_cost}") print(f"Protocols: {route.protocol_sequence}")
__init__(graph, compatibility_matrix, cost_calculator, config=None)
¶
Initialize Protocol-Aware Dijkstra.
| PARAMETER | DESCRIPTION |
|---|---|
graph
|
Protocol graph with agents and edges
TYPE:
|
compatibility_matrix
|
Protocol compatibility information |
cost_calculator
|
Path cost calculator
TYPE:
|
config
|
Routing configuration
TYPE:
|
find_optimal_route(source, target, source_protocol, target_protocol=None, max_hops=None)
¶
Find optimal protocol-aware route.
Algorithm 1 from formal model: 1. Initialize dist[source, source_protocol] = 0 2. For each state (u, p_in) in priority queue: a. For each neighbor v with edge (u,v): b. For each protocol p_out ∈ Φ(u,v): - cost = dist[u, p_in] + w(u,v, p_out) + τ(p_in, p_out, u) - if cost < dist[v, p_out]: update 3. Return optimal path to (target, target_protocol)
| PARAMETER | DESCRIPTION |
|---|---|
source
|
Source agent ID
TYPE:
|
target
|
Target agent ID
TYPE:
|
source_protocol
|
Protocol at source
TYPE:
|
target_protocol
|
Required protocol at target (optional)
TYPE:
|
max_hops
|
Maximum hops (overrides config)
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
OptimalRoute | None
|
OptimalRoute if path exists, None otherwise |
find_all_routes(source, target, source_protocol, max_routes=5, max_cost_factor=1.5)
¶
Find multiple alternative routes.
| PARAMETER | DESCRIPTION |
|---|---|
source
|
Source agent ID
TYPE:
|
target
|
Target agent ID
TYPE:
|
source_protocol
|
Protocol at source
TYPE:
|
max_routes
|
Maximum number of routes to return
TYPE:
|
max_cost_factor
|
Max cost as factor of optimal (e.g., 1.5 = 50% worse)
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[OptimalRoute]
|
List of routes sorted by cost |
get_statistics()
¶
Get routing statistics.
reset_statistics()
¶
Reset routing statistics.
ProtocolConstrainedBFS
¶
Protocol-Constrained BFS (Algorithm 2 from formal model).
Minimum-hop routing ignoring costs — returns shortest path by hop count with protocol compatibility checks. Uses BFS instead of priority queue.
State space: (agent_id, incoming_protocol)
Usage
bfs = ProtocolConstrainedBFS(graph, compatibility_matrix, cost_calculator) route = bfs.find_shortest_path("agent1", "agent3", ProtocolName.MCP)
__init__(graph, compatibility_matrix, cost_calculator, config=None)
¶
Initialize Protocol-Constrained BFS.
| PARAMETER | DESCRIPTION |
|---|---|
graph
|
Protocol graph with agents and edges
TYPE:
|
compatibility_matrix
|
Protocol compatibility information |
cost_calculator
|
Path cost calculator (for route cost annotation)
TYPE:
|
config
|
Routing configuration
TYPE:
|
find_shortest_path(source, target, source_protocol, target_protocol=None, max_hops=None)
¶
Find shortest path by hop count with protocol constraints.
| PARAMETER | DESCRIPTION |
|---|---|
source
|
Source agent ID
TYPE:
|
target
|
Target agent ID
TYPE:
|
source_protocol
|
Protocol at source
TYPE:
|
target_protocol
|
Required protocol at target (optional)
TYPE:
|
max_hops
|
Maximum hops (overrides config)
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
OptimalRoute | None
|
OptimalRoute with minimum hops, or None if unreachable |
ResilientRouter
¶
Resilient Multi-Protocol Router (Algorithm 3 from formal model).
Three failover strategies: 1. Same-edge protocol fallback — try alternative protocols on current edge 2. Alternate path — reroute using different protocol 3. Gateway insertion — route via gateway nodes
Creates a residual graph excluding failed protocols/agents, then routes on the degraded topology.
Usage
router = ResilientRouter(graph, compatibility_matrix, cost_calculator) route = router.find_resilient_route( "agent1", "agent3", ProtocolName.MCP, failed_protocols={ProtocolName.A2A}, )
__init__(graph, compatibility_matrix, cost_calculator, config=None)
¶
Initialize Resilient Router.
| PARAMETER | DESCRIPTION |
|---|---|
graph
|
Protocol graph
TYPE:
|
compatibility_matrix
|
Protocol compatibility information |
cost_calculator
|
Path cost calculator
TYPE:
|
config
|
Routing configuration
TYPE:
|
find_resilient_route(source, target, source_protocol, failed_protocols=None, failed_agents=None, max_hops=None)
¶
Find route avoiding failed protocols and agents.
Strategy order: 1. Try routing on the residual graph (excluding failures) 2. If direct routing fails, try via gateway nodes
| PARAMETER | DESCRIPTION |
|---|---|
source
|
Source agent ID
TYPE:
|
target
|
Target agent ID
TYPE:
|
source_protocol
|
Protocol at source
TYPE:
|
failed_protocols
|
Protocols to avoid
TYPE:
|
failed_agents
|
Agents to avoid
TYPE:
|
max_hops
|
Maximum hops (overrides config)
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
OptimalRoute | None
|
OptimalRoute on degraded topology, or None if unreachable |