API Protocol

HemoStat agents communicate through Redis pub/sub channels and shared state. This document describes the message formats and communication patterns.

Redis Pub/Sub Channels

Health Alert Channel

Channel: hemostat:health_alert

Publisher: Monitor Agent

Subscriber: Analyzer Agent

Message format:

{
  "timestamp": "2025-11-03T10:30:45.123456",
  "agent": "HemoStat-Monitor",
  "type": "health_alert",
  "data": {
    "container": "hemostat-test-api",
    "issues": ["High CPU: 92.5%"],
    "metrics": {
      "name": "hemostat-test-api",
      "status": "running",
      "memory_pct": 45.2,
      "cpu_pct": 92.5,
      "timestamp": "2025-11-03T10:30:45"
    }
  }
}

Remediation Needed Channel

Channel: hemostat:remediation_needed

Publisher: Analyzer Agent

Subscriber: Responder Agent

Message format:

{
  "timestamp": "2025-11-03T10:30:48.456789",
  "agent": "HemoStat-Analyzer",
  "type": "remediation_needed",
  "data": {
    "container": "hemostat-test-api",
    "action": "restart",
    "reason": "CPU contention",
    "confidence": 0.9,
    "metrics": {
      "name": "hemostat-test-api",
      "memory_pct": 45.2,
      "cpu_pct": 92.5
    }
  }
}

Remediation Complete Channel

Channel: hemostat:remediation_complete

Publisher: Responder Agent

Subscriber: Alert Agent

Message format:

{
  "timestamp": "2025-11-03T10:30:53.789012",
  "agent": "HemoStat-Responder",
  "type": "remediation_complete",
  "data": {
    "container": "hemostat-test-api",
    "action": "restart",
    "result": {
      "status": "success",
      "action": "restart",
      "container": "hemostat-test-api"
    }
  }
}

False Alarm Channel

Channel: hemostat:false_alarm

Publisher: Analyzer Agent

Subscriber: Alert Agent

Message format:

{
  "timestamp": "2025-11-03T10:30:48.456789",
  "agent": "HemoStat-Analyzer",
  "type": "false_alarm",
  "data": {
    "container": "hemostat-test-api",
    "reason": "Transient spike, back to normal"
  }
}

Redis Key Structure

Container Stats

Key: hemostat:stats:<container_name>

TTL: 300 seconds

Type: JSON string

{
  "name": "hemostat-test-api",
  "status": "running",
  "memory_pct": 45.2,
  "cpu_pct": 22.1,
  "timestamp": "2025-11-03T10:30:45"
}

Remediation History

Key: hemostat:remediation:<container_name>

TTL: 3600 seconds

Type: JSON string

{
  "last_action": "2025-11-03T10:30:53",
  "count": 1
}

Event Log

Key: hemostat:events:<event_type>

TTL: 3600 seconds

Type: JSON array (max 100 events)

[
  {
    "timestamp": "2025-11-03T10:30:48",
    "agent": "HemoStat-Analyzer",
    "type": "remediation_needed",
    "data": {}
  }
]

Agent Base Class

All agents inherit from HemoStatAgent which provides Redis pub/sub primitives and state management. See the API Reference for complete documentation of:

  • publish_event() - Publish events to Redis channels

  • subscribe_to_channel() - Subscribe to Redis channels

  • start_listening() - Start listening for events

  • get_shared_state() - Read shared state from Redis

  • set_shared_state() - Write shared state to Redis

Error Handling

On Connection Loss

  • All agents implement automatic retry logic

  • Exponential backoff starting at 1 second

  • Maximum 10 retries before failing

On Invalid Message

  • Log error, skip message

  • Continue processing next message

  • No cascading failures

On Remediation Failure

  • Log error details

  • Don’t retry immediately (cooldown applies)

  • Update status to “failed”

Monitoring Communication

View All Events

docker exec hemostat-redis redis-cli SUBSCRIBE "hemostat:*"

View Specific Channel

docker exec hemostat-redis redis-cli SUBSCRIBE "hemostat:remediation_needed"

Check Event Backlog

docker exec hemostat-redis redis-cli KEYS "hemostat:events:*"
docker exec hemostat-redis redis-cli GET "hemostat:events:remediation_complete"

Integration Points

Custom Analyzer

  1. Subscribe to hemostat:health_alert

  2. Implement custom analysis logic

  3. Publish to hemostat:remediation_needed or hemostat:false_alarm

See the Analyzer Agent API documentation for implementation details.

Custom Responder

  1. Subscribe to hemostat:remediation_needed

  2. Implement custom remediation logic

  3. Publish to hemostat:remediation_complete

See the Responder Agent API documentation for implementation details.

Custom Dashboard

  1. Read from hemostat:stats:* for current metrics

  2. Read from hemostat:events:* for history

  3. Subscribe to relevant channels for live updates

See the Dashboard API documentation for implementation details.