Agent Communication Protocol

The Agent Communication Protocol (ACP) is Clawpy's inter-agent messaging infrastructure. It provides a structured, traceable, and auditable message bus that enables agents to delegate work, report outcomes, and share context across the swarm hierarchy.

Architecture

┌──────────────────────────────────────────────────┐
│              ACP Bridge Server                    │
│         (bridge_server.py — 53,416 bytes)         │
├──────────────────────────────────────────────────┤
│                                                   │
│   ┌─────────┐  ┌─────────┐  ┌─────────┐         │
│   │ Agent A  │  │ Agent B  │  │ Agent C  │         │
│   │ (Client) │  │ (Client) │  │ (Client) │         │
│   └────┬─────┘  └────┬─────┘  └────┬─────┘         │
│        │             │             │                │
│   ┌────▼─────────────▼─────────────▼────┐          │
│   │         Event Bus                     │          │
│   │    (bus.py — 12,293 bytes)            │          │
│   └───────────────────────────────────────┘          │
└──────────────────────────────────────────────────┘

Components

| Bridge Protocol | bridge_protocol.py | 13,729 bytes | Message format and serialization | | Task Events | task_events.py | 7,676 bytes | Structured task lifecycle events | | Bridge Events | bridge_events.py | 4,586 bytes | System-level bridge events | | Protocol Spec | protocol.py | 3,959 bytes | Wire protocol definitions |

Message Flow

Task Delegation

When Agent A needs to delegate a sub-task to Agent B:

Agent A                  Bridge Server               Agent B
   │                         │                          │
   │  ── delegate(task) ──>  │                          │
   │                         │  ── route(task) ────────> │
   │                         │                          │
   │                         │  <── accept(ack) ─────── │
   │  <── ack ─────────────  │                          │
   │                         │                          │
   │                         │  <── result(outcome) ─── │
   │  <── result ──────────  │                          │

Bridge Configuration

Each agent's communication capabilities are configured in comms.json:

{
  "reports_to": "cto",
  "can_delegate_to": ["builder_01", "builder_02"],
  "can_receive_from": ["cto", "architect"],
  "communication_mode": "async",
  "max_concurrent_delegations": 3
}

Event Bus Integration

All ACP messages are published to the Plugin Event Bus, enabling:

• Audit logging — Every delegation, result, and escalation is recorded
• Reflection capture — The Reflection Service learns from delegation patterns
• Budget tracking — Token costs are attributed to the delegating agent's budget
• Real-time dashboard — Operators can watch delegation flows in the swarm hierarchy view

Swarm Orchestrator

The Swarm Orchestrator (swarm_orchestrator.py, 26,014 bytes) sits above the ACP and manages complex multi-agent workflows:

• Sequential chains — Architect → Builder → Auditor pipeline
• Parallel fan-out — Split a large task across multiple builders simultaneously
• Conditional routing — Route to different agents based on task analysis
• Escalation paths — When a worker fails, automatically escalate to a senior agent

The orchestrator integrates with the Task Board (task_board.py, 34,355 bytes) which tracks task lifecycle states (queued → assigned → in-progress → review → completed) across the entire swarm.