Multi-Agent Setup

Learn how to configure multiple OctoMY™ Agents (robots) to work together, communicate, and coordinate their actions.

Pro Tip

Start with just two Agents to understand the basics of peer communication. Add more Agents once you're comfortable with pairing, messaging, and coordination patterns. Debugging a swarm of robots is much harder than debugging two!

Overview

Multi-Agent setups enable:

Swarm behavior - Robots acting as a group
Task distribution - Divide work among robots
Coordination - Synchronized actions
Fault tolerance - Backup when one fails

                    Multi-Agent Network
    ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
    │   Agent 1   │◄───►│   Agent 2   │◄───►│   Agent 3   │
    │   (Scout)   │     │   (Worker)  │     │   (Worker)  │
    └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
           │                   │                   │
           └───────────────────┼───────────────────┘
                               │
                        ┌──────┴──────┐
                        │     Hub     │ (optional)
                        │ Coordinator │
                        └─────────────┘

Architecture options

Option 1: Peer-to-Peer

Agents communicate directly with each other:

    Agent A ◄──────────► Agent B
        │                    │
        └──────► Agent C ◄───┘

Pros:

No central point of failure
Low latency between peers
Simple for small groups

Cons:

Complex coordination
Each agent needs to know all peers

Option 2: Hub-Coordinated

A Hub manages all agents:

              ┌───────────┐
              │    Hub    │
              └─────┬─────┘
         ┌──────────┼──────────┐
         ▼          ▼          ▼
    ┌────────┐ ┌────────┐ ┌────────┐
    │ Agent A│ │ Agent B│ │ Agent C│
    └────────┘ └────────┘ └────────┘

Pros:

Centralized control
Easier coordination
Better monitoring

Cons:

Single point of failure
Extra latency through Hub

Did You Know?

OctoMY™'s peer-to-peer communication uses the same encrypted protocol as Agent-Remote connections. This means Agents can securely share sensor data and coordinate actions without worrying about eavesdropping, even on untrusted networks.

Option 3: Hybrid

Mix of direct and Hub communication:

              ┌───────────┐
              │    Hub    │
              └─────┬─────┘
                    │
         ┌──────────┼──────────┐
         ▼          ▼          ▼
    ┌────────┐ ┌────────┐ ┌────────┐
    │ Agent A│◄┤ Agent B├►│ Agent C│
    └────────┘ └────────┘ └────────┘
         └──────────────────────┘
           (direct peer links)

Step 1: Configure Agents

Give each Agent a unique identity

Each Agent needs a distinct personality:

Agent 1: "Scout Alpha"   - Exploration role
Agent 2: "Worker Beta"   - Task execution
Agent 3: "Worker Gamma"  - Task execution

Network configuration

Ensure all Agents can reach each other:

┌─────────────────────────────────────────────┐
│  Network Settings - Scout Alpha              │
├─────────────────────────────────────────────┤
│                                              │
│  Local Address: 192.168.1.101                │
│  Listen Port: 8124                           │
│                                              │
│  Discovery:                                  │
│  [✓] Enable multicast discovery              │
│  [✓] Auto-connect to known peers             │
│                                              │
│  Peer Timeout: [30___] seconds               │
│                                              │
└─────────────────────────────────────────────┘

Step 2: Pair Agents together

Agent-to-Agent pairing

On Agent A, go to Pairing
Select Pair with Agent
Discover or enter Agent B's address
Complete handshake on both sides

┌─────────────────────────────────────────────┐
│  Pair with Agent                             │
├─────────────────────────────────────────────┤
│                                              │
│  Discovered Agents:                          │
│                                              │
│  ┌────────────────────────────────────┐     │
│  │ 🤖 Worker Beta                     │     │
│  │    192.168.1.102:8124              │     │
│  │    [Pair]                          │     │
│  ├────────────────────────────────────┤     │
│  │ 🤖 Worker Gamma                    │     │
│  │    192.168.1.103:8124              │     │
│  │    [Pair]                          │     │
│  └────────────────────────────────────┘     │
│                                              │
│  [Refresh] [Manual Address]                  │
│                                              │
└─────────────────────────────────────────────┘

Trust between Agents

Set appropriate trust levels for coordination:

┌─────────────────────────────────────────────┐
│  Agent Trust: Worker Beta                    │
├─────────────────────────────────────────────┤
│                                              │
│  Trust Level:                                │
│  ○ Handshake  - View status only             │
│  ○ Trust      - Receive commands             │
│  ● Depend     - Full coordination            │
│                                              │
│  Permissions:                                │
│  [✓] Share sensor data                       │
│  [✓] Receive plan commands                   │
│  [✓] Coordinate movements                    │
│  [✓] Emergency stop authority                │
│                                              │
│  [Save]                                      │
│                                              │
└─────────────────────────────────────────────┘

Security Consideration

The "Depend" trust level grants significant authority to peer Agents, including emergency stop capability. Only use this level with Agents you control. For third-party or experimental robots, start with "Trust" level and upgrade once you've verified their behavior.

Step 3: Agent communication

Shared data

Agents can share sensor readings:

plan CoordinatedSearch {
    // Read own sensors
    var my_distance = sensors.distance.front

    // Read peer sensor data
    var peer_distance = peers["Worker Beta"].sensors.distance.front

    if my_distance < 30 && peer_distance < 30 {
        // Both see obstacle - coordinate avoidance
        broadcast("obstacle_detected", my_position)
    }
}

Messaging

Send messages between Agents:

plan ScoutAndReport {
    // Scout role
    loop {
        var reading = sensors.distance.front

        if reading < 20 {
            // Found something - notify workers
            send_to("Worker Beta", "target_found", {
                "location": my_position,
                "distance": reading
            })
        }

        delay(100)
    }
}

Receiving messages

Handle incoming messages:

plan WorkerRole {
    // Handle messages from Scout
    on_message("target_found") { msg ->
        log("Target at: " + msg.location)
        navigate_to(msg.location)
    }

    loop {
        // Normal worker behavior
        do_work()
        delay(100)
    }
}

Step 4: Coordination patterns

Leader-Follower

One Agent leads, others follow:

// Leader Agent
plan Leader {
    loop {
        var heading = plan_route()
        broadcast("follow_heading", heading)
        drive_heading(heading)
        delay(100)
    }
}

// Follower Agent
plan Follower {
    var leader_heading = 0

    on_message("follow_heading") { h ->
        leader_heading = h
    }

    loop {
        drive_heading(leader_heading)
        delay(100)
    }
}

Task queue

Distribute tasks among workers:

// Coordinator (Hub or designated Agent)
plan TaskCoordinator {
    var tasks = ["area_a", "area_b", "area_c", "area_d"]
    var available_workers = []

    on_message("worker_ready") { worker ->
        available_workers.add(worker.id)
    }

    on_message("task_complete") { result ->
        log("Task done: " + result.task)
        available_workers.add(result.worker)
    }

    loop {
        if tasks.length > 0 && available_workers.length > 0 {
            var task = tasks.pop()
            var worker = available_workers.pop()
            send_to(worker, "do_task", task)
        }
        delay(100)
    }
}

// Worker Agent
plan Worker {
    init {
        broadcast("worker_ready", {id: my_id})
    }

    on_message("do_task") { task ->
        execute_task(task)
        broadcast("task_complete", {
            worker: my_id,
            task: task
        })
    }
}

Formation

Maintain relative positions:

plan FormationMember {
    var formation_offset = {x: 2, y: 1}  // 2m right, 1m behind leader

    on_message("leader_position") { pos ->
        var target_x = pos.x + formation_offset.x
        var target_y = pos.y + formation_offset.y
        navigate_to(target_x, target_y)
    }

    loop {
        maintain_position()
        delay(50)
    }
}

Step 5: Synchronization

Time sync

Agents can synchronize clocks:

// Synchronize action timing
plan SyncDemo {
    // Wait for sync signal
    wait_for_message("sync_start")

    // Execute at precisely the same time
    var start_time = synced_time()
    execute_at(start_time + 1000) {  // 1 second from now
        do_synchronized_action()
    }
}

Share state across the fleet:

plan SharedState {
    // Local state
    var my_state = "idle"

    // Update fleet about state changes
    function set_state(new_state) {
        my_state = new_state
        broadcast("state_update", {
            agent: my_id,
            state: new_state
        })
    }

    // Track other agents' states
    var fleet_states = {}
    on_message("state_update") { update ->
        fleet_states[update.agent] = update.state
    }

    // Check if all agents are ready
    function all_ready() {
        for agent in fleet_states {
            if fleet_states[agent] != "ready" {
                return false
            }
        }
        return true
    }
}

Step 6: Fault tolerance

Health monitoring

Monitor peer status:

plan HealthMonitor {
    var peer_last_seen = {}
    var timeout = 5000  // 5 seconds

    on_message("heartbeat") { msg ->
        peer_last_seen[msg.from] = now()
    }

    loop {
        // Send our heartbeat
        broadcast("heartbeat", {from: my_id})

        // Check for lost peers
        for peer in peer_last_seen {
            if now() - peer_last_seen[peer] > timeout {
                handle_peer_lost(peer)
            }
        }

        delay(1000)
    }
}

Failover

Handle Agent failures:

plan FailoverWorker {
    var primary_task = null
    var is_backup = true

    on_message("primary_failed") { task ->
        if is_backup {
            log("Taking over task: " + task)
            primary_task = task
            is_backup = false
            execute_task(task)
        }
    }

    on_message("primary_recovered") { _ ->
        if !is_backup {
            log("Primary back, reverting to backup")
            is_backup = true
            primary_task = null
        }
    }
}

Monitoring multi-Agent systems

Fleet dashboard

┌─────────────────────────────────────────────────────────────┐
│  Fleet: Search Team                                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │        Map View                                      │    │
│  │                                                      │    │
│  │     [A]──────→         ← Scout Alpha                │    │
│  │                \                                     │    │
│  │          [B]   [C]     ← Workers Beta/Gamma         │    │
│  │                                                      │    │
│  │     [ ] = Search area    [*] = Target found         │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
│  Status:                                                     │
│  • Scout Alpha: Searching sector 4                           │
│  • Worker Beta: Investigating target at (12, 45)            │
│  • Worker Gamma: En route to sector 6                        │
│                                                              │
│  Messages/sec: 45    Sync drift: <10ms                       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Troubleshooting

Agents can't connect

Issue	Solution
Different networks	Ensure same subnet or use VPN
Firewall blocking	Open port 8124/UDP
Discovery failing	Try manual IP entry

Messages not delivered

Issue	Solution
Not paired	Complete pairing first
Wrong trust level	Set to "Depend" for messaging
Network congestion	Reduce message rate

Coordination issues

Issue	Solution
Time sync drift	Use Hub as time reference
State inconsistency	Add acknowledgments
Race conditions	Use leader election

Best practices

Start small - Test with 2 Agents before scaling
Use heartbeats - Monitor connection health
Handle failures - Plan for Agent disconnection
Log everything - Debug coordination issues
Test offline - Verify behavior without network

Next steps

Central coordination - Hub Setup
Custom processing - Custom Lobes
Communication reference - Protocols