Agent Communication Protocols

Why Protocols Matter

Without clear communication protocols, multi-agent systems become unpredictable. Agents misinterpret each other's outputs, tasks are dropped or duplicated, and debugging becomes nearly impossible.

A communication protocol defines: message format, handoff criteria, error signaling, and logging requirements.

The Standard Agent Message Format

Every inter-agent message should include:

{
  "from": "agent-id",
  "to": "agent-id",
  "task_id": "uuid",
  "type": "request|result|error|status",
  "payload": {},
  "timestamp": "ISO8601",
  "correlation_id": "links related messages"
}

Correlation IDs allow tracing a task across multiple agents even when messages are processed out of order.

Handoff Criteria

Define explicit completion criteria for every task type. An agent hands off (or completes) when these criteria are met — not based on judgment alone.

Bad handoff criteria: "when the research is done" Good handoff criteria: "when at least 5 sources have been found, each with title, URL, and 100-word summary"

Error Signaling

Agents should fail loudly, not silently. When an agent fails:

1. Log the failure with full context
2. Signal failure to the orchestrator with error type and details
3. Don't attempt to hide or auto-correct failures beyond the agent's defined scope

The orchestrator decides how to handle failures, not the worker.

The Comms Log Pattern

All inter-agent communication should be logged to a central channel. In clawd, every agent message is paired with a post to #comms-log. This creates an auditable trail of all agent activity.

Think of it as structured logging for your agent fleet.