Agent Communication

Agent Communication Library

Multi-agent coordination and message passing.

---

Table of Contents

• Overview
• Loading the Library
• Agent Registration
• Message Passing
• Task Coordination
• Shared State
• Locking and Synchronization
• Configuration
• Patterns

---

Overview

The Agent Communication library (agent_comm.sh) enables multiple AI agents to:

Feature	Description
Registration	Agents announce their presence
Messaging	Send and receive messages
Task Coordination	Claim and complete tasks
Shared State	Read and write shared variables
Locking	Prevent concurrent execution

---

Loading the Library

source "$MAINFRAME_ROOT/lib/agent_comm.sh"

---

Agent Registration

agent_register

Register an agent with the system.

agent_register "worker-1"
# Creates: $AGENT_BASE_DIR/worker-1/

agent_unregister

Remove an agent from the system.

agent_unregister "worker-1"

agent_list

List all registered agents.

agents=$(agent_list)
# Returns JSON array: ["worker-1", "worker-2"]

agent_status

Check agent status.

status=$(agent_status "worker-1")
# Returns: {"ok":true,"data":{"id":"worker-1","status":"active","last_seen":"..."}}

agent_heartbeat

Update agent's last-seen timestamp.

agent_heartbeat "worker-1"

---

Message Passing

agent_send

Send a message to another agent.

agent_send "worker-2" "task" '{"action":"process","file":"data.csv"}'

Parameters:

• $1 - Target agent ID
• $2 - Message type
• $3 - Message payload (JSON)

agent_receive

Receive messages for an agent.

messages=$(agent_receive "worker-1" 10)
# Returns array of messages, max 10

Message Format:

{
  "id": "msg-uuid",
  "from": "sender-id",
  "to": "receiver-id",
  "type": "task",
  "payload": {"action": "process"},
  "timestamp": "2024-01-15T10:30:00"
}

agent_receive_type

Receive messages of specific type.

tasks=$(agent_receive_type "worker-1" "task" 5)

agent_broadcast

Send message to all agents.

agent_broadcast "announcement" '{"message":"System maintenance in 5 minutes"}'

agent_ack

Acknowledge a message (marks as processed).

agent_ack "msg-uuid"

---

Task Coordination

agent_post_task

Post a task for any agent to claim.

task_id=$(agent_post_task "process" '{"file":"data.csv"}')
# Returns task ID

agent_claim_task

Claim an unclaimed task.

if agent_claim_task "$task_id" "worker-1"; then
    # Task claimed successfully
    process_task "$task_id"
else
    # Already claimed by another agent
fi

agent_complete_task

Mark a task as complete.

agent_complete_task "$task_id" '{"result":"success","rows":1000}'

agent_fail_task

Mark a task as failed.

agent_fail_task "$task_id" '{"error":"File not found"}'

agent_list_tasks

List tasks by status.

pending=$(agent_list_tasks "pending")
active=$(agent_list_tasks "active")
completed=$(agent_list_tasks "completed")

agent_get_task

Get task details.

task=$(agent_get_task "$task_id")
# Returns: {"id":"...","type":"process","status":"active","claimed_by":"worker-1",...}

---

Shared State

agent_set_state

Set a shared state variable.

agent_set_state "progress" "50%"
agent_set_state "config" '{"timeout":30}'

agent_get_state

Get a shared state variable.

progress=$(agent_get_state "progress")
# Returns: 50%

config=$(agent_get_state "config")
# Returns: {"timeout":30}

agent_delete_state

Delete a shared state variable.

agent_delete_state "temp_value"

agent_list_state

List all state keys.

keys=$(agent_list_state)
# Returns: ["progress", "config"]

agent_increment_state

Atomically increment a numeric state.

agent_set_state "counter" "0"
agent_increment_state "counter"  # Now 1
agent_increment_state "counter"  # Now 2

---

Locking and Synchronization

agent_lock

Acquire a named lock.

if agent_lock "deploy" "worker-1" 30; then
    # Lock acquired, valid for 30 seconds
    do_deployment
    agent_unlock "deploy" "worker-1"
else
    echo "Lock held by another agent"
fi

agent_unlock

Release a lock.

agent_unlock "deploy" "worker-1"

agent_with_lock

Execute with lock held.

agent_with_lock "critical_section" "worker-1" 60 \
    do_critical_work

agent_wait_for

Wait for a condition.

# Wait for another agent to set a state
agent_wait_for "initialization_complete" "true" 30

---

Configuration

Environment Variables

Variable	Default	Description
AGENT_BASE_DIR	/tmp/mainframe_agents	Base directory for agent data
AGENT_MESSAGE_TTL	3600	Message time-to-live (seconds)
AGENT_TASK_TTL	86400	Task time-to-live (seconds)
AGENT_LOCK_TTL	300	Default lock TTL (seconds)

Directory Structure

$AGENT_BASE_DIR/
├── agents/
│   ├── worker-1/
│   │   ├── status.json
│   │   └── inbox/
│   └── worker-2/
│       ├── status.json
│       └── inbox/
├── tasks/
│   ├── pending/
│   ├── active/
│   └── completed/
├── state/
│   ├── progress
│   └── config
└── locks/
    └── deploy

---

Patterns

Worker Pool Pattern

#!/bin/bash
# Worker agent

source "$MAINFRAME_ROOT/lib/agent_comm.sh"

WORKER_ID="worker-$$"
agent_register "$WORKER_ID"

while true; do
    # Get pending task
    task_id=$(agent_list_tasks "pending" | head -1)
    
    if [[ -n "$task_id" ]] && agent_claim_task "$task_id" "$WORKER_ID"; then
        task=$(agent_get_task "$task_id")
        
        # Process task
        if result=$(process_task "$task"); then
            agent_complete_task "$task_id" "$result"
        else
            agent_fail_task "$task_id" "$result"
        fi
    fi
    
    agent_heartbeat "$WORKER_ID"
    sleep 1
done

Producer-Consumer Pattern

# Producer
for file in /data/*.csv; do
    agent_post_task "process" "$(json_object "file=$file")"
done

# Consumer (in worker)
while task_id=$(agent_list_tasks "pending" | head -1); do
    agent_claim_task "$task_id" "$WORKER_ID"
    # Process...
done

Coordination Pattern

# Leader
agent_set_state "phase" "initialization"
# ... do initialization ...
agent_set_state "phase" "ready"

# Workers
phase=$(agent_get_state "phase")
while [[ "$phase" != "ready" ]]; do
    sleep 1
    phase=$(agent_get_state "phase")
done
# Now proceed

---

Function Reference

Function	Description
agent_register	Register agent
agent_unregister	Remove agent
agent_list	List all agents
agent_status	Get agent status
agent_heartbeat	Update last-seen
agent_send	Send message
agent_receive	Receive messages
agent_broadcast	Broadcast to all
agent_post_task	Create task
agent_claim_task	Claim task
agent_complete_task	Complete task
agent_fail_task	Fail task
agent_set_state	Set shared state
agent_get_state	Get shared state
agent_lock	Acquire lock
agent_unlock	Release lock

---

MAINFRAME · The AI-Native Bash Runtime

Home · AI Agent Integration · Agent Safety