python-sdk/pkg/hanzo-network/DISTRIBUTED_NETWORK.md

Hanzo Distributed Network

This document describes the distributed networking capabilities integrated from hanzo/net into hanzo-network.

Overview

The distributed network extends the base Network class with:

• Automatic peer discovery via UDP broadcast
• Distributed agent execution across nodes
• Cross-node state synchronization
• Load balancing across nodes
• Device capability detection and reporting

Key Components

1. UDP Discovery (udp_discovery.py)

• Broadcasts node presence on the local network
• Discovers other nodes automatically
• Maintains peer health checks
• Supports network interface prioritization

2. gRPC Server (grpc_server.py)

• Handles peer-to-peer communication
• Executes remote agent requests
• Manages distributed state sync
• Currently a simplified implementation for testing

3. Device Capabilities (device_capabilities.py)

• Detects hardware (CPU, GPU, memory)
• Reports compute capabilities (TFLOPS)
• Supports macOS, Linux, and Windows
• Used for intelligent agent placement

4. Distributed Network (distributed_network.py)

• Extends base Network with distributed features
• Manages peer discovery and communication
• Routes agent execution to appropriate nodes
• Synchronizes state across the network

Usage

Basic Example

from hanzo_network import create_distributed_network, create_agent, create_tool

# Create agents
agent = create_agent(
    name="my_agent",
    description="Example agent",
    tools=[...]
)

# Create distributed network
network = create_distributed_network(
    agents=[agent],
    name="my-network",
    node_id="node-1",
    listen_port=5678,
    broadcast_port=5678
)

# Start network
await network.start(wait_for_peers=0)

# Check status
status = network.get_network_status()
print(f"Peers: {status['peer_count']}")

# Execute agent (locally or remotely)
result = await network.run("Do something", initial_agent=agent)

Multi-Node Setup

Run on different machines or terminals:

Node 1:

network1 = create_distributed_network(
    agents=[weather_agent],
    node_id="node-1",
    listen_port=5681,
    broadcast_port=5678  # Same broadcast port
)
await network1.start()

Node 2:

network2 = create_distributed_network(
    agents=[math_agent],
    node_id="node-2", 
    listen_port=5682,
    broadcast_port=5678  # Same broadcast port
)
await network2.start()

The nodes will automatically discover each other and share agent capabilities.

Architecture

┌─────────────────┐     UDP Broadcast      ┌─────────────────┐
│                 │ ◄──────────────────────► │                 │
│   Node 1        │                         │   Node 2        │
│                 │      gRPC Requests      │                 │
│ - Weather Agent │ ◄──────────────────────► │ - Math Agent    │
│ - Discovery     │                         │ - Discovery     │
│ - gRPC Server   │                         │ - gRPC Server   │
└─────────────────┘                         └─────────────────┘
        │                                             │
        └─────────────────┬───────────────────────────┘
                          │
                    State Sync &
                    Agent Registry

Testing

All distributed network tests are passing:

python -m pytest tests/test_distributed_network.py -v

Tests cover:

• Network creation and configuration
• Start/stop operations
• Local agent execution
• Peer discovery simulation
• Router integration

Future Enhancements

The current implementation is a foundation. Future work includes:

1. Real gRPC Implementation: Replace simplified gRPC with full protocol buffers
2. NATS Integration: Add NATS as an alternative discovery mechanism
3. Security: Add authentication and encryption for peer communication
4. Advanced Routing: Implement load balancing and fault tolerance
5. State Replication: Full state synchronization across nodes
6. GPU Support: Leverage GPU detection for ML workload placement

Integration with hanzo-mcp

The distributed network can be used by hanzo-mcp to create agent networks that span multiple machines, enabling:

• Distributed AI workloads
• Peer-to-peer agent collaboration
• Local compute resource utilization
• Reduced API costs through local model execution