agenticraft_foundation.protocols.graph¶

Protocol graph representation — agent nodes, protocol edges, and the formal model \(G = (V, E, P, \Phi, \Gamma)\).

Protocol graph model: G = (V, E, P, Φ, Γ).

Formal graph-theoretic representation of multi-protocol mesh topology.

The graph represents: - V: Set of agents (vertices). - E: Set of edges between agents. - P: Protocol set {MCP, A2A, CUSTOM, ...}. - Φ: E → 2ᴾ (protocols supported on each edge). - Γ: Capability-protocol affinity function.

`NodeType` ¶

Bases: str, Enum

Type of node in the protocol graph.

Extended taxonomy from graph-theoretic foundations: - AGENT: Generic agent (backward-compatible default) - LLM_AGENT: LLM-powered agent with inference capabilities - TOOL_SERVER: Tool/resource server (MCP servers, API endpoints) - COORDINATOR: Orchestrator/coordinator agent managing workflows - GATEWAY: Protocol gateway/bridge between protocol domains - ROUTER: Routing node for message forwarding - TRANSLATOR: Protocol translator for message conversion

`AgentNode` `dataclass` ¶

Agent node in the protocol graph.

Represents an agent with its capabilities and supported protocols.

`agent_id` `instance-attribute` ¶

Unique agent identifier

`capabilities = field(default_factory=list)` `class-attribute` `instance-attribute` ¶

Agent capabilities (e.g., ['code_execution', 'web_search'])

`protocols = field(default_factory=set)` `class-attribute` `instance-attribute` ¶

Protocols this agent supports

`node_type = NodeType.AGENT` `class-attribute` `instance-attribute` ¶

Type of node

`metadata = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

Additional node metadata

`avg_latency_ms = 50.0` `class-attribute` `instance-attribute` ¶

Average response latency in milliseconds

`reliability = 0.99` `class-attribute` `instance-attribute` ¶

Node reliability score (0.0 to 1.0)

`supports_protocol(protocol)` ¶

Check if agent supports a specific protocol.

`ProtocolEdge` `dataclass` ¶

Edge with protocol capabilities: Φ(u, v).

Represents a connection between two agents with per-protocol weights.

`source` `instance-attribute` ¶

Source agent ID

`target` `instance-attribute` ¶

Target agent ID

`protocols` `instance-attribute` ¶

Φ(u,v) — protocols supported on this edge

`weights = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

wₑ(p) — per-protocol edge weights (cost/latency)

`metadata = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

Additional edge metadata

`bandwidth_mbps = 100.0` `class-attribute` `instance-attribute` ¶

Estimated bandwidth in Mbps

`reliability = 0.99` `class-attribute` `instance-attribute` ¶

Edge reliability score (0.0 to 1.0)

`get_weight(protocol)` ¶

Get edge weight for a specific protocol.

Returns infinity if protocol not supported on this edge.

`supports_protocol(protocol)` ¶

Check if edge supports a specific protocol.

`diversity_index(total_protocols)` ¶

Protocol Diversity Index: PDI(e) = |Pₑ| / |P|.

Measures what fraction of the total protocol set is supported on this edge. Higher values indicate more versatile connections.

PARAMETER	DESCRIPTION
`total_protocols`	Total number of protocols in the mesh \|P\| TYPE: `int`

RETURNS	DESCRIPTION
`float`	PDI in [0.0, 1.0]

`ProtocolGraph` `dataclass` ¶

Multi-protocol mesh graph G = (V, E, P, Φ, Γ).

V: Set of agents (vertices) E: Set of edges between agents P: Protocol set {MCP, A2A, CUSTOM, ...} Φ: E → 2ᴾ (protocols supported on each edge) Γ: Capability-protocol affinity function

This graph enables: - Protocol-aware path finding (Dijkstra with protocol constraints) - Optimal protocol selection based on capability affinity - Semantic-preserving route discovery

`agents = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

V: Set of agent nodes

`edges = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

E: Set of protocol edges

`protocols = field(default_factory=(lambda: {ProtocolName.MCP, ProtocolName.A2A, ProtocolName.CUSTOM}))` `class-attribute` `instance-attribute` ¶

P: Supported protocol set

`add_agent(agent_id, capabilities=None, protocols=None, node_type=NodeType.AGENT, metadata=None, avg_latency_ms=50.0, reliability=0.99)` ¶

Add an agent node to the graph.

PARAMETER	DESCRIPTION
`agent_id`	Unique agent identifier TYPE: `str`
`capabilities`	Agent capabilities TYPE: `list[str] \| None` DEFAULT: `None`
`protocols`	Supported protocols TYPE: `set[ProtocolName] \| None` DEFAULT: `None`
`node_type`	Type of node TYPE: `NodeType` DEFAULT: `AGENT`
`metadata`	Additional metadata TYPE: `dict[str, Any] \| None` DEFAULT: `None`
`avg_latency_ms`	Average latency TYPE: `float` DEFAULT: `50.0`
`reliability`	Node reliability TYPE: `float` DEFAULT: `0.99`

RETURNS	DESCRIPTION
`AgentNode`	The created or updated AgentNode

`remove_agent(agent_id)` ¶

Remove an agent node and all connected edges.

PARAMETER	DESCRIPTION
`agent_id`	Agent to remove TYPE: `str`

RETURNS	DESCRIPTION
`bool`	True if removed, False if not found

`add_edge(source, target, protocols, weights=None, metadata=None, bidirectional=True)` ¶

Add a protocol edge between two agents.

PARAMETER	DESCRIPTION
`source`	Source agent ID TYPE: `str`
`target`	Target agent ID TYPE: `str`
`protocols`	Protocols supported on this edge TYPE: `set[ProtocolName]`
`weights`	Per-protocol edge weights TYPE: `dict[ProtocolName, float] \| None` DEFAULT: `None`
`metadata`	Additional metadata TYPE: `dict[str, Any] \| None` DEFAULT: `None`
`bidirectional`	If True, add reverse edge as well TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`ProtocolEdge`	The created ProtocolEdge

RAISES	DESCRIPTION
`ValueError`	If source or target agent not in graph

`remove_edge(source, target, bidirectional=True)` ¶

Remove an edge between two agents.

PARAMETER	DESCRIPTION
`source`	Source agent ID TYPE: `str`
`target`	Target agent ID TYPE: `str`
`bidirectional`	If True, remove reverse edge as well TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`bool`	True if removed, False if not found

`get_edge(source, target)` ¶

Get edge between two agents.

PARAMETER	DESCRIPTION
`source`	Source agent ID TYPE: `str`
`target`	Target agent ID TYPE: `str`

RETURNS	DESCRIPTION
`ProtocolEdge \| None`	ProtocolEdge or None if not found

`get_neighbors(agent_id, protocol=None)` ¶

Get neighbors of an agent, optionally filtered by protocol.

PARAMETER	DESCRIPTION
`agent_id`	Agent to get neighbors for TYPE: `str`
`protocol`	Optional protocol filter TYPE: `ProtocolName \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[str]`	List of neighbor agent IDs

`get_edges_from(agent_id, protocol=None)` ¶

Get all outgoing edges from an agent.

PARAMETER	DESCRIPTION
`agent_id`	Source agent ID TYPE: `str`
`protocol`	Optional protocol filter TYPE: `ProtocolName \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[ProtocolEdge]`	List of outgoing ProtocolEdges

`is_protocol_valid_path(path, protocol_sequence)` ¶

Check if a path is valid for a given protocol sequence.

Validates: ∀ (u,v) ∈ π: p_i ∈ Φ(u,v)

PARAMETER	DESCRIPTION
`path`	Sequence of agent IDs TYPE: `list[str]`
`protocol_sequence`	Protocol to use on each edge TYPE: `list[ProtocolName]`

RETURNS	DESCRIPTION
`bool`	True if path is valid

`get_agents_by_capability(capability, protocol=None)` ¶

Find agents with a specific capability.

PARAMETER	DESCRIPTION
`capability`	Capability to search for TYPE: `str`
`protocol`	Optional protocol filter TYPE: `ProtocolName \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[AgentNode]`	List of matching AgentNodes

`get_agents_by_protocol(protocol)` ¶

Find agents that support a specific protocol.

PARAMETER	DESCRIPTION
`protocol`	Protocol to filter by TYPE: `ProtocolName`

RETURNS	DESCRIPTION
`list[AgentNode]`	List of matching AgentNodes

`get_statistics()` ¶

Get graph statistics.

RETURNS	DESCRIPTION
`dict[str, Any]`	Dictionary of statistics

`protocol_diversity()` ¶

Compute Protocol Diversity Index for all edges.

RETURNS	DESCRIPTION
`dict[str, float]`	Dictionary mapping edge key "source->target" to PDI value.

`is_reachable(source, target, allowed_protocols=None)` ¶

Check reachability from source to target using allowed protocols.

Implements Theorem 3 from the formal model: protocol-constrained reachability in O(|V| + |E|) via BFS on the protocol subgraph.

PARAMETER	DESCRIPTION
`source`	Source agent ID TYPE: `str`
`target`	Target agent ID TYPE: `str`
`allowed_protocols`	If provided, only traverse edges that support at least one of these protocols. If None, all edges are used. TYPE: `set[ProtocolName] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if target is reachable from source

`reachable_agents(source, allowed_protocols=None)` ¶

Find all agents reachable from source using allowed protocols.

PARAMETER	DESCRIPTION
`source`	Source agent ID TYPE: `str`
`allowed_protocols`	If provided, only traverse edges that support at least one of these protocols. If None, all edges are used. TYPE: `set[ProtocolName] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`set[str]`	Set of reachable agent IDs (excluding source)

`clear()` ¶

Clear all agents and edges.

agenticraft_foundation.protocols.graph¶

NodeType ¶

AgentNode dataclass ¶

agent_id instance-attribute ¶

capabilities = field(default_factory=list) class-attribute instance-attribute ¶

protocols = field(default_factory=set) class-attribute instance-attribute ¶

node_type = NodeType.AGENT class-attribute instance-attribute ¶

metadata = field(default_factory=dict) class-attribute instance-attribute ¶

avg_latency_ms = 50.0 class-attribute instance-attribute ¶

reliability = 0.99 class-attribute instance-attribute ¶

supports_protocol(protocol) ¶

ProtocolEdge dataclass ¶

source instance-attribute ¶

target instance-attribute ¶

protocols instance-attribute ¶

weights = field(default_factory=dict) class-attribute instance-attribute ¶

metadata = field(default_factory=dict) class-attribute instance-attribute ¶

bandwidth_mbps = 100.0 class-attribute instance-attribute ¶

reliability = 0.99 class-attribute instance-attribute ¶

get_weight(protocol) ¶

supports_protocol(protocol) ¶

diversity_index(total_protocols) ¶

ProtocolGraph dataclass ¶

agents = field(default_factory=dict) class-attribute instance-attribute ¶

edges = field(default_factory=dict) class-attribute instance-attribute ¶

protocols = field(default_factory=(lambda: {ProtocolName.MCP, ProtocolName.A2A, ProtocolName.CUSTOM})) class-attribute instance-attribute ¶

add_agent(agent_id, capabilities=None, protocols=None, node_type=NodeType.AGENT, metadata=None, avg_latency_ms=50.0, reliability=0.99) ¶

remove_agent(agent_id) ¶

add_edge(source, target, protocols, weights=None, metadata=None, bidirectional=True) ¶

remove_edge(source, target, bidirectional=True) ¶

get_edge(source, target) ¶

get_neighbors(agent_id, protocol=None) ¶

get_edges_from(agent_id, protocol=None) ¶

is_protocol_valid_path(path, protocol_sequence) ¶

get_agents_by_capability(capability, protocol=None) ¶

get_agents_by_protocol(protocol) ¶

get_statistics() ¶

protocol_diversity() ¶

is_reachable(source, target, allowed_protocols=None) ¶

reachable_agents(source, allowed_protocols=None) ¶

clear() ¶

`NodeType` ¶

`AgentNode` `dataclass` ¶

`agent_id` `instance-attribute` ¶

`capabilities = field(default_factory=list)` `class-attribute` `instance-attribute` ¶

`protocols = field(default_factory=set)` `class-attribute` `instance-attribute` ¶

`node_type = NodeType.AGENT` `class-attribute` `instance-attribute` ¶

`metadata = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

`avg_latency_ms = 50.0` `class-attribute` `instance-attribute` ¶

`reliability = 0.99` `class-attribute` `instance-attribute` ¶

`supports_protocol(protocol)` ¶

`ProtocolEdge` `dataclass` ¶

`source` `instance-attribute` ¶

`target` `instance-attribute` ¶

`protocols` `instance-attribute` ¶

`weights = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

`metadata = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

`bandwidth_mbps = 100.0` `class-attribute` `instance-attribute` ¶

`reliability = 0.99` `class-attribute` `instance-attribute` ¶

`get_weight(protocol)` ¶

`supports_protocol(protocol)` ¶

`diversity_index(total_protocols)` ¶

`ProtocolGraph` `dataclass` ¶

`agents = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

`edges = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

`protocols = field(default_factory=(lambda: {ProtocolName.MCP, ProtocolName.A2A, ProtocolName.CUSTOM}))` `class-attribute` `instance-attribute` ¶

`add_agent(agent_id, capabilities=None, protocols=None, node_type=NodeType.AGENT, metadata=None, avg_latency_ms=50.0, reliability=0.99)` ¶

`remove_agent(agent_id)` ¶

`add_edge(source, target, protocols, weights=None, metadata=None, bidirectional=True)` ¶

`remove_edge(source, target, bidirectional=True)` ¶

`get_edge(source, target)` ¶

`get_neighbors(agent_id, protocol=None)` ¶

`get_edges_from(agent_id, protocol=None)` ¶

`is_protocol_valid_path(path, protocol_sequence)` ¶

`get_agents_by_capability(capability, protocol=None)` ¶

`get_agents_by_protocol(protocol)` ¶

`get_statistics()` ¶

`protocol_diversity()` ¶

`is_reachable(source, target, allowed_protocols=None)` ¶

`reachable_agents(source, allowed_protocols=None)` ¶

`clear()` ¶